Smart Gifting & Occasion Shopping
The user wants to send a gift — “a birthday gift for my mom under $75, with gift wrap, by Friday”. The agent searches across merchants, picks an item that matches the budget and occasion, adds gift wrap as an addon, optionally bundles a digital gift card, sets the recipient’s address, and completes checkout via the user’s express wallet.
This is the single richest scenario in terms of Firmly capabilities touched in one flow: discovery, addons, gift card line items, recipient address, and express checkout.
Recommended setup
| Choice | Default | Why |
|---|---|---|
| Integration pattern | Embedded checkout | Wallet sheet handoff (Google Pay) needs an iframe context |
| Protocol | MCP or direct REST | MCP tools cover the discovery + cart + addon flow natively |
| Flow shape | Single- or multi-product depending on bundle | A standalone gift = single; gift + gift card = multi |
API sequence
| # | Endpoint | Purpose |
|---|---|---|
| 1 | Browser session | Auth |
| 2 | Discovery search | Find gift candidates matching budget + occasion |
| 3 | Get product | Variants + check that addons (e.g., gift wrap) are offered |
| 4 | Add line item | Add the gift |
| 5 | Add addon | Add gift wrap, gift message, warranty, or other addon the merchant offers |
| 6 | (optional) Add line item | Add a digital gift card as a separate line item |
| 7 | Set shipping info | Recipient’s address, not the user’s; populates shipments with shipping_method_options |
| 8 | Get shipping availability | (Optional) Delivery dates / time slots / pickup locations |
| 9 | Set shipping method | Pick a method from the shipment’s shipping_method_options (often expedited for occasions) |
| 10 (conditional) | Get consents → Set consents | If the merchant requires consents; skipping them makes complete-order return RequiredConsentsNotSigned (412) |
| 11 | Set billing info | Buyer’s billing address (often differs from shipping) |
| 12 | Express checkout — Google Pay / PayPal / Click to Pay | Wallet handoff. See Smart Payment Selection → Path B for the express-wallet sequence |
Key agent considerations
- Recipient ≠ buyer. Shipping address is the recipient; billing address is the buyer’s. The agent must collect both — and ask the user to confirm the recipient’s address before placing the order.
- Gift wrap is merchant-specific. Not every merchant offers it. Check
cart.addons.offersfor the available add-ons before promising the user gift wrap. - Gift message length limits vary. A gift message is carried as an addon property when the merchant’s gift-wrap addon supports it — set it through the addon, not on the cart. See Add addon for the addon payload. Truncate cleanly if the user’s message exceeds the merchant’s limit.
- Delivery date promises. “By Friday” is a shipping-method choice plus the merchant’s processing time. Don’t promise a date based on shipping speed alone — confirm against the merchant’s lead time.
- Gift cards. A digital gift card is just another line item. Multi-product flow handles both physical + digital in one cart and one order — see Wallet pass purchase.
Related
- Addon management — gift wrap, warranties
- Wallet pass purchase recipe — digital pass / gift card pattern
- Smart payment selection — wallet checkout paths
- Multi-product purchase flow — bundling gift + gift card