AI Deal & Coupon Hunting
The user gives the agent a target (“running shoes under $80, with any coupons applied”). The agent searches the connected merchants, finds candidates that match the price target, applies any available promo codes during cart-building, and completes checkout.
This scenario exercises Firmly’s Promotions API. It’s a strong fit when the agent is positioned as a “savings agent” or when the destination wants to differentiate on price optimization.
Recommended setup
| Choice | Default | Why |
|---|---|---|
| Integration pattern | Deep Link / Headless | Agent needs to inspect cart totals before/after promo application |
| Protocol | MCP or direct REST | MCP tools include apply_coupon natively |
| Flow shape | Single- or multi-product | Either works — apply promos at the cart level |
API sequence
| # | Endpoint | Purpose |
|---|---|---|
| 1 | Browser session | Auth |
| 2 | Discovery search | Find candidates within the price target |
| 3 | Add line item | Add the selected item |
| 4 | Add promo codes | Apply one or more codes to the cart |
| 5 | Get cart | Re-inspect totals — confirm the discount applied |
| 6 (conditional) | Clear promo codes | Only if the code didn’t qualify — remove and try another, then re-read the cart |
| 7 | Set shipping info | Address; populates the shipments array 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 |
| 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 |
Agent logic to consider
- Validate the discount applied. Some codes look valid but fail merchant-side rules (minimum cart value, category exclusions). Always re-read the cart after applying and compare the totals before and after. Depending on how the merchant models the promotion, the change can appear in
sub_total,total, or a discount line rather than only insub_total— comparetotalto be sure the discount actually landed. - Stack carefully. Most merchants disallow stacking. If applying code B silently removes code A, the destination’s agent should detect and surface that.
- Surface the actual savings to the user. “I found this for $69.99 with code SAVE10” is a stronger UX than just placing the order.
Related
- Promotions overview — full endpoint catalog
- Cart lifecycle — cart state and the notices surfaced when a promo expires or doesn’t apply
- AI Shopping Copilot — base flow without promo logic
- Errors & conventions — handling failed promo applications