headless-checkout-proxy — Claude Code skill: setup and features
Guides agents when building cart and checkout flows for headless VTEX via a BFF. Ensures safe OrderForm proxying and strict PCI DSS compliance.
npx skills add vtex/skills --skill headless-checkout-proxy -a claude-codeWhat headless-checkout-proxy does
This skill enforces architectural boundaries for headless VTEX storefronts. Every interaction with the Checkout API (/api/checkout/...) must pass through the backend-for-frontend layer. Saving orderFormId or session cookies inside localStorage is forbidden; they must stay inside server-side storage to protect customer profile and address data.
For checkout completion, the rule enforces a three-stage sequence: place order, submit payment, and process transaction. Credit card payloads must bypass the BFF entirely. Browsers send sensitive card fields directly to vtexpayments.com.br, keeping the merchant server outside the scope of strict PCI DSS audits.
Values like orderGroup must travel between flow steps via request bodies rather than req.session. When running multiple BFF replicas, pod restarts or routing mismatches drop in-memory session data, triggering unwanted 400 errors.
What it helps with
- proxy VTEX Checkout API calls safely through a backend layer
- keep orderFormId and session cookies out of browser storage
- route raw credit card data straight to vtexpayments.com.br
- pass orderGroup across checkout steps in multi-replica deployments
Example prompts for the agent
- Write a BFF endpoint to attach shipping data to the current VTEX OrderForm
- Implement the 3-step checkout flow with direct card submission to VTEX payments
- Show how to manage OrderForm ownership cookies on the server
How to install headless-checkout-proxy
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-checkout-proxy -a claude-code2Manually: put the files in place
~/.claude/skills/headless-checkout-proxy/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/headless-checkout-proxy/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-checkout-proxy -a codex2Manually: put the files in place
.agents/skills/headless-checkout-proxy/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-checkout-proxy -a cursor2Manually: put the files in place
.cursor/skills/headless-checkout-proxy/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills headless-checkout-proxy2Manually: put the files in place
.github/skills/headless-checkout-proxy/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-checkout-proxy -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/headless-checkout-proxyManually: put the files in place
.devin/skills/headless-checkout-proxy/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill headless-checkout-proxy -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about headless-checkout-proxy
How to install headless-checkout-proxy in Claude Code?
Run npx skills add vtex/skills --skill headless-checkout-proxy -a claude-code. The file will be placed in ~/.claude/skills/headless-checkout-proxy/SKILL.md.
What does headless-checkout-proxy do?
It provides rules for building VTEX cart and checkout integrations through a dedicated BFF. It governs OrderForm state transitions, input validation, and payment security boundaries.
Why do credit card details bypass the BFF?
PCI DSS isolation requires keeping cardholder data off merchant servers. The client sends payment details directly to vtexpayments.com.br, while the BFF handles only order placement and final callback processing.
