--- title: Edit existing orders description: Use the GraphQL Admin API to edit existing orders. source_url: html: >- https://shopify.dev/docs/apps/build/orders-fulfillment/order-management-apps/edit-orders md: >- https://shopify.dev/docs/apps/build/orders-fulfillment/order-management-apps/edit-orders.md api_name: admin --- # 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 * Your app can make [authenticated requests](https://shopify.dev/docs/api/admin-graphql#authentication) to the GraphQL Admin API. * Your app has the `write_order_edits` [access scope](https://shopify.dev/docs/api/usage/access-scopes). **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](https://shopify.dev/docs/apps/build/cli-for-apps/app-configuration). * You've met Shopify's [protected customer data requirements](https://shopify.dev/docs/apps/launch/protected-customer-data). * 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](https://shopify.dev/docs/apps/build/checkout#upgrade). * 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. *** ## Editing 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](https://shopify.dev/docs/api/checkout-ui-extensions). * Editing the order doesn't modify the subscription contract itself. You must [update the subscription contract](https://shopify.dev/docs/apps/build/purchase-options/subscriptions/contracts/update-a-subscription-contract) instead. *** ## Step 1: Begin order editing The [`orderEditBegin`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/ordereditbegin) mutation is the first step in editing an order. The [`orderEditBegin`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/calculatedorder) object as a return field: ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql mutation beginEdit{ orderEditBegin(id: "gid://shopify/Order/1234"){ calculatedOrder{ id } } } ``` ## JSON response ```json { "data": { "orderEditBegin": { "calculatedOrder": { "id": "gid://shopify/CalculatedOrder/5678" } } } } ``` *** ## 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-new-variant) * [Add a discount to the variant](#add-a-discount-to-the-variant) * [Remove a discount from a variant](#remove-a-discount-from-a-variant) * [Update a discount from a variant](#update-a-discount-from-a-variant) * [Add a custom line item](#add-a-custom-line-item) * [Edit line item quantity](#edit-line-item-quantity) * [Remove a line item](#remove-a-line-item) * [Add a new shipping line](#add-a-new-shipping-line) * [Update a newly added shipping line](#update-a-newly-added-shipping-line) * [Remove a shipping line](#remove-a-shipping-line) ### Add a new variant Add a new product variant to an order with the [`orderEditAddVariant`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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 ```graphql 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 ```json { "data": { "calculatedOrder": { "id": "gid://shopify/CalculatedOrder/5678", "addedLineItems": { "edges": [ { "node": { "id": "gid://shopify/CalculatedLineItems/121314", "quantity": 3 } } ] } }, "userErrors": [] } } ``` ### Add a discount to the variant Add a fixed amount or percentage discount to a line item with the [`orderEditAddLineItemDiscount`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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 ```graphql 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 ```json { "data": { "calculatedOrder": { "id": "gid://shopify/CalculatedOrder/5678", "addedLineItems": { "edges": [ { "node": { "id": "gid://shopify/CalculatedLineItem/151617", "quantity": 2 } } ] } }, "userErrors": [] } } ``` ### Remove a discount from a variant Remove a fixed amount or percentage discount from a line item with the [`orderEditRemoveDiscount`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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 ```graphql mutation removeDiscount { orderEditRemoveDiscount(id: "gid://shopify/CalculatedOrder/5678", discountApplicationId: "gid://shopify/CalculatedDiscountApplication/134243") { userErrors { field message } } } ``` ## JSON response ```json { "data": { "orderEditRemoveDiscount": { "userErrors": [] } } } ``` ### Update a discount from a variant Update a fixed amount or percentage discount from a line item with the [`orderEditUpdateDiscount`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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 ```graphql 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 ```json { "data": { "orderEditUpdateDiscount": { "userErrors": [] } } } ``` ### Add a custom line item Add a custom line item to an order with the [`orderEditAddCustomItem`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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 ```graphql 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 ```json { "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 You can use the [`orderEditSetQuantity`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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 ```graphql 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 ```json { "data": { "calculatedOrder": { "id": "gid://shopify/CalculatedOrder/5678", "addedLineItems": { "edges": [ { "node": { "id": "gid://shopify/CalculatedLineItem/151617", "title": "Gift wrapping service", "quantity": 2 } } ] } }, "userErrors": [] } } ``` ### Remove a line item You can remove any line item using the [`orderEditSetQuantity`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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 ```graphql 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 ```json { "data": { "calculatedOrder": { "id": "gid://shopify/CalculatedOrder/5678", "lineItems": { "edges": [ { "node": { "id": "gid://shopify/CalculatedLineItem/151617", "title": "Gift wrapping service", "quantity": 0 } } ] } }, "userErrors": [] } } ``` ### Add a new shipping line You can add a custom shipping line using the [`orderEditAddShippingLine`](https://shopify.dev/docs/api/admin-graphql/2024-04/mutations/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 ```graphql 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 ```json { "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`. ### Update a newly added shipping line You can update a newly added shipping line using the [`orderEditUpdateShippingLine`](https://shopify.dev/docs/api/admin-graphql/2024-04/mutations/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 ```graphql 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 ```json { "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`. ### Remove a shipping line You can remove any shipping line using the [`orderEditRemoveShippingLine`](https://shopify.dev/docs/api/admin-graphql/2024-04/mutations/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 ```graphql mutation removeShippingLine { orderEditRemoveShippingLine(id: "gid://shopify/CalculatedOrder/5678", shippingLineId: "gid://shopify/CalculatedShippingLine/134243") { calculatedOrder { id shippingLines { id stagedStatus } } userErrors { field message code } } } ``` ## JSON response ```json { "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`. *** ## Step 3: Commit the order edits When you're satisfied with your changes, you can commit them to the order with the [`orderEditCommit`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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](https://shopify.dev/docs/api/admin-graphql/latest/objects/draftorder). ## POST https://{shop}.myshopify.com/api/{api\_version}/graphql.json ## GraphQL mutation ```graphql 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 ```json { "data": { "order": { "id": "gid://shopify/Order/1234" } }, "userErrors": [] } ``` *** ## Step 4: Subscribe to a webhook To be notified when an order is edited, subscribe your app to the [`orders/edited`](https://shopify.dev/docs/api/admin-graphql/latest/enums/WebhookSubscriptionTopic) 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](https://shopify.dev/docs/apps/build/webhooks/subscribe). The following examples show the payload for an edit that adds one unit of one line item and removes one unit of another. As of API version `2026-10`, the payload carries an extra `shipping_address` field, which reports whether the edit changed the order's shipping address. For the payload as of a specific API version, refer to the [`orders/edited` webhook reference](https://shopify.dev/docs/api/webhooks?reference=toml#list-of-topics-orders/edited). The payload reports what the edit changed, not the order's new state. `id` is the ID of the order edit, and `order_id` is the ID of the order. To query that order with the GraphQL Admin API, convert the numeric `order_id` into a global ID of the form `gid://shopify/Order/820982911946154508`. Line item changes are quantity deltas rather than lists of products. Raising the quantity of a line item that's already on the order appears in `additions`, and lowering it appears in `removals`. `delta` is always positive: the array it appears in carries the direction. Each `id` is a line item ID. When an edit adds a variant, that's the ID of the line item the edit created, not of the product or variant. ## Example webhook responses ##### orders/edited (before 2026-10) ```json { "order_edit": { "id": 78912328793123782, "app_id": null, "created_at": "2021-12-31T19:00:00-05:00", "committed_at": "2021-12-31T19:00:00-05:00", "notify_customer": false, "order_id": 820982911946154508, "staff_note": "", "user_id": null, "line_items": { "additions": [ { "id": 78643924236718232, "delta": 1 } ], "removals": [ { "id": 487817672276298554, "delta": 1 } ] }, "discounts": { "line_item": { "additions": [], "removals": [] } }, "shipping_lines": { "additions": [], "removals": [] } } } ``` ##### orders/edited (2026-10 and later) ```json { "order_edit": { "id": 78912328793123782, "app_id": null, "created_at": "2021-12-31T19:00:00-05:00", "committed_at": "2021-12-31T19:00:00-05:00", "notify_customer": false, "order_id": 820982911946154508, "staff_note": "", "user_id": null, "line_items": { "additions": [ { "id": 78643924236718232, "delta": 1 } ], "removals": [ { "id": 487817672276298554, "delta": 1 } ] }, "discounts": { "line_item": { "additions": [], "removals": [] } }, "shipping_lines": { "additions": [], "removals": [] }, "shipping_address": { "changed": false } } } ``` **Note:** Before `2026-10`, you don't receive an `orders/edited` webhook for an order edit that stages one shipping address update and nothing else, because the payload would report nothing. From `2026-10`, you receive it, with `shipping_address.changed` set to `true`. *** ## Next steps * Consult the [merchant documentation](https://help.shopify.com/manual/orders/edit-orders) to learn about editing orders in the Shopify admin. * Explore examples for querying orders, including [retrieving sales data from an order](https://shopify.dev/docs/api/admin-graphql/latest/queries/order#section-examples), using the GraphQL Admin API. ***