Edit an order after it was placed
Add items, change quantities and commit the change with orderEditBegin, orderEditAddVariant, orderEditSetQuantity and orderEditCommit.
- API
- Admin GraphQL API
- Operations
- orderEditBegin, orderEditAddVariant, orderEditSetQuantity, orderEditCommit
- Access scope
- write_order_edits
- API version
- 2026-10
- Last checked
In short
To edit a placed order, start with orderEditBegin, which returns a calculated order: a draft copy of the order. Stage changes on it with orderEditAddVariant, orderEditSetQuantity and similar mutations, then apply them all at once with orderEditCommit. Nothing changes on the real order until you commit. Only unfulfilled line items can be edited, and your app needs write_order_edits.
How to use it
- Send BeginOrderEdit with the order ID. Keep the calculated order ID and the calculated line item IDs it returns.
- Stage changes: AddItemToOrder adds a variant, ChangeQuantity lowers or raises a line item. Use restock: true to put removed units back in stock.
- Check userErrors after each step; a staged change that fails leaves the others in place.
- Send CommitOrderEdit. With notifyCustomer: true the customer gets the updated order by email.
Code
order-edit-begin.graphqlmutation BeginOrderEdit($orderId: ID!) {
orderEditBegin(id: $orderId) {
calculatedOrder {
id
lineItems(first: 20) {
nodes {
id
title
quantity
editableQuantity
}
}
}
userErrors {
field
message
}
}
}
order-edit-begin.variables.json{
"orderId": "gid://shopify/Order/1234567890"
}
order-edit-begin.response.json{
"data": {
"orderEditBegin": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/1234567890",
"lineItems": {
"nodes": [
{"id": "gid://shopify/CalculatedLineItem/1111111111", "title": "Linen shirt", "quantity": 2, "editableQuantity": 2}
]
}
},
"userErrors": []
}
}
}
order-edit-add-variant.graphqlmutation AddItemToOrder($calculatedOrderId: ID!, $variantId: ID!, $quantity: Int!) {
orderEditAddVariant(id: $calculatedOrderId, variantId: $variantId, quantity: $quantity, allowDuplicates: false) {
calculatedLineItem {
id
title
quantity
}
userErrors {
field
message
}
}
}
order-edit-add-variant.variables.json{
"calculatedOrderId": "gid://shopify/CalculatedOrder/1234567890",
"variantId": "gid://shopify/ProductVariant/2222222222",
"quantity": 1
}
order-edit-add-variant.response.json{
"data": {
"orderEditAddVariant": {
"calculatedLineItem": {
"id": "gid://shopify/CalculatedLineItem/2222222222",
"title": "Wool scarf",
"quantity": 1
},
"userErrors": []
}
}
}
order-edit-set-quantity.graphqlmutation ChangeQuantity($calculatedOrderId: ID!, $lineItemId: ID!, $quantity: Int!) {
orderEditSetQuantity(id: $calculatedOrderId, lineItemId: $lineItemId, quantity: $quantity, restock: true) {
calculatedLineItem {
id
quantity
}
userErrors {
field
message
}
}
}
order-edit-set-quantity.variables.json{
"calculatedOrderId": "gid://shopify/CalculatedOrder/1234567890",
"lineItemId": "gid://shopify/CalculatedLineItem/1111111111",
"quantity": 1
}
order-edit-set-quantity.response.json{
"data": {
"orderEditSetQuantity": {
"calculatedLineItem": {
"id": "gid://shopify/CalculatedLineItem/1111111111",
"quantity": 1
},
"userErrors": []
}
}
}
order-edit-commit.graphqlmutation CommitOrderEdit($calculatedOrderId: ID!, $notifyCustomer: Boolean, $staffNote: String) {
orderEditCommit(id: $calculatedOrderId, notifyCustomer: $notifyCustomer, staffNote: $staffNote) {
order {
id
name
totalOutstandingSet {
shopMoney {
amount
currencyCode
}
}
}
userErrors {
field
message
}
}
}
order-edit-commit.variables.json{
"calculatedOrderId": "gid://shopify/CalculatedOrder/1234567890",
"notifyCustomer": true,
"staffNote": "Swapped one shirt for a scarf at the customer's request."
}
order-edit-commit.response.json{
"data": {
"orderEditCommit": {
"order": {
"id": "gid://shopify/Order/1234567890",
"name": "#1001",
"totalOutstandingSet": {
"shopMoney": {
"amount": "-14.00",
"currencyCode": "EUR"
}
}
},
"userErrors": []
}
}
}
Written by Lintel. MIT license: free to use in your own store and in client work.
Limits and edge cases
- Only unfulfilled line items can be edited, and orders placed before January 1, 2019 or archived orders can’t be edited.
- If the total changes, a balance may have to be collected or refunded. A negative totalOutstandingSet means the store owes the customer money; refund it with refundCreate.
- Setting a quantity to 0 removes the line item from the order.
- Shopify’s guide also lists requirements for editing orders in a currency other than the store’s, and for subscription orders.
Questions
- Can I edit a Shopify order after it is placed?
- Yes, as long as the line items are unfulfilled. Use orderEditBegin, stage the changes, then orderEditCommit, or edit the order in the Shopify admin.
- Does editing an order refund the customer automatically?
- No. If the new total is lower, the difference shows as an outstanding amount owed to the customer; create the refund yourself.
- What is a calculated order?
- A working copy of the order that holds your staged edits and the recalculated totals. It becomes the real order only when you commit it.
Shopify documentation
- Validated against the Admin or Storefront API schema for version 2026-10 on the date shown. Check the version in your request URL.
- IDs and store addresses in the examples are placeholders. Replace them with your own.
- Admin API calls need an access token from your app. Never put an Admin API token in a storefront or theme.
- MIT license. Use the code in your own store or in client work.
Need this built, tested and maintained for your store? See API integrations.
