Order changes

Every change ever staged against an order, newest first, each with its typed actions, its state (staged, confirmed or discarded) and the versions it moved the order between. Also answers the order's current version, whether the order is locked (closed, and needing unlock_order before it can be changed), and the action vocabulary each kind of change may use.

Open a change against a placed order. Nothing is written to the order by this call or by any action added to it — the change is a proposal until confirm_order_change is called, and a change that is never confirmed leaves the order exactly as it was. Add actions with add_order_change_action, read the previewed totals it returns, then confirm. Refused with 409 for a cart (use the cart endpoints), for a closed order that has not been unlocked, and when this store has not switched on order versioning. Pass idempotency_key to make a retried request answer with the change it already opened.

Add one typed verb to a staged change and get back the previewed totals. Still writes nothing to the order. The vocabulary is add_item, write_off_item, reinstate_item, update_quantity, update_price, add_adjustment, remove_adjustment, update_shipping, update_address, update_tax, add_payment, refund_payment and return_item — and which of them a change may use depends on its change_type, which list_order_changes reports. There is no delete_item, and that is on purpose: removing a line is write_off_item, which leaves the original line readable forever at the version it was bought under. Every amount is in minor units of the order's own currency. On a store that sells in more than one currency, an add_item that names a variant_id and sends no unit_price_minor is priced at that variant's price in the order's currency, and a variant with no price in it is refused with 422 whatever price is sent. An add_item with no variant_id is a custom line, priced by the amount you send.

Apply the change to a new version of the order, atomically. The order's version is incremented, every current line and adjustment is duplicated into the new version, the actions are applied to the copies, and the previous version's rows are left exactly as they were and stay readable forever through get_order_version. Recalculation appends and never removes. A return_receive change puts the sound units back on the shelf and leaves the damaged ones off it. Idempotent: a repeated confirm answers with applied: false and changes nothing.

Abandon a staged change. Its actions stay on the record, because a proposal that was withdrawn is still worth being able to read later. Refused with 409 for a change that has already been confirmed.

The lines and adjustments an order carried at a given version, exactly as they were written. Version 1 is the order as it was placed and reads back unchanged however many times it has been edited since — including the lines a later change wrote off, which is what makes an edit safe.

Open an order whose status is marked final — cancelled, archived, or anything a merchant flagged that way — so a change can be staged against it. Never refused, and never silent: the unlock writes an entry on the order's history naming whoever asked for it. This is not an editing cliff; it is one audited action.

Mark an order the merchant placed to try the store (a rehearsal, a comp, a card run through a live provider) as a test order, or with test false take the mark off. A test order is left out of every report, its refunds included, and stays an order in every other way. Recorded on the order's history. Answers changed false when the order already stood that way.