Edit an existing order with GraphQL Admin API
Apps can edit orders created by a Shopify channel (for example, POS, online store, or draft orders) or orders the app created through the API.
This guide explains how to use the GraphQL Admin API to edit an existing order. For example, you might add new items to a customer’s order or alter the quantity of line items.
How it worksAnchor link to section titled "How it works"
Editing an order with the GraphQL Admin API follows a new pattern, starting with a begin mutation, then a series of edits, and finally a commit. The
orderEditBegin mutation creates a
CalculatedOrder object, which tracks the edits that you want to make to the order. When you are satisfied with your changes, the
orderEditCommit mutation commits the changes to the order.
Refer to the GraphQL Admin API reference for more information on order editing mutations and objects.
Types of edits to an orderAnchor link to section titled "Types of edits to an order"
You can make the following edits to an order:
- Add new variant line items
- Add new custom line items
- Add or remove line item discounts
- Alter line item quantities
Only unfulfilled line items can be edited. If an edit changes the total order value then a balance might need to be collected from or refunded to the customer. You can use the
orderEditCommit mutation to send an invoice to the customer that they can use to pay the outstanding balance and complete the order (similiar to completing draft orders).
Access scopesAnchor link to section titled "Access scopes"
- To use the GraphQL Admin API to edit orders, your app needs to request the
- By default, your app has access to orders placed in the last 60 days. To use the GraphQL Admin API to query orders placed more than 60 days ago, your app needs to request the
For more information on requesting access scopes when your app is installed, see OAuth.
LimitationsAnchor link to section titled "Limitations"
- You can't edit archived orders or orders placed more than 180 days ago.
- If you sell in multiple currencies, then you can only edit orders placed in your store currency.
Begin order editingAnchor link to section titled "Begin order editing"
orderEditBegin mutation is the first step in editing an order. Pass the order's ID to the mutation, and request the ID of the CalculatedOrder object as a return field. The CalculatedOrder object tracks the edits until you're ready to commit them to the order with the
Edit the orderAnchor link to section titled "Edit the order"
Now that you have the CalculatedOrder object ID, make the following edits to the order:
- Add a new variant
- Add a discount to the variant
- Remove a discount from a variant
- Add a custom line item
- Edit line item quantity
Add a new variantAnchor link to section titled "Add a new variant"
You can use the
orderEditAddVariant mutation to add a new product variant with a quantity of 3 to the order. Include the CalculatedOrder object ID, the variant ID and the variant quantity as the mutation's input. Request the ID of the added line items using the
addedLineItems field to verify that our variant was added correctly.
Add a discount to the variantAnchor link to section titled "Add a discount to the variant"
orderEditAddLineItemDiscount mutation adds a fixed amount or percentage discount to the line item. Include the
CalculatedOrder object ID, the line item ID and the
OrderEditAppliedDiscountInput inputs as the mutation's input.
Remove a discount from a variantAnchor link to section titled "Remove a discount from a variant"
orderEditRemoveLineItemDiscount mutation removes a fixed amount or percentage discount from the line item. Include the
CalculatedOrder object ID and the
discountApplicationId as the mutation's input.
Add a custom line itemAnchor link to section titled "Add a custom line item"
Add a custom line item to the order for gift wrapping. In the input, include the CalculatedOrder ID, line item title, quantity, and price to the
orderEditAddCustomItem field. In the response, request the added line item’s ID, title, and quantity to verify that it was added correctly.
Edit line item quantityAnchor link to section titled "Edit line item quantity"
Adjust the line item quantity to add an additional gift wrapping service to the order using the
orderEditSetQuantity mutation. In the input, include the order
lineItemId, and the new
quantity value that you want to set. In the response, request the ID and quantity of the line items to verify that it was updated correctly.
Commit the order editsAnchor link to section titled "Commit the order edits"
Commit the changes to the order. The
orderEditCommit mutation commits the changes tracked by the
CalculatedOrder object to the order. In the input, include the
CalculatedOrder object ID, the
notifyCustomer field set to false, and a
notifyCustomer is set to true, an email invoice with the updated order information is sent to the customer.
Orders updated webhookAnchor link to section titled "Orders updated webhook"
Subscribe to the
orders/updated webhook to be notified when an order has been edited. The webhook is triggered whenever an order edit is completed.