Skip to main content

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.


  • Your app can make authenticated requests to the GraphQL Admin API.

  • Your app has the write_order_edits access scope.

    Tip

    By default, your app has access to orders placed in the last 60 days. To use the GraphQL Admin API to query orders that were placed more than 60 days ago, your app needs to request the read_all_orders scope. Learn how to configure your access scopes using Shopify CLI.

  • 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 Shopify Extensions in Checkout.

  • 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.


Anchor to Editing subscription ordersEditing subscription orders

You can use the GraphQL Admin API to edit orders that contain subscription items, but consider the following restrictions:

  • You can't change the line item quantity when the order is a prepaid subscription and contains multiple scheduled fulfillments.
  • You can't edit orders that include a prepaid subscription through a checkout UI extension.
  • Editing the order doesn't modify the subscription contract itself. You must update the subscription contract instead.

Anchor to Step 1: Begin order editingStep 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:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation beginEdit{
orderEditBegin(id: "gid://shopify/Order/1234"){
calculatedOrder{
id
}
}
}

JSON response

{
"data": {
"orderEditBegin": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678"
}
}
}
}

Anchor to Step 2: Edit the orderStep 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 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL 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
}
}
}

JSON response

{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678",
"addedLineItems": {
"edges": [
{
"node": {
"id": "gid://shopify/CalculatedLineItems/121314",
"quantity": 3
}
}
]
}
},
"userErrors": []
}
}

Anchor to Add a discount to the variantAdd 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation addDiscount {
orderEditAddLineItemDiscount(id: "gid://shopify/CalculatedOrder/5678", lineItemId: "gid://shopify/CalculatedLineItem/121314", discount: {percentValue: 20, description: "Product offer at checkout"}) {
calculatedOrder {
id
addedLineItems(first:5) {
edges {
node {
id
quantity
}
}
}
}
userErrors {
message
}
}
}

JSON response

{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678",
"addedLineItems": {
"edges": [
{
"node": {
"id": "gid://shopify/CalculatedLineItem/151617",
"quantity": 2
}
}
]
}
},
"userErrors": []
}
}

Anchor to Remove a discount from a variantRemove 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation removeDiscount {
orderEditRemoveDiscount(id: "gid://shopify/CalculatedOrder/5678", discountApplicationId: "gid://shopify/CalculatedDiscountApplication/134243") {
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"orderEditRemoveDiscount": {
"userErrors": []
}
}
}

Anchor to Update a discount from a variantUpdate 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation updateDiscount {
orderEditUpdateDiscount(id: "gid://shopify/CalculatedOrder/5678", discountApplicationId: "gid://shopify/CalculatedDiscountApplication/134243", discount: {percentValue: 20, description: "Product offer at checkout"}) {
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"orderEditUpdateDiscount": {
"userErrors": []
}
}
}

Anchor to Add a custom line itemAdd 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation addCustomItemToOrder {
orderEditAddCustomItem(id: "gid://shopify/CalculatedOrder/5678", title: "Custom Line Item", quantity: 1, price: {amount: 40.00, currencyCode: CAD}) {
calculatedOrder {
id
addedLineItems(first: 5) {
edges {
node {
id
}
}
}
}
userErrors {
field
message
}
}
}

JSON 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": []
}
}

Anchor to Edit line item quantityEdit 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation increaseLineItemQuantity {
orderEditSetQuantity(id: "gid://shopify/CalculatedOrder/5678", lineItemId: "gid://shopify/CalculatedLineItem/2941798776854", quantity: 2) {
calculatedOrder {
id
addedLineItems(first: 5) {
edges {
node {
id
quantity
}
}
}
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678",
"addedLineItems": {
"edges": [
{
"node": {
"id": "gid://shopify/CalculatedLineItem/151617",
"title": "Gift wrapping service",
"quantity": 2
}
}
]
}
},
"userErrors": []
}
}

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.

Note

Optionally, you can include restock in the mutation's input, which determines whether the line item should be restocked when the updated quantity is less than the original quantity. By default, restock value is set to false.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation removeLineItem {
orderEditSetQuantity(id: "gid://shopify/CalculatedOrder/5678", lineItemId: "gid://shopify/CalculatedLineItem/151617", quantity: 0) {
calculatedOrder {
id
lineItems(first: 5) {
edges {
node {
id
quantity
}
}
}
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678",
"lineItems": {
"edges": [
{
"node": {
"id": "gid://shopify/CalculatedLineItem/151617",
"title": "Gift wrapping service",
"quantity": 0
}
}
]
}
},
"userErrors": []
}
}

Anchor to Add a new shipping lineAdd 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation addShippingLine {
orderEditAddShippingLine(id: "gid://shopify/CalculatedOrder/5678", shippingLine: { title: "Standard Shipping", price: { amount: 10.00, currencyCode: CAD }}) {
calculatedOrder {
id
shippingLines {
id
stagedStatus
title
price {
shopMoney {
currencyCode
amount
}
}
}
}
userErrors {
field
message
code
}
}
}

JSON response

{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678",
"shippingLines": [
{
"id": "gid://shopify/CalculatedShippingLine/151617",
"stagedStatus": "ADDED",
"title": "Standard Shipping",
"price": {
"shopMoney": {
"currencyCode": "CAD",
"amount": 10.0,
}
}
}
]
},
"userErrors": [],
}
}
Note

This mutation is available as of API version 2024-04.

Anchor to Update a newly added shipping lineUpdate 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation updateShippingLine {
orderEditUpdateShippingLine(id: "gid://shopify/CalculatedOrder/5678", shippingLineId: "gid://shopify/CalculatedShippingLine/151617", shippingLine: { price: { amount: 12.00, currencyCode: CAD }}) {
calculatedOrder {
id
shippingLines {
id
stagedStatus
title
price {
shopMoney {
currencyCode
amount
}
}
}
}
userErrors {
field
message
code
}
}
}

JSON response

{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678",
"shippingLines": [
{
"id": "gid://shopify/CalculatedShippingLine/151617",
"stagedStatus": "ADDED",
"title": "Standard Shipping",
"price": {
"shopMoney": {
"currencyCode": "CAD",
"amount": 12.0,
}
}
}
]
},
"userErrors": [],
}
}
Note

This mutation is available as of API version 2024-04.

Anchor to Remove a shipping lineRemove 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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation removeShippingLine {
orderEditRemoveShippingLine(id: "gid://shopify/CalculatedOrder/5678", shippingLineId: "gid://shopify/CalculatedShippingLine/134243") {
calculatedOrder {
id
shippingLines {
id
stagedStatus
}
}
userErrors {
field
message
code
}
}
}

JSON response

{
"data": {
"calculatedOrder": {
"id": "gid://shopify/CalculatedOrder/5678",
"shippingLines": [
{
"id": "gid://shopify/CalculatedShippingLine/151617",
"stagedStatus": "REMOVED"
}
]
},
"userErrors": []
}
}
Note

This mutation is available as of API version 2024-04.


Anchor to Step 3: Commit the order editsStep 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.

Note

You can edit only unfulfilled line items. 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, similarly to how you'd complete draft orders.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation commitEdit {
orderEditCommit(id: "gid://shopify/CalculatedOrder/5678", notifyCustomer: false, staffNote: "I edited the order! It was me!") {
order {
id
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"order": {
"id": "gid://shopify/Order/1234"
}
},
"userErrors": []
}

Anchor to Step 4: Subscribe to a webhookStep 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.



Was this page helpful?