marketplace-fulfillment — Claude Code skill: how to install
Helps an agent build the seller side of VTEX fulfillment: simulation, order reservations, dispatch, and invoice and tracking calls to OMS.
npx skills add vtex/skills --skill marketplace-fulfillment -a claude-codeWhat marketplace-fulfillment does
This skill walks an agent through the VTEX External Seller protocol on the seller host: answering simulation calls during indexation and checkout, then booking a reservation for each new order and committing it after approval. Once goods ship, the seller calls the marketplace OMS to report invoices and tracking.
The simulation endpoint gets 2.5 seconds; miss that and the offer counts as unavailable. OMS URLs take the marketplace order id. Use the reservation id you returned as orderId and the invoice never reaches the customer's order. An Output invoice records a sale, an Input one a return, and an invoiced order can only be canceled after a return invoice.
Tracking goes in later through a separate PATCH, once the carrier supplies it. Split shipments get one invoice per package, with invoiceValue summed over that package's items only. Catalog sync and order feed handling live in marketplace-catalog-sync and marketplace-order-hook, not here.
What it helps with
- answer VTEX simulation calls with shipping options and stock within 2.5 seconds
- create a reservation on order placement and return its id as
orderId - turn a reservation into a firm order on the
fulfillcall - post invoices and tracking to OMS under the marketplace order id
- issue a separate invoice for each package of a split shipment
Example prompts for the agent
- Write a
POST /pvt/orderForms/simulationhandler for a VTEX External Seller that replies inside 2.5 seconds - Build
POST /pvt/ordersso it creates a reservation, and add the/fulfillhandler for our seller service - Send the OMS invoice for this order, then update tracking with a
PATCHonce the carrier gives us a code
How to install marketplace-fulfillment
1Skills CLI (Vercel)
npx skills add vtex/skills --skill marketplace-fulfillment -a claude-code2Manually: put the files in place
~/.claude/skills/marketplace-fulfillment/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/marketplace-fulfillment/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill marketplace-fulfillment -a codex2Manually: put the files in place
.agents/skills/marketplace-fulfillment/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add vtex/skills --skill marketplace-fulfillment -a cursor2Manually: put the files in place
.cursor/skills/marketplace-fulfillment/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install vtex/skills marketplace-fulfillment2Manually: put the files in place
.github/skills/marketplace-fulfillment/SKILL.md1Skills CLI (Vercel)
npx skills add vtex/skills --skill marketplace-fulfillment -a gemini-cli2Platform CLI
gemini skills install https://github.com/vtex/skills --path skills/marketplace-fulfillmentManually: put the files in place
.devin/skills/marketplace-fulfillment/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add vtex/skills --skill marketplace-fulfillment -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-fulfillment
How do I install marketplace-fulfillment in Claude Code?
Run npx skills add vtex/skills --skill marketplace-fulfillment -a claude-code. The skill file sits at ~/.claude/skills/marketplace-fulfillment/SKILL.md.
What does marketplace-fulfillment do?
It guides an agent through the seller side of VTEX fulfillment: simulation, order placement, dispatch authorization, and OMS invoice and tracking calls, including partial invoices.
Which order id goes into the OMS invoice path?
The marketplace order id, marketplaceOrderId in the VTEX payload. The orderId you returned for the reservation will not match, so the invoice would not attach to the customer order.
