On this page
Shopify added these APIs in version 2026-10. Adopt them when your order-management or fulfillment integration needs to see a customer’s pending cancellation request before the merchant processes it.
Restrict submissions to unfulfilled removals
The supported change is removal. In 2026-10, the lineItems input of orderRequestEdit contains only removals, each with a lineItemId and the requested quantity. Partial quantities are allowed. Adds and variant swaps have no request type, nor do address, shipping, or discount changes.
In the native customer-account flow, buyers select Cancel items on an eligible order. Legacy customer accounts are unsupported. Shopify’s setup requirements describe activation under Settings > Customer accounts. Use the customer-account migration guide if the store still runs legacy accounts.
Read Order.requestedEditInformation when building the buyer interface. Its eligibility object exposes hasEditableLineItems, editableLineItems, and ineligibleLineItems. Render eligible quantities from that response. Do not assume every unfulfilled unit is available for a new request.
Native self-serve requests apply to B2B orders too. Processing a request for a subscription order leaves the subscription contract active. Per-market activation requires Advanced or Plus and access to the early-access order actions settings in the checkout and accounts editor. Stores without that option activate requests across all markets.
Wire the API and permissions
Use the 2026-10 references. The request resource is RequestedOrderEdit. Its status enum contains REQUESTED, RESOLVED, and DECLINED. REQUESTED means merchant action is pending. There is no APPROVED state.
| Caller | Operation | Purpose |
|---|---|---|
| Admin API | requestedOrderEditCreate |
Create a request on a buyer’s behalf |
| Admin API | requestedOrderEditResolve |
Mark a request resolved |
| Admin API | requestedOrderEditDecline |
Decline a request |
| Customer Account API | orderRequestEdit |
Submit the buyer’s request |
| Both APIs | requestedOrderEditCalculate |
Preview the financial outcome |
For Admin queries, request read_orders. The three Admin mutations require write_orders and the staff edit_orders permission, as the create reference specifies. The calculated merchant-edit workflow separately requires write_order_edits.
For the buyer mutation, request customer_write_pre_authenticated. The user also needs customer_write_orders access or pre-authenticated access to the order. For the buyer’s preview query, the app needs customer_read_pre_authenticated, and the user must have customer_read_orders access or pre-authenticated access to that specific order before you offer the preview. Reading OrderRequestedEditInformation requires customer_read_orders.
Use @idempotent on orderRequestEdit and reuse the key when retrying the same submission. Shopify returns the original request instead of creating another.
Hold fulfillment while the merchant reviews
A pending request has no documented automatic hold. Shopify’s changelog describes holding fulfillment as work an app can perform on orders with REQUESTED status.
Subscribe to the three request webhook topics: requested_order_edit/created, requested_order_edit/resolved, and requested_order_edit/declined. Each requires at least one of read_orders, read_marketplace_orders, or read_buyer_membership_orders. Payloads identify the order and requested removals, including quantity and resolved_quantity. The sample webhook statuses are lowercase. GraphQL enum values are uppercase.
If the merchant wants picking paused during review, build this sequence into your integration:
- On
/created, fetch the current order and request. Record the request ID against the warehouse order. - Apply the fulfillment hold or warehouse stop mechanism your integration owns. If the warehouse already imported the order, require its confirmation that picking has stopped for the requested units.
- On
/resolvedor/declined, fetch the order’s remaining requests and current quantities. Release your integration’s hold only after pending requests and any required refund work are complete.
Check every request. An order can have multiple requests, and displayRequestedEditStatus = REQUESTED means at least one still needs merchant action. Do not release the hold on a single /resolved event.
Agree on the stop acknowledgment before enabling automated release. The fulfillment-hold integration guide covers the downstream controls.
Process the removal before closing the request
In Shopify admin, filter Orders by Customer request. The request appears in a banner on the order. Reviewers need the Orders permission.
For a paid order, Remove items opens the refund page with the requested items marked. Select the items to refund, review the amount and restock options, then click Refund. Shopify marks the request resolved. For unpaid orders, Remove items opens the restock page instead.
Resolution closes the request record. The requestedOrderEditResolve reference describes it as marking the request completed, and its only input is the request id, with no quantity, refund or restock fields. Remove and refund the units separately, and keep both operations in your implementation’s execution record.
Use requestedOrderEditCalculate to preview the requested removal’s financial outcome before submission. It returns financialSummary and calculated line items. A preview does not settle money. Our order-editing API guide covers the existing begin, stage, and commit workflow and its separate settlement work.
To reject the request, call requestedOrderEditDecline. Its optional declineNote is a buyer notification message with a 500-character maximum. In Shopify admin, Manage request > Mark as resolved instead closes the request without changing the order or emailing the customer. Decline when the merchant refuses the removal. Resolve only after the units are removed and refunded, or when the request was handled another way.
Prove the undocumented transitions before release
In Shopify admin, refunding the requested items resolves the request and so does cancelling the order, while removing items and refunding later leaves it open. Shopify does not document whether refundCreate or an orderEditCommit that removes the requested units resolves it through the API. Test whether your API path behaves like the admin on a development store before you rely on it.
Create a request for part of an unfulfilled line, then process that quantity through your intended refund or edit path without calling requestedOrderEditResolve. Inspect the resulting request status and resolvedQuantity, alongside the order’s remaining units and refund transaction. Record which request webhooks arrive.
Create another request against different eligible units on the same order, and exercise your release handler while one request remains pending. Keep the warehouse blocked while the merchant still has a request to review. If removal or refund fails, show the merchant a visible exception and keep the order blocked.
For recovery, run a paginated orders query using the filter requested_order_edit_status:requested. Fetch each matching order’s requestedOrderEdits connection and reconcile it against your request records. Also reconcile the orders your integration is holding, by ID, because an order whose last request closed while a webhook was missed drops out of that search. Set the sweep interval from the warehouse’s release rules.
Choose who executes the change
Route additions outside the buyer-request API. Shopify’s merchant editing flow permits adding products before fulfillment.
For customers who need variant swaps, address fixes, or added items within a merchant-set editing window, stores use a self-serve editing app such as Revize. Its Hold orders setting, under Fulfillment while editing, holds fulfillment while a timed edit deadline is open, then releases it according to the configured release timing and payment conditions. With the Until fulfillment deadline, Revize places no hold.
| Buyer-requested edit | Merchant edit | Revize (self-serve app) | |
|---|---|---|---|
| Who starts it | Buyer in customer accounts or through orderRequestEdit. An app can create a request for the buyer |
Merchant staff or an app using the order-editing API | Buyer on Shopify’s order status page |
| Who approves it | Merchant or app reviews and processes or declines the request | Staff or app executes the edit | Merchant sets permitted actions beforehand. Eligible cancellation is automatic |
| What can change | Removal of unfulfilled units, including partial quantities. Submission changes nothing | Products, quantities, shipping fees, manual discounts within native editing limits | Variant and quantity changes, shipping address, added products. Product additions require Pro |
| Payment | Creation and resolution issue no refund. Processing the removal needs a refund decision | Increased total permits an updated invoice. Decreased total permits a refund | Pay now, Refund or Confirm, depending on whether the total rises, falls or stays the same. Shopify executes the payment or refund; Pay now collects only the difference |
| Fulfillment | Unfulfilled units only. No automatic hold documented | Quantity changes and removals: unfulfilled items only. Manual discounts can also change on fulfilled items | Before fulfillment, inside the merchant-set window. Hold orders mode holds fulfillment |
Set Fulfillment while editing with the warehouse before opening the customer editing flow. For shopper-facing cancellation instructions, link customers to the cancellation guide.
Frequently asked questions
Our request is RESOLVED, but the units remain. Did the API fail?
The status alone does not prove removal. requestedOrderEditResolve marks the request completed and takes only the request id, with no quantity, refund or restock fields. Support should inspect the actual order and refund record before telling the buyer that processing finished.
Can the buyer request a size swap through these APIs?
No. The 2026-10 request inputs support only removals of unfulfilled units. Route the size change to the store’s merchant-edit or customer self-serve editing workflow.
Does a resolved webhook mean every request on that order is closed?
No. Fetch requestedOrderEdits or inspect displayRequestedEditStatus before releasing the warehouse order. An order-level REQUESTED value means merchant action remains pending on at least one request.
Should we keep our fulfillment-order cancellation subscriptions?
Keep them if your fulfillment-service integration needs them. fulfillment_orders/cancellation_request_* topics concern merchant or app requests to a fulfillment service. Buyer-requested edits use requested_order_edit/* and require their own handling.