Vertical Specialist Agent
The user wants something category-specific — “build me an outfit for a wedding”, “a skincare set for sensitive skin”, “a 30-day fitness supplement stack”. The agent does discovery with vertical-aware filters, lets the user pick variants (size, shade, dosage), builds a multi-product cart, and checks out.
This scenario exercises Firmly’s multi-product cart, variant selection, and the merchant adapters’ vertical-specific product data. It’s the canonical “category specialist” shape.
Recommended setup
| Choice | Default | Why |
|---|---|---|
| Integration pattern | Embedded checkout | Variant selectors (size grid, shade swatches) are easier in a rendered UI than pure text |
| Protocol | MCP for conversational AI surfaces; direct REST for headless | MCP exposes Firmly tools the LLM can call iteratively |
| Flow shape | Multi-product purchase | Multiple items, one merchant, one checkout |
Vertical patterns
Firmly preserves each category’s specific product detail and checkout behavior across discovery, cart, and checkout, so the destination doesn’t have to special-case every category itself.
| Vertical | What the product page needs | What the cart / checkout needs |
|---|---|---|
| Apparel | Size grid, color swatches, fit guidance | Standard shipping; sometimes multi-shipment when sizes ship from different warehouses |
| Beauty / skincare | Shade selectors, ingredient lists, sample requests | Standard shipping |
| Fitness supplements | Dosage selectors, flavor variants, bundle pricing | Multi-product cart for stacks; sometimes scheduled re-orders (see Scheduled buying) |
| Flowers | Arrangement size, stem selection, vase options | Recipient address, delivery date, gift message, occasion; scheduled delivery window |
| Furniture | Room dimensions, fabric options, assembly | White-glove delivery scheduling |
| Electronics | Warranties, trade-ins, bundles | Per-line shipping from multiple warehouses |
API sequence
| # | Endpoint | Purpose |
|---|---|---|
| 1 | Browser session | Auth |
| 2 | Discovery search | Find candidates within the vertical |
| 3 | Get product | Fetch full variants — size grid / shade swatches / dosage options |
| 4 | Add line item | Add the first item with the chosen variant |
| 5 | (repeat 3–4 per additional item) | Iterative multi-product build |
| 6 | Get cart | Re-inspect — the user may want to adjust quantities |
| 7 | Set shipping info | Address; populates shipments with shipping_method_options (multi-shipment is common in apparel) |
| 8 | Get shipping availability | (Optional) Delivery dates / time slots / pickup locations |
| 9 | Set shipping method | Pick a method per shipment from its shipping_method_options |
| 10 | … then the standard checkout tail | Get/set consents → set billing info → get payment public key → complete order (v2, with encrypted_card). Because the cart was built above, finalize it with complete-order, not the one-shot place-order. See the single-product flow |
Multi-shipment specifics
For apparel, items frequently ship from different warehouses. The cart response groups them into shipments[]. Walk each shipment_id separately for availability and method selection. See Shipping & Fulfillment.
Related
- Multi-product purchase flow — full walkthrough
- Why Firmly — why platform adapters matter for verticals
- Shipping & Fulfillment — multi-shipment carts
- Cart API guide — multi-step cart with variants