Schema Update

Returns a list of automatic discounts.

Returns a BulkOperation resource by ID.

Returns the list of business entities associated with the shop. Use this query to retrieve business entities for assigning to markets, managing payment providers per entity, or viewing entity attribution on orders.

Each shop can have multiple business entities with one designated as primary. To identify the primary entity in the query results, set the primary field to true.

Learn more about managing multiple legal entities.

Returns a paginated list of catalogs for the shop. Catalogs control which products are published and how they're priced in different contexts, such as international markets (Canada vs. United States), B2B company locations (different branches of the same business), or specific sales channels (such as online store vs. POS).

Filter catalogs by type and use the query argument to search and filter by additional criteria.

Learn more about Shopify Catalogs.

Returns a Channel resource by ID.

Returns active channels where merchants sell products and collections. Each channel is an authenticated link to an external platform such as marketplaces, social media platforms, online stores, or point-of-sale systems.

Returns a list of code-based discounts.

Available delivery options for a DraftOrder based on the provided input. The query returns shipping rates, local delivery rates, and pickup locations that merchants can choose from when creating draft orders.

Accepts draft order details including LineItem objects, MailingAddress for shipping, and discounts to determine which delivery methods are available. Pagination parameters control the number of local pickup options returned.

Returns the shop's inventory configuration, including all inventory quantity names. Quantity names represent different inventory states that merchants use to track inventory.

Retrieves an InventoryShipment by ID. Returns tracking details, InventoryShipmentLineItem objects with quantities, and the shipment's current InventoryShipmentStatus.

Returns an InventoryTransfer by ID. Inventory transfers track the movement of inventory between locations, including origin and destination details, InventoryTransferLineItem objects, quantities, and InventoryTransferStatus values.

Returns a paginated list of InventoryTransfer objects between locations. Transfers track the movement of InventoryItem objects between Location objects.

Supports filtering transfers using query parameters and sorting by various criteria. Use the connection's edges to access transfer details including InventoryTransferLineItem objects, quantities, and shipment status.

Retrieves navigation menus. Menus organize content into hierarchical navigation structures that merchants can display in the online store (for example, in headers, footers, and sidebars) and customer accounts.

Each Menu contains a handle for identification, a title for display, and a collection of MenuItem objects that can be nested up to 3 levels deep. Default menus have protected handles that can't be modified.

Retrieves the status of a deferred payment by its payment reference ID. Use this query to monitor the processing status of payments that are initiated through payment mutations. Deferred payments are called payment terms in the API.

The query returns an OrderPaymentStatus object that includes the current payment status, any error messages, and associated transactions. Poll this query to track asynchronous payment processing after initiating a deferred payment.

Returns a paginated list of product types assigned to products in the store. The maximum page size is 1000.
The maximum page size is 1000.

Retrieves a Publication by ID.

Returns null if the publication doesn't exist.

Returns a paginated list of Publication.

Filter publications by CatalogType.

Calculates the financial outcome of a Return without creating it. Use this query to preview return costs before initiating the actual return process.

The calculation provides detailed breakdowns of refund amounts, taxes, RestockingFee charges, return shipping fees, and order-level discount adjustments based on the FulfillmentLineItem objects that customers select for return.

Learn more about building for return management.

Returns the full library of available return reason definitions.

Use this query to retrieve the standardized return reasons available for creating returns.
Filter by IDs or handles to get specific definitions.

Only non-deleted reasons should be shown to customers when creating new returns.
Deleted reasons have been replaced with better alternatives and are no longer recommended.
However, they remain valid options and may still appear on existing returns.

Retrieves a paginated list of SellingPlanGroup objects that belong to the app making the API call. Selling plan groups are selling methods like subscriptions, preorders, or other purchase options that merchants offer to customers.

Each group has one or more SellingPlan objects that define specific billing and delivery schedules, pricing adjustments, and policies. Use the query argument to search by name or filter results by other criteria.

Learn more about building selling plans.

Returns the Shopify Payments account information for the shop. Includes current balances across all currencies, payout schedules, and bank account configurations.

The account includes ShopifyPaymentsBalanceTransaction records showing charges, refunds, and adjustments that affect your balance. Also includes ShopifyPaymentsDispute records and ShopifyPaymentsPayout history between the account and connected ShopifyPaymentsBankAccount configurations.

