Edit an existing order with Admin API
Apps can edit any order created by a Shopify channel (for example, POS, online store, or draft orders) or any 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 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 order
You can make the following edits to an order:
- Add new variant line items
- Add new custom line items
- Remove line items
- 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 scopes
To use the GraphQL Admin API to edit orders, your app needs to request the write_order_edits
access scope for a Shopify store. For more information on requesting access scopes when your app is installed, see OAuth.
Begin order editing
The 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 orderEditCommit
mutation.
Mutation
mutation beginEdit{
orderEditBegin(id: "gid://shopify/Order/1234"){
calculatedOrder{
id
}
}
}
Response
{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678"
}
}
}
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 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.
Mutation
mutation addVariantToOrder{
orderEditAddVariant(id: "gid://shopify/CalculatedOrder/5678", variantId: "gid://shopify/ProductVariant/19523055845398", quantity: 1){
calculatedOrder {
id
addedLineItems(first:5) {
edges {
node {
id
quantity
}
}
}
}
userErrors {
field
message
}
}
}
Response
{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678",
"addedLineItems": {
"edges": [
{
"node": {
"id": "gid://shopify/CalculatedLineItems/121314",
"quantity": 3
}
}
]
}
},
"userErrors": []
}
}
Add a discount to the variant
The 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.
Mutation
mutation addDiscount {
orderEditAddLineItemDiscount(id: "gid://shopify/CalculatedOrder/5678", lineItemId: "gid://shopify/CalculatedLineItem/121314", discount: {percentValue: 20, description: "Upsell"}) {
calculatedOrder {
id
addedLineItems(first:5) {
edges {
node {
id
quantity
}
}
}
}
userErrors {
message
}
}
}
Response
{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678",
"addedLineItems": {
"edges": [
{
"node": {
"id": "gid://shopify/CalculatedLineItem/151617",
"quantity": 2
}
}
]
}
},
"userErrors": []
}
}
Remove a discount from a variant
The 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.
Mutation
mutation removeDiscount {
orderEditRemoveLineItemDiscount(id: "gid://shopify/CalculatedOrder/5678", discountApplicationId: "gid://shopify/CalculatedDiscountApplication/134243") {
userErrors {
field
message
}
}
}
Response
{
"data": {
"orderEditRemoveLineItemDiscount": {
"userErrors": []
}
}
}
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.
Mutation
mutation addCustomItemToOrder {
orderEditAddCustomItem(id: "gid://shopify/CalculatedOrder/19300374", title: "Custom Line Item", quantity: 1, price: {amount: 40.00, currencyCode: CAD}) {
calculatedOrder {
id
addedLineItems(first: 5) {
edges {
node {
id
}
}
}
}
userErrors {
field
message
}
}
}
Response
{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678",
"addedLineItems": {
"edges": [
{
"node": {
"id": "gid://shopify/CalculatedLineItem/121314",
"title": "Shopify socks",
"quantity": 4
}
},
{
"node": {
"id": "gid://shopify/CalculatedLineItem/151617",
"title": "Gift wrapping service",
"quantity": 1
}
}
]
}
},
"userErrors": []
}
}
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 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 it was updated correctly.
Mutation
mutation increaseLineItemQuantity {
orderEditSetQuantity(id: "gid://shopify/CalculatedOrder/19300374", lineItemId: "gid://shopify/CalculatedLineItem/2941798776854", quantity: 2) {
calculatedOrder {
id
addedLineItems(first: 5) {
edges {
node {
id
quantity
}
}
}
}
userErrors {
field
message
}
}
}
Response
{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678",
"addedLineItems": {
"edges": [
{
"node": {
"id": "gid://shopify/CalculatedLineItem/151617",
"quantity": 2
}
}
]
}
},
"userErrors": []
}
}
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 staffNote
. When notifyCustomer
is set to true, an email invoice with the updated order information is sent to the customer.
Mutation
mutation commitEdit {
orderEditCommit(id: "gid://shopify/CalculatedOrder/19300374", notifyCustomer: false, staffNote: "I edited the order! It was me!") {
order {
id
}
userErrors {
field
message
}
}
}
Response
{
"data": {
"order": {
"id": "gid://shopify/Order/1234"
}
},
"userErrors": []
}
Order edited webhook
Subscribe to the orders/edited
webhook to be notified when an order has been edited. The webhook is triggered whenever an order edit is completed.