firestarter_create_voucher
Create discount codes buyers can apply to your listings, using percentage off, fixed amount, or free shipping, with optional usage limits and dates. You fund the discount from your proceeds; deep discounts require explicit confirmation.
Instructions
Create a voucher (also called a coupon, promo code, or discount code) that buyers can apply to your listings. Requires a SELLER account with at least one listing — a community-market owner who only recommends other sellers' products has nothing of their own to discount; tiered access (firestarter_set_market_tiers) is the member-reward mechanism for that case. Supports percentage off, a fixed amount off, or free shipping, with an optional start/end date, usage cap, per-buyer limit, minimum order value, and scoping to a single listing. YOU FUND THE DISCOUNT: it comes out of your proceeds, and the platform fee is charged on the discounted total. Dates accept natural language — 'next Friday', 'in 2 weeks' — as well as ISO dates. A discount above 50% requires confirm_deep_discount — a flag attesting that the seller has confirmed that unusually deep number. If the voucher would leave the seller's cheapest orders below the payable minimum the call is rejected with an explanation rather than creating something whose orders would fail at payment.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | The code buyers type, e.g. 'SUMMER20'. 2-64 characters: letters, numbers, dashes or underscores. Case-insensitive; stored uppercase. | |
| max_uses | No | Total redemptions allowed across all buyers. Omit for unlimited. | |
| starts_at | No | When it becomes usable. Natural language ('tomorrow') or ISO. Omit to start immediately. | |
| expires_at | No | When it stops working. Natural language ('next Friday') or ISO. Omit for no expiry. | |
| listing_id | No | Restrict the voucher to one of your listings (lst_...). Omit to apply across all of them. | |
| discoverable | No | Default true: buyer agents can find and auto-apply it. Set false for a targeted code usable only by someone you give it to. | |
| free_shipping | No | Set true for a free-shipping voucher instead of a discount off the item price. | |
| min_order_cents | No | Minimum order subtotal in cents before the voucher applies. | |
| per_buyer_limit | No | How many times one buyer may use it. Omit for unlimited. | |
| discount_percent | No | Percent off, 1-100. Use this OR discount_amount_cents, not both. | |
| confirm_deep_discount | No | Required to create a discount above 50%. Only pass it after the seller has confirmed that exact number. | |
| discount_amount_cents | No | Fixed amount off in cents (e.g. 500 = $5 off). Use instead of discount_percent. |