Edit a paid order
A buyer emails to change the size, drop one item, or add another before the order ships. An order edit makes that change on the paid order itself. In one request Flint removes the units, adds the new lines, releases and commits their stock, and refunds or collects the difference. The order keeps one ID, one receipt history, and one activity log, so you don't cancel it and sell again.
| You want to | Send | Section |
|---|---|---|
| See the money before you commit | A preview | 1. Preview the edit |
| Take units off | remove_line_items | 2. Remove units |
| Swap a size or add an item | remove_line_items and add_line_items | 3. Swap or add items |
| Charge for an upgrade | balance_due_behavior: "collect" | 4. Collect a balance |
| Fix a refund that failed | The edit's retry | 6. Retry a failed refund |
Before you start#
You need a sandbox API key with commerce.orders.read for previews, and both commerce.orders.write and commerce.refunds.write to edit, because an edit changes the order and moves money.
The order must be paid, and the units you remove must not be in a fulfillment yet. An order that isn't paid takes ordinary line item changes instead. Amounts are in cents. Replace the example IDs with your own.
1. Preview the edit#
A preview calculates the edit without changing anything. It holds no stock and reserves no money, so it needs no Idempotency-Key:
curl -X POST https://api.withflintpay.com/v1/order-edit-previews \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order_id": "ord_01KEZF7C00JBKMARG3P06Z224B",
"remove_line_items": [
{"order_line_item_id": "li_01KEZF7C004XP0V220YVMGQ354", "quantity": 1}
]
}'
{
"data": {
"order_id": "ord_01KEZF7C00JBKMARG3P06Z224B",
"based_on_order_version": 7,
"calculated_at": "2026-11-06T00:00:00Z",
"remove_line_items": [
{
"order_line_item_id": "li_01KEZF7C004XP0V220YVMGQ354",
"quantity": 1,
"removable_quantity": 2,
"refund_money": {"amount": 1200, "currency": "USD"},
"total_money": {"amount": 1200, "currency": "USD"}
}
],
"add_line_items": [],
"charge_refunds": [],
"removed_total_money": {"amount": 1200, "currency": "USD"},
"added_total_money": {"amount": 0, "currency": "USD"},
"refund_money": {"amount": 1200, "currency": "USD"},
"amount_due_money": {"amount": 0, "currency": "USD"}
}
}
removable_quantityis how many units of the line can still come off.total_moneyis the removed units' value at the price the buyer paid, including their share of discounts and tax.refund_moneyis the part that goes back to the buyer after paying for any added items.amount_due_moneyis what the buyer would owe when the added items cost more than what came off. At most one ofrefund_moneyandamount_due_moneyis above zero.based_on_order_versionis the orderversionthe preview read. Send it asexpected_order_versionwhen you commit.
Show the buyer refund_money or amount_due_money before you commit. A preview is an estimate: the commit calculates again.
2. Remove units#
Send the same removals to the order's edits route, with the order version you read and an Idempotency-Key:
curl -X POST https://api.withflintpay.com/v1/orders/ord_01KEZF7C00JBKMARG3P06Z224B/edits \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: edit-ord_01KEZF7C00JBKMARG3P06Z224B-1" \
-d '{
"expected_order_version": 7,
"reason": "requested_by_customer",
"note": "Buyer asked to drop the second mug by email",
"remove_line_items": [
{"order_line_item_id": "li_01KEZF7C004XP0V220YVMGQ354", "quantity": 1}
]
}'
The response is 201 with the order_edit, the updated order, and the refunds the edit created. In one step, Flint:
- Checks
expected_order_versionand that the units are still unassigned. If the order changed or a fulfillment claimed the units first, nothing changes: read the order and build the edit again. - Records the edit with the values it calculated. They never change afterward, even if prices or tax rules do.
- Releases the stock behind the removed units. Units still on backorder go first, then committed ones. Nothing physical moves.
- Adds the activity row and saves the refund to create.
Flint then creates the refund. If it can't finish during the request, refunds is [], the edit still stands, and Flint keeps trying and sends refund.created once the refund exists. Repeating the request with the same Idempotency-Key returns the same edit and never edits the order twice.
The line keeps its original quantity and price. The removed units count as final in the order's fulfillment_status, like canceled ones, and the value removed adds up in settlement_amounts.removed_money.
Units that come off for a reason you should record go in reason, which takes any refund reason. With out_of_stock, the refund receipt says "Item out of stock". note is for your team, up to 500 characters, and buyers never see it.
3. Swap or add items#
To swap a size before shipping, remove the old units and add the new variant in the same edit. Preview it first with both lists:
curl -X POST https://api.withflintpay.com/v1/order-edit-previews \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"order_id": "ord_01KEZF7C00JBKMARG3P06Z224B",
"remove_line_items": [
{"order_line_item_id": "li_01KEZF7C004XP0V220YVMGQ354", "quantity": 1}
],
"add_line_items": [
{"type": "variant", "variant_id": "var_01KEZF7C00Q0Y1Z9G7F3J6V2DD", "quantity": 1}
]
}'
add_line_items takes lines in the same shape as adding a line to an open order: a catalog variant, a bundle, or a custom item with a delivery requirement. Then commit the same lists to POST /v1/orders/{order_id}/edits with expected_order_version from the preview.
The removed value pays for the added lines first, in request order, and whatever is left goes back to the buyer. The credit stays with the payment that made it: if the buyer later returns the new item, its refund goes back to the card or gift card that paid for the units it replaced.
How Flint prices what's added:
- Price. Added lines are priced like any new line: the catalog, a price list, or the customer's price sets the unit price. Existing lines keep their sale prices.
- Promotions. Flint doesn't evaluate promotions again, so an added line's
discount_moneyis0, and a removal doesn't take away a discount the rest of the order earned. - Stock. Stock must cover each added line, or the variant must allow backorders. Otherwise the edit returns
409 INVENTORY_INSUFFICIENTat the firstadd_line_items[i]it can't cover. Stock that the removed units free goes to older backorders first, so it doesn't count toward the added lines. - Fulfillment. Added lines don't join the order's delivery selection. Their units become unassigned
fulfillment_quantitiesfor you to fulfill yourself. Each new line carries theorder_edit_idthat added it.
4. Collect a balance#
By default, the removed value and released charges must cover the added items. An upgrade that costs more returns 409 LIMIT_EXCEEDED with reason order_edit_balance_due, and maximum_money is the most you can add. To charge the buyer the difference instead, send balance_due_behavior: "collect" with the preview's amount_due_money:
curl -X POST https://api.withflintpay.com/v1/orders/ord_01KEZF7C00JBKMARG3P06Z224B/edits \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: edit-ord_01KEZF7C00JBKMARG3P06Z224B-upgrade" \
-d '{
"expected_order_version": 7,
"balance_due_behavior": "collect",
"expected_amount_due_money": {"amount": 1800, "currency": "USD"},
"remove_line_items": [
{"order_line_item_id": "li_01KEZF7C004XP0V220YVMGQ354", "quantity": 1}
],
"add_line_items": [
{"type": "variant", "variant_id": "var_01KEZF7C00Q0Y1Z9G7F3J6V2DD", "quantity": 1}
]
}'
The edit starts pending with a payment_intent_id for the balance. Nothing on the order changes until it's paid: Flint holds stock for the added items, the removed units can't join a fulfillment, and the order stays paid. Confirm the payment intent with the buyer's card. For a card the buyer saved for later use, while they're away:
curl -X POST https://api.withflintpay.com/v1/payment-intents/pi_01KEZF7C00EDITBALANCE0001/confirm \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: confirm-edit-balance-ord_01KEZF7C00JBKMARG3P06Z224B" \
-d '{
"payment_source": {
"credential_type": "payment_method",
"payment_method_id": "pm_1kmn0aExample",
"customer_presence": "absent"
}
}'
When the payment succeeds, the edit becomes completed, Flint applies the changes, and sends order_edit.completed. Fulfill the added items then, not before. A decline leaves the edit pending, so retry with another card. To back out, POST /v1/orders/{order_id}/edits/{order_edit_id}/cancel. An unpaid edit cancels itself 24 hours after it was created, and either way the original order is left as it was.
Two details on the balance:
- The balance is frozen in
amount_due_money, including tax, and is charged to cards only, captured at once. - For USD orders, Flint waives a balance under 50 cents, such as a tax-rounding difference on an equal swap, so no payment is needed. The preview and edit report it in
small_balance_adjustment_money.
Collect a balance on an edit covers payment actions, expiry, and every cancellation reason.
5. Tax, shipping, and charges#
- Tax on removed units goes back in proportion, as it does for a quantity refund. Flint rounds each unit's share the same way, so separate one-unit edits add up to the line's total.
- Tax on added lines is calculated through the order's tax settings at the order's destination. Added lines aren't in the delivery selection, so automatic tax calculates them from your legal origin. Tax already committed on the order's other lines doesn't change.
- Shipping and other charges stay as they are. Flint doesn't requote delivery for an edit. To give back a delivery fee, such as when the edit leaves nothing to ship, list it in
charge_refundswith itsorder_charge_id. Leave outamount_moneyto release everything still refundable on the charge. Released charges count toward added items before anything is refunded.
6. Retry a failed refund#
A refund the edit created can fail like any refund, for example when the buyer's card was closed. The edit stays completed and the units stay removed. Flint holds the money for that edit, so POST /v1/refunds can't use it: retry from the edit.
The edit's unrefunded_money says what it still owes, and its supported_actions contains retry once nothing is in progress:
curl -X POST https://api.withflintpay.com/v1/orders/ord_01KEZF7C00JBKMARG3P06Z224B/edits/oed_01KEZF7C00R4Q8T5N2M6W1XV3C/retry \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: retry-oed_01KEZF7C00R4Q8T5N2M6W1XV3C-1"
Send destinations in the body to send the money somewhere else, such as store credit. A retry while a refund is still pending returns 409 ACTION_NOT_ALLOWED with reason in_progress.
What an edit can't change#
| You have | Do this instead |
|---|---|
| Units in a fulfillment that hasn't shipped | End the fulfillment with fail and release_quantity: true, which returns the units to unassigned_quantity, then edit the order. See Cancel, fail, and try again. |
| Units that shipped or were delivered | Take them back with a Return. |
| Lines with nothing to fulfill: services, digital items, gift cards, and event tickets | Refund them with POST /v1/refunds. A ticket refund also voids the ticket; see Refunds and seats. |
| Lines to add that Flint can't fulfill: gift cards, subscribe-and-save lines, services, digital items, or anything on an event ticket order | Sell them on a new order. These return 400 INVALID_REQUEST with detail NOT_ALLOWED at add_line_items[i]. |
| An order a subscription or a Return created | Change the subscription, or the Return. The edit returns 409 ACTION_NOT_ALLOWED with reason subscription_owned or return_owned. |
| An order an invoice collected | Correct it with a credit note. The edit returns 409 RESOURCE_IN_USE. |
| A disputed payment | Wait for the dispute. The edit returns reason payment_disputed. |
| An unresolved inventory exception | Resolve it first. The edit returns reason not_offered. |
One order can have one edit waiting for payment at a time. A second returns 409 ACTION_NOT_ALLOWED with reason order_edit_pending.
What the buyer and your records show#
- The buyer gets an email listing what was added or removed, or confirming the cancellation if the edit removed every item, with any refund due. They also get the usual refund receipt when the refund succeeds. Your
notestays private. - The activity log gets an
order_editedrow. Its refund gets its ownrefundrow, and a failure addsrefund_failed. An edit that collects a balance addsorder_editedand apaymentrow when it completes, not while it's pending. See Order activities. - The edit itself stays readable with
GET /v1/orders/{order_id}/editsandGET /v1/orders/{order_id}/edits/{order_edit_id}. Itsremove_line_items,add_line_items,charge_refunds, andrefund_idssay exactly what changed.