Retrieves a SubscriptionContract by ID.

The contract tracks the subscription's lifecycle through various statuses, and links to related billing attempts, generated Order objects, and the customer's CustomerPaymentMethod.

Returns a SubscriptionContractConnection containing subscription contracts. Subscription contracts are agreements between customers and merchants for recurring purchases with defined billing and delivery schedules.

Filter results with the query argument. You can paginate results using standard cursor-based pagination.

Access to Shopify's standardized product taxonomy for categorizing products. The Taxonomy organizes products into a hierarchical tree structure with categories, attributes, and values.

Query categories using search terms, or navigate the hierarchy by requesting children, siblings, or descendants of specific categories. Each TaxonomyCategory includes its position in the tree, parent-child relationships, and associated attributes for that product category.

Modifies which contexts, like markets or B2B company locations, can access a Catalog. You can add or remove contexts to control where the catalog's products and prices are available.

Learn more about managing catalog contexts and managing B2B catalogs.

Creates a Catalog that controls product availability and pricing for specific contexts like markets or B2B company locations. Catalogs use Publication objects to determine which products are available and PriceList objects to set custom pricing.

You can optionally associate a publication and price list when creating the catalog, or add them later using separate mutations.

Learn more about managing catalog contexts and using catalogs for different markets.

Updates an existing catalog's configuration. Catalogs control product publishing and pricing for specific contexts like markets or B2B company locations.

You can modify the catalog's title, status, and associated context. You can also update the PriceList that determines pricing adjustments or the Publication that controls which products customers see.

Adds products to a Collection asynchronously and returns a Job to track the operation's progress. This mutation handles large product sets efficiently by processing them in the background.

You can poll the returned job using the job query to monitor completion status.

Note:
This mutation adds products in the order specified in the productIds argument.

Calculates the properties of a DraftOrder without creating it. Returns pricing information including CalculatedDraftOrderLineItem totals, shipping charges, applicable discounts, and tax calculations based on the provided Customer and MailingAddress information.

Use this mutation to preview total taxes and prices before creating a draft order. It's particularly useful when working with B2B PurchasingEntity or when you need to determine costs without committing to a draft order. Learn more about calculating draft orders for B2B purchasing entities.

Activates an inventory item at a Location by creating an InventoryLevel that tracks stock quantities. This enables you to manage inventory for a ProductVariant at the specified location.

When you activate an inventory item, you can set its initial quantities. The available argument sets the quantity that's available for sale. onHand argument sets the total physical quantity at the location. If you don't specify quantities, then available and onHand default to zero.

Caution:
As of version 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of version 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Learn more about managing inventory quantities and states.

Adjusts quantities for inventory items by applying incremental changes at specific locations. Each adjustment modifies the quantity by a delta value rather than setting an absolute amount.

The mutation tracks adjustments with a reason code and optional reference URI for audit trails. Returns an InventoryAdjustmentGroup that records all changes made in the operation.

Learn more about managing inventory quantities and states.

Caution:
As of version 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of version 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Activates or deactivates an inventory item at multiple locations. When you activate an InventoryItem at a Location, that location can stock and track quantities for that item. When you deactivate an inventory item at a location, the inventory item is no longer stocked at that location.

The mutation accepts an inventory item ID and a list of location-specific activation settings. It returns the updated inventory item and any activated InventoryLevel objects.

Learn more about managing inventory quantities and states.

Updates an InventoryItem's properties including whether inventory is tracked, cost, SKU, and whether shipping is required. Inventory items represent the goods available to be shipped to customers.

Moves inventory quantities for a single inventory item between different states at a single location. Use this mutation to reallocate inventory across quantity states without moving it between locations.

Each change specifies the quantity to move, the source state and location, and the destination state and location. The mutation returns an InventoryAdjustmentGroup that tracks all changes made in a single operation, providing an audit trail with the reason and reference document URI.

Caution:
As of version 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of version 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Sets an inventory item's on-hand quantities to specific absolute values at designated locations. The mutation takes a reason for tracking purposes and a reference document URI for audit trails.

Returns an InventoryAdjustmentGroup that tracks all changes made in this operation, including the delta values calculated from the previous quantities.

