firestarter_execute
Start a purchase by finding products from a natural-language request, verifying sellers, and quoting shipping. Returns ranked options awaiting approval — no payment until approved.
Instructions
Start a purchase. Step 1 of the buy flow: it finds products matching a natural-language request (or pins to an exact listing), verifies the seller, computes real pricing + shipping, and returns ranked OPTIONS that are AWAITING APPROVAL — it does NOT pay yet. Full flow: firestarter_execute (find/price) → firestarter_approve (confirm + pay) → firestarter_receipt (proof of payment) and firestarter_track_order (delivery). Each purchasable option lists real DELIVERY OPTIONS (Standard / Express / Same-Day with prices and ETAs); the delivery speed is the buyer's choice, selected at approval via shipping_option_index (firestarter_shipping_options re-fetches or previews a speed's total; firestarter_shipping_estimate quotes shipping on a listing BEFORE any purchase starts). No budget, address, or payment method is needed to call this — a card is requested only at the very end, after the buyer approves; browsing, quoting, and comparing shipping never require one. A saved shipping address is used automatically — the buyer's street, zip, and phone are already on file, and the response's default_delivery shows a masked view of the ship-to. A new address matters only when none is saved or the order ships somewhere else; a saved address_id (from firestarter_addresses) is accepted in place of a re-typed address. When the buyer's location (country, and city if known) is provided, results are localized to their country so a buyer in Kenya sees locally-deliverable options first instead of an empty or US-only list. An exact listing id (lst_..., e.g. from a firestarter.network/l/ share link or firestarter_catalog_search) can be passed as listing_id to skip search and pin to that exact product. Results may include browse-only options (external, or not buyable right now) that can't be approved — each carries a link that can be shared instead. auto_pay presumes the buyer's explicit prior authorization to buy without a confirmation step.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| request | Yes | Natural language description of what to buy (e.g. 'specialty coffee beans under $30'). This is the only required field — call with just this and refine later. | |
| auto_pay | No | If true, automatically pay for the best option within budget WITHOUT a confirmation step — only when the buyer explicitly pre-authorized it. If false (default), options are returned for approval. | |
| location | No | Where the buyer is. Pass this whenever you know it (from the conversation, profile, or a prior message) even without a full delivery address — it makes search location-aware so local marketplaces are shown first. | |
| priority | No | Optimization priority: cost (cheapest), speed (fastest delivery), quality (best rated). Default cost — shipping is quoted and shipped at the cheapest carrier rate unless the buyer asks for speed/quality. | |
| address_id | No | A saved address id (addr_...) to ship to, from firestarter_addresses. Optional — omit to use the buyer's default saved address. Localizes search + shipping to that destination. | |
| budget_max | No | Maximum budget in USD. Optional — omit to see all options regardless of price. | |
| listing_id | No | Exact Firestarter listing id (lst_...) to buy — from a listing or a share link (firestarter.network/l/<id>). Pins the purchase to that listing, skipping product search. Always pass it when you have one. | |
| requested_by | No | Who asked for this purchase, when relaying someone else's request (e.g. a teammate in chat). Stored as execution metadata so the buyer's dashboard can attribute the order. Integrations set this programmatically; pass it whenever you know the requester. | |
| voucher_code | No | A discount code the buyer already has (voucher / coupon / promo code). Only meaningful for a code the buyer supplied — the best publicly available voucher is applied automatically, so searching for codes is unnecessary; this field exists for private or targeted codes that auto-apply cannot find. If the code can't be used the order still proceeds at the best price available, and the response explains why it didn't apply. | |
| hold_at_shipped | No | TEST MODE ONLY (fs_test_ keys): park the order at 'shipped' instead of auto-delivering it ~2s later. The mock shipment, tracking number and 'shipped' status all still happen; only the auto-deliver timer is skipped, so the order can be inspected mid-flight and then delivered explicitly with firestarter_confirm_delivery. Ignored on a live key. Use it to stage a shipped-but-not-delivered order for QA. | |
| delivery_address | No | Optional shipping address — pass EITHER a single-line string (e.g. "123 Main St, Austin, TX 78701, US") OR an object { name?, street1, street2?, city, state?, zip?, country? } (country is an ISO code, e.g. US/TH; defaults to US). The buyer's saved default address is used automatically at approval, so only pass one here if they have none saved or want it shipped elsewhere; prefer a saved address_id. A COMPLETE address (ZIP + state for US/CA/AU) lets execute quote a REAL carrier rate up front instead of the flat placeholder; a partial or odd-shaped address is accepted anyway (never rejected for shape) and the response's `needs_more` names exactly what to collect. | |
| hold_at_delivered | No | Keep the escrow hold in place after delivery, instead of releasing it the moment the order is marked delivered, so the order can still be disputed — which is what firestarter_disputes needs to open a dispute at all. The order still ships and delivers normally; only the payout is held, on the same inspection window a live order gets. REQUIRES the organization's test mode to be ON as well as a test key: a test key on its own runs the mock sandbox, which never creates an escrow hold for this to act on, and the API now refuses the flag there (HOLD_AT_DELIVERED_UNAVAILABLE) rather than accepting a purchase whose hold would be silently dropped. Inert on a live key, where escrow already holds for the full window. |