AI Shopping Copilot
A user describes what they want in natural language. The AI agent searches across connected merchant catalogs, picks a product (or asks the user to choose), assembles the cart, and places the order against the merchant’s native platform.
This is the default agentic commerce scenario. If you’re not sure which scenario fits, start here — every other scenario on this site is a specialization of this one.
Recommended setup
| Choice | Default | Why |
|---|---|---|
| Integration pattern | Deep Link / Headless | Agent has full control of the conversational flow |
| Protocol | MCP or direct REST | MCP lets the agent expose Firmly as tools; REST is universal |
| Auth | Browser session for per-user; S2S for backend | Pick based on where the agent runs |
| Flow shape | Single-product | Multi-product is just steps 3–4 repeated per item |
API sequence
Every call below is a link to the canonical reference. Payload examples live in the API Reference — this page is the order of operations.
| # | Endpoint | Purpose |
|---|---|---|
| 1 | Browser session | Bootstrap auth, get a JWT |
| 2 | Discovery search | Find candidate products across merchants |
| 3 | Get product | Fetch detail + variants for the chosen item |
| 4 | Add line item | Create the cart (implicit) and add the item |
| 5 | Set shipping info | Address; populates shipments array with shipping_method_options |
| 6 | Get shipping availability | (Optional) Delivery dates / time slots / pickup locations |
| 7 | Set shipping method | Pick a method from the shipment’s shipping_method_options |
| 8 | Set consents | Merchant-required consents (terms, warranty acknowledgments) |
| 9 | Set billing info | Billing address |
| 10 | Get payment public key | RSA key for card encryption |
| 11 | Complete order (v2) | Finalize the cart built in steps 4–9 (body: encrypted_card + billing_info) |
For multi-product, repeat steps 3–4 per item (fetch the product, then add the line item). For multi-shipment (same merchant, different shipments), repeat steps 6–7 per shipment_id.
Because this sequence builds the cart across steps 4–9, step 11 finalizes it with complete-order (existing cart). Reach for place-order only on the one-shot path — it creates the cart and places the order in a single call with an items[] array, replacing steps 4–11.
Runnable example
The Advanced Checkout Guide is this sequence as a complete Node script — start there for working code.
Related
- Flows → Single-product purchase — annotated walkthrough
- Flows → Multi-product purchase — iterative cart-building
- Integration patterns — pick where the checkout UI lives
- Errors & conventions — recovery patterns for every call above