Sell pre-orders and backorders
Flint sells two kinds of goods you don't have on the shelf yet, on the same orders, checkouts, and payment links as everything else:
- A pre-order is a sale before a variant's
release_date. The line records the date, and the buyer sees "Pre-order, releases January 3, 2027" in checkout, on the receipt, and in their account. - A backorder is a sale past available stock. The units stock can't cover wait in line, oldest payment first, and Flint fills them the moment stock arrives.
A pre-order of a tracked product that sells past its stock is both. Neither needs a separate app or a second checkout: turn them on in the catalog and inventory, and every way you sell picks them up.
| Step | Calls | Section |
|---|---|---|
| Turn it on | Set a release date, allow backorders | 1. Set up the product |
| Sell | Hosted checkout, payment links, or your own orders | 2. Sell it |
| Charge | Charge now, authorize then capture, or charge at release | 3. Choose when the buyer is charged |
| Wait for stock | Read what's waiting, change a ship date | 4. Track what's waiting |
| Ship | Fulfill units as stock fills them | 5. Fulfill |
| Cancel | Remove units, refund, and give up the place in line | 6. Cancel or refund |
Before you start#
You need a sandbox API key with commerce.products.write for release dates, commerce.inventory.write to allow backorders, commerce.orders.write to sell, fulfill, and change orders, and commerce.refunds.write as well to cancel units with an order edit. Selling past stock needs a variant that tracks inventory and a Location that holds it. A pre-order of a variant that doesn't track inventory needs only the release date.
Amounts are in cents. Replace the example IDs with your own.
1. Set up the product#
Give the variant a release date#
release_date is a calendar date, YYYY-MM-DD. Send it on a new variant, in default_variant or an entry of variants, or add it to an existing one:
curl -X PATCH https://api.withflintpay.com/v1/products/prod_1kmn0aExample/variants/var_1kmn0aExample \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"release_date": "2027-01-03"}'
While the date is after today in your account's time zone, every new order line for the variant is a pre-order: Flint copies the date onto the line as release_date. After the date passes, new lines carry null and sell as ordinary stock. Flint copies the date once, so moving the variant's date later doesn't change lines already sold; change those with the ship date. Send "release_date": null to clear it.
Allow sales past available stock#
Backorders are off until you turn them on for the variant's inventory item:
curl -X PATCH https://api.withflintpay.com/v1/inventory-items/invi_1kmn0aExample \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"backorder": {
"enabled": true,
"limit_quantity": 200,
"expected_ship_date": "2027-01-15"
}
}'
limit_quantitycaps how many units can wait at once across all of the item's Locations, such as the size of your next production run.nullmeans no cap. Concurrent buyers can't push the item past it.expected_ship_dateis the date backordered lines show the buyer: "Backordered, ships about January 15, 2027".nullshows "Backordered" without a date.
backorder is a patch: fields you leave out keep their values. Without backorder.enabled, a pre-order of a tracked variant is held from stock like any other order, and sells out when stock does.
2. Sell it#
Pre-orders and backorders work wherever you sell:
- Hosted checkout and payment links show the pre-order or backorder note on the line. A payment link stays available, with
is_sold_out: false, while the item's backorder limit has room left, even with nothing in stock. - Your own checkout reads the same fields on each order line.
- Orders you create with
POST /v1/ordersbackorder as soon as a payment or delivery selection holds stock.
When a hold begins, Flint takes the stock it has and backorders the rest. A buyer who orders 3 when 1 is on the shelf gets 1 unit held and 2 backordered. When the shortfall is more than the backorder limit has room for, the payment fails with 409 INVENTORY_INSUFFICIENT before anything is charged. The detail's reason is backorder_limit_reached, and available_quantity counts stock plus the room left under the limit.
Each order line reports where it stands:
{
"data": {
"order_id": "ord_1kmn0aExample",
"payment_status": "paid",
"line_items": [
{
"order_line_item_id": "li_1kmn0aExample",
"name": "Field jacket, olive",
"quantity": 3,
"backordered_quantity": 2,
"release_date": null,
"expected_ship_date": "2027-01-15"
}
]
},
"request_id": "req_..."
}
| Field | Meaning |
|---|---|
backordered_quantity | Units of the line waiting for stock. 0 when none are. Lines that track inventory always carry it. |
release_date | The variant's release date when the line was created, if it was still ahead. Otherwise null. |
expected_ship_date | When Flint expects the line to ship. It comes from release_date when the line has one, and otherwise, for backordered units, from the item's backorder.expected_ship_date. It freezes when the order is paid. |
Delivery estimates count from the same dates: a shipping quote's handling_days and transit_days start from the latest release or expected ship date among the order's lines, when it is after today. Backordered and pre-ordered lines has every rule behind these fields.
Some sales never backorder: bundle components, subscription renewals, and reservations you create with the inventory API. They return 409 INVENTORY_INSUFFICIENT when stock falls short, or for a renewal keep waiting in inventory_wait. Affirm doesn't allow pre-orders, so don't offer it for goods that aren't available yet.
3. Choose when the buyer is charged#
A pre-order or backorder is charged when its order is paid, like any order. What changes is how long you can wait between taking the order and collecting the money:
| Option | When the buyer is charged | Use it when |
|---|---|---|
| Charge now | At checkout | Almost always: the buyer's place in line is held, and nothing expires |
| Authorize, then capture | When you capture, within a day | You'll confirm you can supply the order within hours, such as a supplier check |
| Charge at release | When you create and pay the order later | You'd rather take no money until the goods exist, and accept that the buyer can decline |
Charge now#
The default. Hosted checkout and payment links always capture at payment, and so does an order you pay with POST /v1/orders/{order_id}/pay unless you created a manual-capture leg. Once the order is paid in full, its backordered units are firm: they keep their place in line until stock fills them or you remove them, with no deadline. A level with firm backordered units reports available_quantity 0, so a new buyer can't jump ahead of one who already paid.
If the goods never come, give the money back. Buyers see the pre-order or backorder note before they pay, on the line in checkout, and again on the receipt.
Authorize, then capture#
With manual capture, your server creates the order's payment leg with "capture_method": "manual", and paying it places a hold on the buyer's card without collecting. Hosted checkout and payment links don't offer this.
The hold has a short life. Its deadline, authorization_expires_at, is the earlier of the card network's window, usually seven days, and the order's resource guarantee. An order that holds stock, backordered units, or a delivery selection has a guarantee of at most 24 hours from when payment started. So for a shipped or tracked pre-order you have about a day to capture:
- Until you capture, the order is unpaid. Its backordered units are tentative and carry the hold's deadline, and Flint can't create a fulfillment for it.
- Capture before
authorization_expires_atwithPOST /v1/payment-intents/{payment_intent_id}/capture. The order becomes paid and its backordered units become firm. - If the deadline passes, the hold is released, the backordered units give up their place, and collecting the money takes a new payment. Flint sends
payment_intent.authorization_expiringbefore the deadline andpayment_intent.expiredafter it.
Authorize-then-capture fits a short check you finish the same day, not a release weeks away.
Charge at release#
To take no money until the goods exist, save the buyer's card when they sign up for the pre-order. At release, create the order and pay it with the saved card and customer_presence: "absent":
curl -X POST https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/pay \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: preorder-jacket-cus-1kmn0a-release" \
-d '{
"action": "pay",
"payment_source": {
"credential_type": "payment_method",
"payment_method_id": "pm_1kmn0aExample",
"customer_presence": "absent"
},
"expected_outstanding_money": {"amount": 18900, "currency": "USD"}
}'
Read data.order_payment_attempt.status: a declined card also returns 200. Know the trade-offs before you choose it:
- Nothing is reserved before payment. An order that isn't paid holds no stock and no backorder place, so a buyer who signed up first can be filled after one who paid at checkout. Stock that sold out in the meantime returns
409 INVENTORY_INSUFFICIENTat payment. - The bank can decline. A card can expire or run short between sign-up and release. When the attempt fails, ask the buyer to pay while present, such as through a checkout session for the same order.
4. Track what's waiting#
List the paid orders waiting on stock:
curl -G https://api.withflintpay.com/v1/orders \
-H "Authorization: Bearer YOUR_API_KEY" \
-d has_backordered_quantity=true \
-d payment_status=paid
When stock arrives, you don't fill backorders yourself. Every stock change that raises sellable stock, such as an adjustment, a transfer received, an applied count, or a return receipt, fills firm backordered units in the same step, oldest payment first. A line can be filled in part. Flint then lowers each line's backordered_quantity, advances the order's version, and sends order.updated. Tentative units, on orders not yet paid, wait until their order is paid. Sell past available stock shows what each level field does.
Change a ship date#
If a release slips, set a new date on each paid line that's waiting. The order must be paid, and expected_ship_date goes on its own in the request:
curl -X PATCH https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/line-items/li_1kmn0aExample \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expected_ship_date": "2027-02-01"}'
Send null to clear the date. Each change advances the order's version, sends order.updated, and emails the buyer the new date with the shipping update email, unless you send buyer emails yourself or the buyer unsubscribed from shipping updates. If you change the same line again before the email goes out, the buyer gets only the latest date. The date set at payment, and stock filling a backorder, send no email. Change an expected ship date covers the rules.
5. Fulfill#
Backordered units stay in the line's unassigned_quantity, but they can't ship until stock fills them. What you can fulfill now is unassigned_quantity minus backordered_quantity. A fulfillment that claims more returns 409 INVENTORY_INSUFFICIENT with the quantity you can fulfill in details[0].available_quantity.
- Flint waits for the whole delivery. For an order with a paid delivery choice, Flint creates its fulfillments only when every remaining unit is in stock, and never splits the choice into shipments on its own.
- Ship part of it sooner yourself. Create a fulfillment for the units in stock. When the rest arrives, Flint creates fulfillments for the remainder only.
- Release dates don't hold shipping back. Flint doesn't block a fulfillment before
release_dateorexpected_ship_date. A pre-order that stock already covers, or one for a variant that doesn't track inventory, gets its fulfillment right after payment. If it shouldn't leave before launch day, hold the fulfillment withPOST /v1/fulfillments/{fulfillment_id}/hold, then release it on the release date.
Fulfill and ship orders covers packages, tracking, and the buyer's shipping emails.
6. Cancel or refund#
When units won't arrive, or the buyer changes their mind before they ship, take them off the order with an order edit. An edit removes units no fulfillment has claimed, refunds their value, and releases them in one step. It releases backordered units first, so the line gives up its place in line before any stock set aside for it:
curl -X POST https://api.withflintpay.com/v1/orders/ord_1kmn0aExample/edits \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: cancel-preorder-ord-1kmn0a-jacket" \
-d '{
"expected_order_version": 7,
"reason": "out_of_stock",
"remove_line_items": [
{"order_line_item_id": "li_1kmn0aExample", "quantity": 2}
]
}'
The response carries the completed edit, the updated order, and the refund it created. With reason: "out_of_stock", the refund receipt says "Item out of stock". Removing every item emails the buyer that the order was canceled, with the refund due.
Use an edit, not a refund on its own, to cancel units that are waiting. A refund moves money but never releases stock, so refunded units would stay in line and take stock when it arrives. If Flint already created a fulfillment for the units, fail it with release_quantity: true first, which returns them to unassigned_quantity. Once units have shipped, take them back with a Return.
With authorize-then-capture, cancel the hold instead: POST /v1/payment-intents/{payment_intent_id}/cancel releases it without charging the buyer.
Webhooks#
Compare a line's backordered_quantity with the last value you stored to tell how many units just became shippable. Events can arrive more than once and out of order, so deduplicate by event ID and compare the order's version.