Caution:
As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Set quantities of specified name using absolute values. This mutation supports compare-and-set functionality to handle
concurrent requests properly. If ignoreCompareQuantity is not set to true,
the mutation will only update the quantity if the persisted quantity matches the compareQuantity value.
If the compareQuantity value does not match the persisted value, the mutation will return an error. In order to opt out
of the compareQuantity check, the ignoreCompareQuantity argument can be set to true.

Note:
Only use this mutation if calling on behalf of a system that acts as the source of truth for inventory quantities,
otherwise please consider using the inventoryAdjustQuantities mutation.

Opting out of the compareQuantity check can lead to inaccurate inventory quantities if multiple requests are made concurrently.
It is recommended to always include the compareQuantity value to ensure the accuracy of the inventory quantities and to opt out
of the check using ignoreCompareQuantity only when necessary.

Caution:
As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Set up scheduled changes of inventory items.

Caution:
As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Adds items to an inventory shipment.

Caution:
As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Adds a draft shipment to an inventory transfer.

Caution:
As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Adds an in-transit shipment to an inventory transfer.

Caution:
As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Receive an inventory shipment.

Caution:
As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Creates a draft inventory transfer to move inventory items between Location objects in your store. The transfer tracks which items to move, their quantities, and the origin and destination locations.

Use inventoryTransferMarkAsReadyToShip to mark the transfer as ready to ship.

Caution:
As of version 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of version 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Creates an inventory transfer in ready to ship.

Caution:
As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

This mutation allows duplicating an existing inventory transfer. The duplicated transfer will have the same
line items and quantities as the original transfer, but will be in a draft state with no shipments.

Caution:
As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

This mutation allows for the setting of line items on a Transfer. Will replace the items already set, if any.

Caution:
As of 2026-01, this mutation supports an optional idempotency key using the @idempotent directive.
As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Creates a payment for an Order using a stored PaymentMandate. A payment mandate represents the customer's authorization to charge their payment method for deferred payments, such as pre-orders or try-before-you-buy purchases.

The mutation processes the payment asynchronously and returns a Job for tracking the payment status. You can specify the payment amount to collect, and use the autoCapture argument to either immediately capture the payment or only authorize it for later capture. Each payment request requires a unique idempotencyKey to prevent duplicate charges. Subsequent calls with the same key return the original payment result rather than creating a new payment.

Learn more about deferred payments and payment mandates and idempotent requests.

Sends an email invoice for an Order.

You can customize the email recipient, sender, and subject line using the email argument.

Note:
Use store or staff account email addresses for the from and bcc input fields.

Sets or removes fixed prices for all variants of a Product on a PriceList. Simplifies pricing management when all variants of a product should have the same price on a price list, rather than setting individual variant prices.

When you add a fixed price for a product, all its ProductVariant objects receive the same price on the price list. When you remove a product's fixed prices, all variant prices revert to the price list's adjustment rules.

Adds media files to a Product, such as images, videos, or 3D models. Media files enhance product listings by providing visual representations that help customers understand the product.

The mutation accepts an array of CreateMediaInput objects, each specifying the source URL, content type, and optional alt text.

You can add multiple media files in a single request. The mutation adds all valid files and returns errors for any invalid ones.

Deletes media from a Product, such as images, videos, and 3D models.

When you delete media images, the mutation also removes any corresponding product images. The mutation returns the IDs of both the deleted media and any product images that the deletion removed.

Caution:
This action is irreversible. You can't recover deleted media.

Publishes a Product to specified Publication objects.

Products sold exclusively on subscription (requiresSellingPlan: true) can only be published to online stores.

Reorders media attached to a product, changing their sequence in product displays. The operation processes asynchronously to handle products with large media collections.

Specify the product ID and an array of moves, where each move contains a media ID and its new zero-based position.

Note:
Only include media items that need repositioning. Unchanged items maintain their relative order automatically.

The mutation returns a Job to track the reordering progress. Poll the job status to determine when the operation completes and media positions update across all sales channels.

Learn more about reordering product media.

Updates properties of media attached to a Product. You can modify alt text for accessibility or change preview images for existing media items.

Provide the product ID and an array of UpdateMediaInput objects. Each update specifies the media's ID and the properties to change. Updates apply only to media already attached to the product and don't affect their position in the product gallery.

Creates a Publication that controls which Product and Collection customers can access through a Catalog.

You can create an empty publication and add products later, or prepopulate it with all existing products. The autoPublish field determines whether the publication automatically adds newly created products.

