11/18/2026, 12:00:38 AM
Many mutations now accept a skipEvents Boolean argument, allowing developers to prevent events such as webhooks from being emitted. The cashDrawers and segments queries have gained a created_at filter, enabling time‑range filtering of records. DeliveryProfile and deliveryProfiles query descriptions have been updated to explain the behavior when a shop uses market‑driven shipping and that merchant‑owned profiles are ignored during checkout. The automationWorkflowRun and automationWorkflowRuns field descriptions now state that each request can make at most 32 read operations; exceeding this limit returns a BAD_REQUEST error. The AutomationStepRun type has been enriched with new diagnostic fields—condition, conditionalOutput, error, input, logs, and output—backed by the newly introduced AutomationRunData type, providing deeper runtime insight. Additional input objects now allow configuring recurring billing policy payment options, and the returnRefund mutation, while still deprecated, now supports the skipEvents argument. Collectively, these updates give developers finer event control, improved query filtering, clearer shipping profile behavior, and richer automation diagnostics.
Returns one production or test run of an automation, with its run-level fields. Returns null when no run with the ID exists or its automation isn't readable. This read is one of the request's automation run reads. A request makes at most 32, and each read after that returns a BAD_REQUEST error.
Returns a page of an automation's production or test runs, newest first, with their run-level fields. Each call examines at most first runs, so a page can have fewer results, or none, and still return a continuation. Returns null when no automation with the ID exists or it isn't readable. This read is one of the request's automation run reads. A request makes at most 32, and each read after that returns a BAD_REQUEST error.
A list of cash drawers in the shop.
Retrieves a DeliveryProfile by ID. Delivery profiles group shipping settings for specific Product objects that ship from selected Location objects to [delivery zones](https://shopify.dev/docs/api/admin-graphql/latest/objects/DeliveryZone with defined rates.
If the shop uses market-driven shipping, checkout ignores the zones and rates on merchant-managed profiles, so they can differ from what buyers pay. See DeliveryProfile for details.
Learn more about delivery profiles.
Returns a paginated list of DeliveryProfile objects for the shop. Delivery profiles group Product and ProductVariant objects that share shipping rates and zones.
Each profile contains DeliveryLocationGroup objects that organize fulfillment Location objects and their associated delivery zones. DeliveryZone objects define geographic regions with specific shipping methods and rates. Use the merchantOwnedOnly filter to exclude profiles that third-party apps manage.
If the shop uses market-driven shipping, checkout ignores the zones and rates on merchant-managed profiles, so they can differ from what buyers pay. See DeliveryProfile for details.
Learn more about delivery profiles.
Returns a paginated list of Segment objects for the shop. Segments are dynamic groups of customers that meet specific criteria defined through ShopifyQL queries. You can filter segments by search query and sort them by creation date or other criteria.
The query supports standard pagination arguments and returns a SegmentConnection containing segment details including names, creation dates, and the query definitions that determine segment membership.
Creates a DeliveryProfile that defines shipping rates for specific products and locations.
A delivery profile groups products with their shipping zones and rates. You can associate profiles with SellingPlanGroup objects to customize shipping for subscriptions and pre-orders. Each profile contains DeliveryProfileLocationGroup objects that specify which Location objects ship to which DeliveryZone objects with specific DeliveryMethodDefinition objects and rates.
Shops that use market-driven shipping: If the shop uses market-driven shipping (check it with shop { features { marketDrivenShipping } }, see ShopFeatures.marketDrivenShipping), checkout combines the shipping rates and options from the shop's market configuration and app-owned delivery profiles. Zones and rates from merchant-managed delivery profiles are ignored. In practice, merchant-managed profiles are the profiles that the merchantOwnedOnly filter returns. A merchant-managed profile that you create is still saved, but its zones and rates have no effect on checkout while the merchant is using market-driven shipping. They apply again if the shop reverts to the legacy shipping profile system and stops using market-driven shipping. To set shipping options for a market-driven shipping shop, use marketUpdate or marketCreate and set the delivery.shipping input, or target an app-owned delivery profile. The marketDrivenShipping check and the delivery input on marketUpdate and marketCreate require API version 2026-07 or later.
Product and variant assignment still takes effect: Associating a product, variant or selling plan group moves it out of its current profile, including a profile that an app manages. That can change the rates buyers see at checkout.
Learn more about building delivery profiles.
Updates a DeliveryProfile's configuration, including its shipping zones, rates, and associated products.
Modify location groups to control which fulfillment Location objects serve specific geographic areas. Add or remove shipping zones with custom countries and provinces. Create or update shipping methods with rate definitions and delivery conditions. Associate or dissociate ProductVariant objects and SellingPlanGroup objects to determine which products use this profile's shipping rules.
The mutation supports partial updates through dedicated input fields for creating, updating, and deleting specific components without affecting the entire profile structure.
Shops that use market-driven shipping: If the shop uses market-driven shipping (check it with shop { features { marketDrivenShipping } }, see ShopFeatures.marketDrivenShipping), checkout combines the shipping rates and options from the shop's market configuration and app-owned delivery profiles. Zones and rates from merchant-managed delivery profiles are ignored. In practice, merchant-managed profiles are the profiles that the merchantOwnedOnly filter returns. Changes to the zones, rates, method definitions and conditions of these profiles are still saved, but they have no effect on checkout while the merchant is using market-driven shipping. The changes apply again if the shop reverts to the legacy shipping profile system and stops using market-driven shipping. To modify shipping options for market-driven shipping shop, use marketUpdate and set the delivery.shipping input, or target an app-owned delivery profile. The marketDrivenShipping check and the delivery input on marketUpdate require API version 2026-07 or later.
Product and variant assignment still takes effect: Associating a product, variant or selling plan group moves it out of its current profile, including a profile that an app manages. That can change the rates buyers see at checkout.
Learn more about building delivery profiles.
Cancels an existing Fulfillment and reverses its effects on associated FulfillmentOrder objects. When you cancel a fulfillment, the system creates new fulfillment orders for the cancelled items so they can be fulfilled again.
The cancellation affects fulfillment orders differently based on their fulfillment status. If a fulfillment order was entirely fulfilled, then it automatically closes. If a fulfillment order is partially fulfilled, then the remaining quantities adjust to include the cancelled items. The system creates new fulfillment orders at the original Location when items are still stocked there, or at alternative locations based on the store's fulfillment priority settings.
Learn more about canceling fulfillments.
Creates a fulfillment for one or more FulfillmentOrder objects. The fulfillment orders are associated with the same Order and are assigned to the same Location.
Use this mutation to mark items as fulfilled when they're ready to ship. You can specify tracking information, customer notification preferences, and which FulfillmentOrderLineItem objects to fulfill from each fulfillment order. If you don't specify line items, then the mutation fulfills all items in the fulfillment order.
Learn more about building fulfillment solutions.
Creates a FulfillmentEvent to track the shipment status and location of items that have shipped. Events capture status updates like carrier pickup, in transit, out for delivery, or delivered.
Each event records the timestamp and current status of the Fulfillment. You can include optional details such as the location where the event occurred, estimated arrival time, and messages for tracking purposes.
Accepts a fulfillment request that the fulfillment service has received for a FulfillmentOrder which signals that the fulfillment service will process and fulfill the order. The fulfillment service can optionally provide a message to the merchant and an estimated shipped date when accepting the request.
Learn more about accepting fulfillment requests.
Applies a fulfillment hold on a fulfillment order.
As of the
2025-01 API version,
the mutation can be successfully executed on fulfillment orders that are already on hold.
To place multiple holds on a fulfillment order, apps need to supply the
handle
field. Each app can place up to
10 active holds
per fulfillment order. If an app attempts to place more than this, the mutation will return
a user error indicating that the limit has been reached.
The app would need to release one of its existing holds before being able to apply a new one.
Changes the location which is assigned to fulfill a number of unfulfilled fulfillment order line items.
Moving a fulfillment order will fail in the following circumstances:
Line items which have already been fulfilled can't be re-assigned
and will always remain assigned to the original location.
You can't change the assigned location while a fulfillment order has a
request status
of SUBMITTED, ACCEPTED, CANCELLATION_REQUESTED, or CANCELLATION_REJECTED.
These request statuses mean that a fulfillment order is awaiting action by a fulfillment service
and can't be re-assigned without first having the fulfillment service accept a cancellation request.
This behavior is intended to prevent items from being fulfilled by multiple locations or fulfillment services.
First scenario: Re-assign all line items belonging to a fulfillment order to a new location.
In this case, the
assignedLocation
of the original fulfillment order will be updated to the new location.
Second scenario: Re-assign a subset of the line items belonging to a fulfillment order to a new location.
You can specify a subset of line items using the fulfillmentOrderLineItems parameter
(available as of the 2023-04 API version),
or specify that the original fulfillment order contains line items which have already been fulfilled.
If the new location is already assigned to another active fulfillment order, on the same order, then
a new fulfillment order is created. The existing fulfillment order is closed and line items are recreated
in a new fulfillment order.
Reschedules a scheduled fulfillment order.
Updates the value of the fulfillAt field on a scheduled fulfillment order.
The fulfillment order will be marked as ready for fulfillment at this date and time.
Sends a fulfillment request to the fulfillment service assigned to a FulfillmentOrder. The fulfillment service must then accept or reject the request before processing can begin.
You can either request fulfillment for all line items or specify individual items with quantities for partial fulfillment. When requesting partial fulfillment, Shopify splits the original fulfillment order into two: one with the submitted items and another with the remaining unsubmitted items. Include an optional message to communicate special instructions to the fulfillment service, such as gift wrapping or handling requirements.
Learn more about managing fulfillment requests as a fulfillment service.
Cancels an order, with options for refunding, restocking inventory, and customer notification.
Caution:
Order cancellation is irreversible. An order that has been cancelled can't be restored to its original state.
Use the orderCancel mutation to programmatically cancel orders in scenarios such as:
The orderCancel mutation provides flexible refund options including refunding to original payment methods
or issuing store credit. If a payment was only authorized (temporarily held) but not yet charged,
that hold will be automatically released when the order is cancelled, even if you choose not to refund other payments.
If the order has an existing
write-off,
calling this mutation can reduce the written-off amount automatically when the cancellation includes a
refund that reduces the order total before write-offs below the remaining written-off amount.
The mutation supports different cancellation reasons: customer requests, payment declines, fraud,
inventory issues, staff errors, or other unspecified reasons. Each cancellation can include optional
staff notes for internal documentation (notes aren't visible to customers).
An order can only be cancelled if it meets the following criteria:
Orders might be assigned to locations that become
deactivated
after the order was created. When cancelling such orders, inventory behavior depends on payment status:
After you cancel an order, you can still make limited updates to certain fields (like
notes and tags) using theorderUpdate.
For partial refunds or more complex refund scenarios on active orders,
such as refunding only specific line items while keeping the rest of the order fulfilled,
consider using the refundCreate
mutation instead of full order cancellation.
Learn how to build apps that integrate with
order management and fulfillment processes.
Creates an order with attributes such as customer information, line items, and shipping and billing addresses.
Use the orderCreate mutation to programmatically generate orders in scenarios where
orders aren't created through the standard checkout process, such as when importing orders from an external
system or creating orders for wholesale customers.
The orderCreate mutation doesn't support applying multiple discounts, such as discounts on line items.
Automatic discounts won't be applied unless you replicate the logic of those discounts in your custom
implementation. You can apply a discount code,
but only one discount code can be set for each order.
Note:
If you're using theorderCreatemutation with a
trial or
development store, then you can create a
maximum of five new orders per minute.
After you create an order, you can make subsequent edits to the order using one of the following mutations:
orderUpdate:orderEditBegin:orderEditBegin mutation initiates an order editing session,orderEditBeginLearn how to build apps that integrate with
order management and fulfillment processes.
Creates a refund for an order, allowing you to process returns and issue payments back to customers.
Use the refundCreate mutation to programmatically process refunds in scenarios where you need to
return money to customers, such as when handling returns, processing chargebacks, or correcting
order errors.
The refundCreate mutation supports various refund scenarios:
You can create both full and partial refunds, and optionally allow over-refunding in specific
cases.
If the order has an existing
write-off,
calling this mutation can reduce the written-off amount automatically when it reduces the order total
before write-offs below the remaining written-off amount.
After creating a refund, you can track its status and details through the order'srefunds
field. The refund is associated with the order and can be used for reporting and reconciliation purposes.
Learn more about
managing returns
and refunding duties.
Note:
The refunding behavior of therefundCreatemutation is similar to thereturnRefund
mutation. The key difference is that therefundCreatemutation lets you to specify restocking behavior
for line items, whereas thereturnRefundmutation focuses solely on handling the financial refund without
any restocking input.
Caution:
As of 2026-01, this mutation supports an optional idempotency key using the@idempotentdirective.
As of 2026-04, the idempotency key is required and must be provided using the@idempotentdirective.
For more information, see the idempotency documentation.
Indicates a return is complete, either when a refund has been made and items restocked,
or simply when it has been marked as returned in the system.
Creates a return from an existing order that has at least one fulfilled
line item
that hasn't yet been refunded. If you create a return on an archived order, then the order is automatically
unarchived.
Use the returnCreate mutation when your workflow involves
approving or
declining requested returns
outside of the Shopify platform.
The returnCreate mutation performs the following actions:
OPEN state, and assumes that the return request from the customer has already beenIf the order has an existing
write-off,
calling this mutation can reduce the written-off amount automatically when it reduces the order total
before write-offs below the remaining written-off amount.
After you've created a return, use thereturn query to retrieve the
return by its ID. Learn more about providing a
return management workflow
for merchants.
Declines a return on an order.
When a return is declined, each ReturnLineItem.fulfillmentLineItem can be associated to a new return.
Use the ReturnCreate or ReturnRequest mutation to initiate a new return.
Creates a refund for items being returned when the return status is OPEN or CLOSED. This mutation processes the financial aspects of a return by refunding line items, shipping costs, and duties back to the customer.
If the order has an existing
write-off,
calling this mutation can reduce the written-off amount automatically when it reduces the order total
before write-offs below the remaining written-off amount.
Creates a return request that requires merchant approval before processing. The return has its status set to REQUESTED and the merchant must approve or decline it.
Use this mutation when customers initiate returns that need review. After creating a requested return, use returnApproveRequest to approve it or returnDeclineRequest to decline it.
For returns that should be immediately open for processing, use the returnCreate mutation instead.
Learn more about building return management workflows.
A diagnostic of a recorded step execution, read only when selected. The state field says whether value is available, because null alone can't tell missing data from a recorded JSON null. A diagnostic field is null with an ACCESS_DENIED error when the run's step details aren't readable with the current permissions. While a TEST run is in progress and its permission requirements aren't searchable yet, a diagnostic field is null with an UNAVAILABLE error ("This test run's step details aren't readable yet. Try again."). Retry with backoff. If the requirements still aren't searchable 4 minutes after the test started, the field is an ACCESS_DENIED error; start a new test run. PRODUCTION runs never return UNAVAILABLE.
Represents how a recurring billing policy may be paid.
The input fields for how a recurring billing policy may be paid.
Represents how a subscription contract's recurring billing attempts may be paid.
The input fields for how a subscription contract's recurring billing attempts may be paid.
conditionA condition execution's definition, from the automation version that the execution recorded, never the current version. The value is a flat list of nodes. Each node's kind is COMPARISON, LOGICAL_EXPRESSION, ARRAY_EXPRESSION, ENVIRONMENT_VALUE, or LITERAL_VALUE, and its uuid matches opId in conditionalOutput. The state is definition_unavailable when that version or its step is missing or, for a test run, when the definition doesn't compile or its compiled digest is missing or differs from the digest that the run recorded. For a test run, the field returns an access denied error, not a state, when the current permissions don't allow a test of the definition. The state is not_applicable when the execution isn't a condition. Each execution that selects this field is one of the request's automation run reads. A request makes at most 32, and each read after that returns a BAD_REQUEST error.
conditionalOutputA condition execution's recorded observations, as a list of opId, iterationTrail, and output. The output is a string: the text of a scalar, or the JSON text of an object or an array. An operation can have several observations from list iterations. A missing observation isn't false. The state is too_many_results when the execution has more than 500 stored records, rollover copies included. The value is never truncated, and this field has no continuation. The state is checkpoint_changed when a record is newer than the execution's checkpoint. Each execution that selects this field is one of the request's automation run reads. A request makes at most 32, and each read after that returns a BAD_REQUEST error.
errorThe execution's error as a summary, optional details, and causes: at most 10 error nodes, the root included, nested at most 10 levels deep. Causes beyond those limits are dropped and marked truncated. Exception classes and backtraces aren't returned. Each execution that selects this field is one of the request's automation run reads. A request makes at most 32, and each read after that returns a BAD_REQUEST error.
inputThe execution's parsed input. A wait step's internal routing fields are removed. Each execution that selects this field is one of the request's automation run reads. A request makes at most 32, and each read after that returns a BAD_REQUEST error.
logsThe message that the execution recorded in its output. This isn't a run-wide log stream. Each execution that selects this field is one of the request's automation run reads. A request makes at most 32, and each read after that returns a BAD_REQUEST error.
outputThe execution's parsed output. For a wait step, this is its hydrated continuation when it has one, without internal routing fields. Each execution that selects this field is one of the request's automation run reads. A request makes at most 32, and each read after that returns a BAD_REQUEST error.
stepRunstepRunsprofileLocationGroupsestimatedArrivalThe date the merchant expects the purchase order to arrive, as entered on the purchase order.
paymentConfigurationThe payment configuration for recurring billing attempts.
WRITE_OFF_ORDERSpaymentConfigurationThe payment configuration for the subscription contract's recurring billing attempts, resolved from the contract version being queried.
paymentConfigurationThe payment configuration that the contract's recurring billing attempts use if you commit the calculation.
paymentConfigurationThe payment configuration for the subscription contract's recurring billing attempts, resolved from the contract version being queried.
paymentConfigurationThe payment configuration for the subscription contract's recurring billing attempts, resolved from the contract version being queried.
SUPPLIER_ACCOUNTS_DELETESUPPLIER_ACCOUNTS_UPDATE