Edit an existing Shopify order programmatically with the order editing API (begin/commit pattern)
domain: shopify.dev · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
Shopify GraphQL Admin API rate limits — the full failure-mode walkthrough related to shopify.dev, checked against official docs, with linked verified routes.
Steps
Ensure your app has the `write_order_edits` access scope in addition to `write_orders`.
Start an editing session by calling `orderEditBegin` with the order ID; this returns a `CalculatedOrder` object containing the current order state and a `calculatedOrderId` used for all subsequent edit mutations.
Apply changes using the `calculatedOrderId`: call `orderEditAddVariant` to add a new line item, `orderEditSetQuantity` to change quantities, `orderEditAddLineItemDiscount` for discounts, or `orderEditRemoveLineItemDiscount` to remove them.
Preview the financial impact of your changes by querying the `CalculatedOrder` fields for `addedLineItemsSubtotalPrice`, `totalPrice`, and `taxLines` before committing.
Commit the session with `orderEditCommit`, optionally setting `notifyCustomer: true` to send an order-updated email and providing a `staffNote` for the order timeline.
If the committed edit increases the order total, use `orderCreatePaymentLink` or direct the merchant to collect additional payment; if it decreases the total, issue a refund via `refundCreate`.
Known gotchas
Only unfulfilled line items can be edited; attempting to change the quantity of a fulfilled line item returns a user error — split the order before editing if partial fulfillment has occurred.
The `calculatedOrderId` is ephemeral: it expires if the editing session is not committed within a reasonable time window (check the current session timeout in Shopify documentation) — build commit logic into the same request flow as `orderEditBegin`.
Calling `orderEditBegin` again on an order that already has an open editing session returns the existing session's `calculatedOrderId`; concurrent edits from multiple processes can overwrite each other's changes.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?