marketplace-order-hook — Claude Code skill: order hooks and setup
Guides VTEX order integrations built with Feed v3 or Hook. Use it when a webhook must validate events, fetch order data, and avoid duplicate processing.
npx skills add vtex/skills --skill marketplace-order-hook -a claude-codeWhat marketplace-order-hook does
This skill covers order integrations between a VTEX marketplace and systems such as ERPs, WMS platforms, or fulfillment services. It helps choose Feed v3 for pull-based consumption or Hook for push delivery, then select FromWorkflow for status changes or FromOrders for JSONata-based order filtering.
A Hook notification carries the order ID and state rather than the complete order record. The integration must fetch the full record through GET /api/oms/pvt/orders/{orderId}. The guidance also checks Origin.Account, Origin.Key, and the configured custom header, then uses OrderId, State, and LastChange to prevent duplicate work. A Hook handler that cannot return HTTP 200 within 5000ms will not meet this constraint.
Feed events remain in a queue until they are committed, while Hook delivery requires an available endpoint. The two filter modes cannot share one configuration request; VTEX responds with 409 Conflict when both are used.
What it helps with
- choose Feed v3 or Hook for order updates
- filter events by status or order properties
- retrieve full order data from a notification
- validate VTEX webhook credentials
- deduplicate repeated order events
Example prompts for the agent
- Design a VTEX Hook handler for order status changes.
- Compare Feed v3 with Hook for sending marketplace orders to an ERP.
- Review this webhook handler and add checks for
Origin.Account,Origin.Key, and duplicate events keyed byOrderId,State, andLastChange.
How to install marketplace-order-hook
1Skills CLI (Vercel)
npx skills add vtex/skills --skill marketplace-order-hook -a claude-code2Manually: put the files in place
~/.claude/skills/marketplace-order-hook/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/marketplace-order-hook/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill marketplace-order-hook -a codex2Manually: put the files in place
.agents/skills/marketplace-order-hook/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill marketplace-order-hook -a cursor2Manually: put the files in place
.cursor/skills/marketplace-order-hook/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills marketplace-order-hook2Manually: put the files in place
.github/skills/marketplace-order-hook/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill marketplace-order-hook -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/marketplace-order-hookManually: put the files in place
.devin/skills/marketplace-order-hook/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill marketplace-order-hook -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 marketplace-order-hook
How do I install marketplace-order-hook in Claude Code?
Run npx skills add vtex/skills --skill marketplace-order-hook -a claude-code, then check ~/.claude/skills/marketplace-order-hook/SKILL.md.
What does marketplace-order-hook do?
It guides VTEX order integrations using Feed v3 or Hook. The skill covers delivery choice, event filters, webhook checks, order lookup, and duplicate-safe processing.
How does Feed differ from Hook in marketplace-order-hook?
Feed uses pull delivery and keeps events in a queue until they are committed. Hook pushes notifications to an endpoint that must stay available and return HTTP 200 within 5000ms.
