Edit existing orders
Apps can edit orders that a Shopify channel creates, such as Shopify Point of Sale (POS), Online Store, draft orders, or orders that the app creates through the GraphQL Admin API. For example, an app might add new items to a customer’s order or alter the quantity of line items.
This guide shows how to use the GraphQL Admin API to edit an existing order.
Requirements
Anchor link to section titled "Requirements"- Your app can make authenticated requests to the GraphQL Admin API.
Your app has the
write_order_edits
access scope.You've met Shopify's protected customer data requirements.
You're editing an order that was placed in your store currency.
Your store currency is the currency that's used in your Shopify admin to price products and display reports. Editing orders placed in international currencies requires you to upgrade to Checkout Extensibility.
You're editing an order that was placed after January 1, 2019. You can't edit archived orders or orders placed before January 1st, 2019.
Step 1: Begin order editing
Anchor link to section titled "Step 1: Begin order editing"The orderEditBegin
mutation is the first step in editing an order. The orderEditBegin
mutation creates a CalculatedOrder
object, which tracks the edits that you want to make to the order.
The following example shows how to pass the order's ID to the orderEditBegin
mutation and request the ID of the CalculatedOrder
object as a return field:
Step 2: Edit the order
Anchor link to section titled "Step 2: Edit the order"After you have the CalculatedOrder
object ID, you can make the following types of edits to the order:
- Add a new variant
- Add a discount to the variant
- Remove a discount from a variant
- Update a discount from a variant
- Add a custom line item
- Edit line item quantity
- Remove a line item
- Add a new shipping line
- Update a newly added shipping line
- Remove a shipping line
Add a new variant
Anchor link to section titled "Add a new variant"Add a new product variant to an order with the orderEditAddVariant
mutation.
The following example adds a new product variant with a quantity of three to the order:
In the mutation's input, include the CalculatedOrder
object ID, the variant ID and the variant quantity. 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 variant
Anchor link to section titled "Add a discount to the variant"Add a fixed amount or percentage discount to a line item with the orderEditAddLineItemDiscount
mutation.
In the mutation's input, include the CalculatedOrder
object ID, the line item ID, and the OrderEditAppliedDiscountInput
inputs.
Remove a discount from a variant
Anchor link to section titled "Remove a discount from a variant"Remove a fixed amount or percentage discount from a line item with the orderEditRemoveDiscount
mutation.
In the mutation's input, include the CalculatedOrder
object ID and the discountApplicationId
.
Update a discount from a variant
Anchor link to section titled "Update a discount from a variant"Update a fixed amount or percentage discount from a line item with the orderEditUpdateDiscount
mutation.
In the mutation's input, include the CalculatedOrder
object ID, discountApplicationId
and the OrderEditAppliedDiscountInput
inputs.
Add a custom line item
Anchor link to section titled "Add a custom line item"Add a custom line item to an order with the orderEditAddCustomItem
mutation.
The following example adds a custom line item to the order for gift wrapping.
In the mutation's input, include the CalculatedOrder
ID, line item title, quantity, and price in the orderEditAddCustomItem
field. In the response, request the added line item’s ID, title, and quantity to verify that the custom line item was added correctly.
Edit line item quantity
Anchor link to section titled "Edit line item quantity"You can use the orderEditSetQuantity
mutation to adjust the line item quantity to add an additional gift wrapping service to the order.
In the mutation's input, include the order id
, 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 the line item quantity was updated correctly.
Remove a line item
Anchor link to section titled "Remove a line item"You can remove any line item using the orderEditSetQuantity
mutation. You can effectively remove a line item by setting its quantity to zero.
In the mutation’s input, include the CalculatedOrder
object ID, the lineItemId
for the line item you want to remove, and set the quantity
value to be 0. In the response, request the ID and quantity of line items to verify that the line item you wanted to remove has its quantity updated to 0.
Add a new shipping line
Anchor link to section titled "Add a new shipping line"You can add a custom shipping line using the orderEditAddShippingLine
mutation.
In the mutation's input, include the CalculatedOrder
object ID, a shipping line title, and a price in the orderEditAddShippingLineInput
input.
Update a newly added shipping line
Anchor link to section titled "Update a newly added shipping line"You can update a newly added shipping line using the orderEditUpdateShippingLine
mutation.
In the mutation's input, include the CalculatedOrder
object ID, the shippingLineId
, and an updated shipping line title or an updated price in the orderEditUpdateShippingLineInput
input.
Remove a shipping line
Anchor link to section titled "Remove a shipping line"You can remove any shipping line using the orderEditRemoveShippingLine
mutation.
In the mutation's input, include the CalculatedOrder
object ID, and the shippingLineId
for the shipping line that you want to remove in the orderEditRemoveShippingLine
input.
Step 3: Commit the order edits
Anchor link to section titled "Step 3: Commit the order edits"When you're satisfied with your changes, you can commit them to the order with the orderEditCommit
mutation. The orderEditCommit
mutation commits the changes tracked by the CalculatedOrder
object to the order.
In the mutation's input, include the CalculatedOrder
object ID, the staffNote
field, and the notifyCustomer
field set to false
. If notifyCustomer
is set to true
, then an email invoice with the updated order information is sent to the customer.
Step 4: Subscribe to a webhook
Anchor link to section titled "Step 4: Subscribe to a webhook"To be notified when an order is edited, subscribe your app the orders/edited
webhook. The webhook is triggered whenever an order edit is completed.
To learn how to set up and consume webhooks, refer to Webhooks configuration overview.
- Consult the merchant documentation to learn about editing orders in the Shopify admin.
- Explore examples for querying orders, including retrieving sales data from an order, using the GraphQL Admin API.