Cursor rule
Apply when implementing fulfillment, invoice, or tracking logic for VTEX marketplace seller connectors. Covers the External Seller fulfillment protocol: fulfillment simulation (checkout and indexation), order placement with reservation id, order dispatch (authorize fulfillment), OMS invoice and tracking APIs, and…
Cursor rule
Apply when implementing order integration hooks, feeds, or webhook handlers for VTEX marketplace connectors. Covers Feed v3 (pull) vs Hook (push), filter types (FromWorkflow and FromOrders), order status lifecycle, payload validation, and idempotent processing. Use for building order integrations between VTEX…
Cursor rule
Apply when implementing retry logic, rate limit handling, or resilience patterns in VTEX API integrations. Covers VTEX rate limit headers (X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After), 429 status handling, exponential backoff with jitter, circuit breaker patterns, and request queuing. Use for any VTEX…
Cursor rule
Composite skill for the masterdata track. Apply when deciding whether VTEX Master Data is the right storage for a given workload, designing JSON Schemas with v-indexed, v-cache, v-security, and v-triggers, planning entity capacity and lifecycle, or auditing existing Master Data usage. Covers when to use MD versus…
Cursor rule
Apply when deciding whether VTEX Master Data is the right storage for a given workload, designing JSON Schemas with v-indexed, v-cache, v-security, and v-triggers, planning entity capacity and lifecycle, or auditing existing Master Data usage. Covers when to use MD versus Catalog, OMS, VBase, or external databases…
Cursor rule
Composite skill for the payment track. Apply when implementing asynchronous payment methods (Boleto, Pix, bank redirects) or working with callback URLs in payment connector code. Covers undefined status response, callbackUrl notification, X-VTEX-signature validation, sync vs async handling, correct delayToCancel…
Cursor rule
Apply when implementing asynchronous payment methods (Boleto, Pix, bank redirects) or working with callback URLs in payment connector code. Covers undefined status response, callbackUrl notification, X-VTEX-signature validation, sync vs async handling, correct delayToCancel configuration for each async method, and…
Cursor rule
Apply when implementing idempotency logic in payment connector code or handling duplicate payment requests. Covers paymentId as idempotency key, payment state machine transitions, retry semantics for cancellation and refund operations, and requestId handling. Use for preventing duplicate charges and ensuring correct…
Cursor rule
Apply when handling credit card data, implementing secureProxyUrl flows, or working with payment security and proxy code. Covers PCI DSS compliance, Secure Proxy card tokenization, sensitive data handling rules, X-PROVIDER-Forward-To header usage, custom token creation, and the constraint that Secure Proxy applies…
Cursor rule
Apply when designing or implementing a Payment Connector in VTEX IO. Covers PPF implementation, TypeScript 3.9.7 builder-hub constraints and safe dependency resolutions, configuration.json schema validation, PaymentProviderService clients wiring, Secure Proxy scope (authorize-only), ExternalClient vs…
Cursor rule
Apply when implementing a VTEX Payment Provider Protocol (PPP) connector or working with payment/connector endpoint files. Covers all nine required endpoints: Manifest, Create Payment, Cancel, Capture/Settle, Refund, Inbound Request, Create Auth Token, Provider Auth Redirect, and Get Credentials. Use for building or…
Cursor rule
Composite skill for the sales-app track. Apply when building, customizing, or deploying extensions for VTEX Sales App. Covers the complete 7-step workflow from prerequisite checks through code generation to deployment, including extension points (cart, PDP, menu), React hooks (useCart, usePDP, useCartItem…
Cursor rule
Code generation templates for Sales App extensions — simple, hook-based, API (no auth), IO Proxy (secure), Direct Auth (insecure), CSS stylesheet, and index.tsx with defineExtensions. Use when generating or scaffolding extension code.
Cursor rule
UX writing rules (sentence case) and Phosphor Icons usage for Sales App extensions. Load when writing JSX text content or when an extension needs icons. CSS-related design rules (tokens, typography, spacing, responsive) are inlined directly in the CSS template — see code-templates-and-patterns.md.
Cursor rule
Discovery flow for identifying what Sales App extension to build, including use case detection keywords, targeted follow-up questions per use case, and API authentication strategy decision tree. Use during Step 1 (Discovery) of the workflow.
Cursor rule
Markdown template for the docs/ .md file generated in Step 4. Load when writing extension documentation to ensure all required sections are covered.
Cursor rule
Complete reference for Sales App extension points, React hooks, and TypeScript types. Use when choosing where to render an extension, which hooks to use, or looking up type definitions for CartItem, ProductSku, Totalizers, and related types.
Cursor rule
Commands and instructions for local development, building, and deploying Sales App extensions via FastStore WebOps. Use during Steps 4 and 5 of the workflow.
Cursor rule
Sales App extensions run inside a sandboxed environment enforced by @vtex/fsp-analyzer. These rules are checked at preBuild and preDev hook time. The AI must validate all generated code against these rules before presenting it to the user.
Cursor rule
Apply when building, customizing, or deploying extensions for VTEX Sales App. Covers the complete 7-step workflow from prerequisite checks through code generation to deployment, including extension points (cart, PDP, menu), React hooks (useCart, usePDP, useCartItem, useCurrentUser, useExtension), TypeScript types…
Cursor rule
Apply when building VTEX IO admin-facing React interfaces under the admin builder. Covers VTEX Styleguide and Shoreline usage, admin page composition, data-heavy admin interactions, and keeping administrative interfaces consistent with the VTEX Admin environment. Use for settings pages, moderation tools, dashboards…
Cursor rule
Apply when defining or changing the contract of a VTEX IO app through manifest.json, builder declarations, dependencies, peerDependencies, billingOptions, and app identity. Covers how the app declares capabilities and integration boundaries. Use for scaffolding apps, splitting responsibilities across apps, or fixing…
Cursor rule
Apply when defining, validating, or consuming VTEX IO app settings. Covers settingsSchema, app-level configuration boundaries, and how backend or frontend code should depend on settings safely. Use for merchant-configurable behavior, settings forms, or reviewing whether settings belong in app configuration rather than…
Cursor rule
Apply when improving VTEX IO Node or .NET services for latency, throughput, and resilience: in-process LRU, VBase, stale-while-revalidate, AppSettings loading, request context, parallel client calls, and avoiding duplicate work. Covers application-level performance patterns that complement edge/CDN caching. Use when…