Updates a Publication.

You can add or remove products from the publication, with a maximum of 50 items per operation. The autoPublish field determines whether new products automatically display in this publication.

Publishes a resource, such as a Product or Collection, to one or more publications.

For products to be visible in a channel, they must have an active ProductStatus. Products sold exclusively on subscription (requiresSellingPlan: true) can only be published to online stores.

You can schedule future publication by providing a publish date. Only online store channels support scheduled publishing.

Publishes a resource to the current Channel associated with the requesting app. The system determines the current channel by the app's API client ID. Resources include Product and Collection objects that implement the Publishable interface.

For products to be visible in the channel, they must have an active ProductStatus. Products sold exclusively on subscription (requiresSellingPlan: true) can only be published to online stores.

Unpublishes a resource, such as a Product or Collection, from one or more publications. The resource remains in your store but becomes unavailable to customers.

For products to be visible in a channel, they must have an active ProductStatus.

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:

• Refunding line items with optional restocking
• Refunding shipping costs
• Refunding duties and import taxes
• Refunding additional fees
• Processing refunds through different payment methods
• Issuing store credit refunds (when enabled)

You can create both full and partial refunds, and optionally allow over-refunding in specific
cases.

After creating a refund, you can track its status and details through the order's
refunds
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 the refundCreate mutation is similar to the
refundReturn
mutation. The key difference is that the refundCreate mutation lets you to specify restocking behavior
for line items, whereas the returnRefund mutation 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 @idempotent directive.
As of 2026-04, the idempotency key is required and must be provided using the @idempotent directive.
For more information, see the idempotency documentation.

Creates a selling plan group that defines how products can be sold and purchased. A selling plan group represents a selling method such as "Subscribe and save", "Pre-order", or "Try before you buy" and contains one or more selling plans with specific billing, delivery, and pricing policies.

Use the resources argument to associate products or product variants with the group during creation. You can also add products later using sellingPlanGroupAddProducts or sellingPlanGroupAddProductVariants.

Learn more about building selling plan groups or explore examples of creating TBYB and other selling plan groups.

Creates a billing attempt to charge for a SubscriptionContract. The mutation processes either the payment for the current billing cycle or for a specific cycle, if selected.

The mutation creates an Order when successful. Failed billing attempts include a processingError field with error details.

Tip:
Use the idempotencyKey to ensure the billing attempt executes only once, preventing duplicate charges if the request is retried.

You can target a specific billing cycle using the billingCycleSelector to bill past or future cycles. The originTime parameter adjusts fulfillment scheduling for attempts completed after the expected billing date.

Learn more about creating billing attempts.

Creates a subscription contract draft, which is an intention to create a new subscription. The draft lets you incrementally build and modify subscription details before committing them to create the actual SubscriptionContract.

The mutation requires Customer information, billing details, and contract configuration including the SubscriptionBillingPolicy and SubscriptionDeliveryPolicy. You can specify the CustomerPaymentMethod, the MailingAddress for shipping, and subscription intervals.

After you create the draft, you can either modify it with the subscriptionDraftUpdate mutation or finalize and create the active subscription contract with subscriptionDraftCommit.

Learn more about building subscription contracts.

Creates a draft of an existing SubscriptionContract. The draft captures the current state of the contract and allows incremental modifications through draft mutations such as subscriptionDraftLineAdd, subscriptionDraftDiscountAdd, and subscriptionDraftUpdate.

Changes remain in draft state and don't affect the live contract until committed. After you've made all necessary changes to the draft, commit it using subscriptionDraftCommit to apply the updates to the original contract.

Learn more about updating subscription contracts.

Adds tags to a resource in the store. Supported resources include Order, DraftOrder, Customer, Product, and Article.

Tags help merchants organize and filter resources. See the tags argument for supported input formats.

Learn more about using tags to organize subscription orders.

Removes tags from an Order, DraftOrder, Customer, Product, or Article.

Tags are searchable keywords that help organize and filter these resources.

Creates a theme from an external URL or staged upload. The theme source can either be a ZIP file hosted at a public URL or files previously uploaded using the stagedUploadsCreate mutation. The theme displays in the Themes page in the Shopify admin.

New themes have an UNPUBLISHED role by default. You can optionally specify a DEVELOPMENT role for temporary themes used during development.