Skip to content

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 toSendSection
See the money before you commitA preview1. Preview the edit
Take units offremove_line_items2. Remove units
Swap a size or add an itemremove_line_items and add_line_items3. Swap or add items
Charge for an upgradebalance_due_behavior: "collect"4. Collect a balance
Fix a refund that failedThe edit's retry6. 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
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}
    ]
  }'
Response
{
  "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_quantity is how many units of the line can still come off.
  • total_money is the removed units' value at the price the buyer paid, including their share of discounts and tax. refund_money is the part that goes back to the buyer after paying for any added items.
  • amount_due_money is what the buyer would owe when the added items cost more than what came off. At most one of refund_money and amount_due_money is above zero.
  • based_on_order_version is the order version the preview read. Send it as expected_order_version when 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
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:

  1. Checks expected_order_version and 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.
  2. Records the edit with the values it calculated. They never change afterward, even if prices or tax rules do.
  3. Releases the stock behind the removed units. Units still on backorder go first, then committed ones. Nothing physical moves.
  4. 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
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_money is 0, 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_INSUFFICIENT at the first add_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_quantities for you to fulfill yourself. Each new line carries the order_edit_id that 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
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
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_refunds with its order_charge_id. Leave out amount_money to 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
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 haveDo this instead
Units in a fulfillment that hasn't shippedEnd 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 deliveredTake them back with a Return.
Lines with nothing to fulfill: services, digital items, gift cards, and event ticketsRefund 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 orderSell 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 createdChange the subscription, or the Return. The edit returns 409 ACTION_NOT_ALLOWED with reason subscription_owned or return_owned.
An order an invoice collectedCorrect it with a credit note. The edit returns 409 RESOURCE_IN_USE.
A disputed paymentWait for the dispute. The edit returns reason payment_disputed.
An unresolved inventory exceptionResolve 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 note stays private.
  • The activity log gets an order_edited row. Its refund gets its own refund row, and a failure adds refund_failed. An edit that collects a balance adds order_edited and a payment row when it completes, not while it's pending. See Order activities.
  • The edit itself stays readable with GET /v1/orders/{order_id}/edits and GET /v1/orders/{order_id}/edits/{order_edit_id}. Its remove_line_items, add_line_items, charge_refunds, and refund_ids say exactly what changed.
  • order_edit.created
    Flint recorded an edit. Check its status: completed when it applied at once, pending when it waits for a balance payment.
  • order_edit.completed
    A pending edit's balance was paid and its changes applied. Fulfill the added items now.
  • order_edit.canceled
    A pending edit ended without applying. cancellation_reason says why, such as expired or merchant_request.
  • refund.created
    The refund an edit created exists. It carries the edit's order_edit_id.
  • order.updated
    The order changed, including when a pending edit is set or cleared.

Errors#

  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    The order changed since you read it, or the balance differs from expected_amount_due_money. Read the order, preview again, and send the new version and balance.
  • HTTP 409
    With reason order_edit_balance_due, the added items cost more than what came off; send balance_due_behavior: "collect" or add less. Otherwise a quantity is more than the line's unassigned quantity, or a charge refund is more than the charge has left. details[0].available_quantity or details[0].maximum_money has the most you can send.
  • HTTP 409
    The order can't be edited. details[0].reason is status_not_reached when it isn't paid, subscription_owned or return_owned, payment_disputed, order_edit_pending, or not_offered for an unresolved inventory exception.
  • HTTP 409
    Stock can't cover the added line named by param. Add fewer units, or sell it on a new order once stock arrives.
  • HTTP 400
    The body is malformed, a removed line has no fulfillment quantities, or an added line is a kind Flint can't fulfill (detail NOT_ALLOWED at add_line_items[i]).
  • HTTP 409
    An invoice collected the order. Correct it with a credit note.

API calls#

Next steps#

Edit a paid order referenceEvery field, frozen value, and refusal.RefundsRefund lines, amounts, and charges without changing the order's items.Your first returnTake back items that already shipped.

Was this helpful?