User
Represents an error in the input of a mutation.
Anchor to FieldsFields
- Anchor to fieldfield•[String!]
The path to the input field that caused the error.
- Anchor to messagemessage•String!non-null
The error message.
Anchor to MutationsMutations
- •mutation
Charges a shop for features or services one time. This type of charge is recommended for apps that aren't billed on a recurring basis. Test and demo shops aren't charged.
- •mutation
Cancels an app subscription on a store.
- •mutation
Allows an app to charge a store for features or services on a recurring basis.
- •mutation
Updates the capped amount on the usage pricing plan of an app subscription line item.
- •mutation
Enables an app to charge a store for features or services on a per-use basis. The usage charge value is counted towards the
limit that was specified in thefield when the app subscription was created. If you create an app usage charge that causes the total usage charges in a billing interval to exceed the capped amount, then aTotal price exceeds balance remainingerror is returned.- •mutation
Starts the cancelation process of a running bulk operation.
There may be a short delay from when a cancelation starts until the operation is actually canceled.
- •mutation
Adds products to a collection.
- •mutation
Creates a collection to group products together in the online store and other sales channels. For example, an athletics store might create different collections for running attire, shoes, and accessories.
There are two types of collections:
- Custom (manual) collections: You specify the products to include in a collection.
- Smart (automated) collections: You define rules, and products matching those rules are automatically included in the collection.
Use the
mutation when you need to:- Create a new collection for a product launch or campaign
- Organize products by category, season, or promotion
- Automate product grouping using rules (for example, by tag, type, or price)
NoteLearn more about using metafields with smart collections.
- •mutation
Deletes a collection.
- •mutation
Removes a set of products from a given collection. The mutation can take a long time to run. Instead of returning an updated collection the mutation returns a job, which should be polled. For use with manual collections only.
- •mutation
Asynchronously reorders a set of products within a specified collection. Instead of returning an updated collection, this mutation returns a job, which should be polled. The
must be. Displaced products will have their position altered in a consistent manner, with no gaps.- •mutation
Updates a collection, modifying its properties, products, or publication settings. Collections help organize products together in the online store and other sales channels.
Use the
mutation to programmatically modify collections in scenarios such as:- Updating collection details, like title, description, or image
- Modifying SEO metadata for better search visibility
- Changing which products are included (using rule updates for smart collections)
- Publishing or unpublishing collections across different sales channels
- Updating custom data using metafields
There are two types of collections with different update capabilities:
- Custom (manual) collections: You can update collection properties, but rule sets can't be modified since products are manually selected.
- Smart (automated) collections: You can update both collection properties and the rules that automatically determine which products are included.
When updating rule sets for smart collections, the operation might be processed asynchronously. In these cases, the mutation returns a
jobobject that you can use to track the progress of the update.
To publish or unpublish collections to specific sales channels, use the dedicated
andmutations.Learn more about using metafields with smart collections.
- •mutation
Create a new customer address.
- •mutation
Deletes a customer's address.
- •mutation
Update a customer's address information.
- •mutation
Add tax exemptions for the customer.
- •mutation
Create a new customer. As of API version 2022-10, apps using protected customer data must meet the protected customer data requirements.
- •mutation
Delete a customer. As of API version 2022-10, apps using protected customer data must meet the protected customer data requirements.
- •mutation
Generate an account activation URL for a customer.
- •mutation
Creates a credit card payment method for a customer using a session id. These values are only obtained through card imports happening from a PCI compliant environment. Please use customerPaymentMethodRemoteCreate if you are not managing credit cards directly.
- •mutation
Updates the credit card payment method for a customer.
- •mutation
Revokes a customer's payment method.
- •mutation
Sends a link to the customer so they can update a specific payment method.
- •mutation
Remove tax exemptions from a customer.
- •mutation
Replace tax exemptions for a customer.
- •mutation
Update a customer's attributes. As of API version 2022-10, apps using protected customer data must meet the protected customer data requirements.
- •mutation
Updates a customer's default address.
- •mutation
Create a delivery profile.
- •mutation
Enqueue the removal of a delivery profile.
- •mutation
Update a delivery profile.
- •mutation
Updates the delivery promise participants by adding or removing owners based on a branded promise handle.
- •mutation
Set the delivery settings for a shop.
- •mutation
Assigns a location as the shipping origin while using legacy compatibility mode for multi-location delivery profiles.
- •mutation
Adds tags to multiple draft orders.
- •mutation
Deletes multiple draft orders.
- •mutation
Removes tags from multiple draft orders.
- •mutation
Calculates the properties of a draft order. Useful for determining information such as total taxes or price without actually creating a draft order.
- •mutation
Completes a draft order and converts it into a regular order. The order appears in the merchant's orders list, and the customer can be notified about their order.
Use the
mutation when a merchant is ready to finalize a draft order and create a real order in their store. Themutation also supports sales channel attribution for tracking order sources using theargument, cart validation controls for app integrations, and detailed error reporting for failed completions.You can complete a draft order with different payment scenarios:
- Mark the order as paid immediately.
- Set the order as payment pending using payment terms.
- Specify a custom payment amount.
- Select a specific payment gateway.
NoteWhen completing a draft order, inventory is reserved for the items in the order. This means the items will no longer be available for other customers to purchase. Make sure to verify inventory availability before completing the draft order.
- •mutation
Creates a draft order with attributes such as customer information, line items, shipping and billing addresses, and payment terms. Draft orders are useful for merchants that need to:
- Create new orders for sales made by phone, in person, by chat, or elsewhere. When a merchant accepts payment for a draft order, an order is created.
- Send invoices to customers with a secure checkout link.
- Use custom items to represent additional costs or products not in inventory.
- Re-create orders manually from active sales channels.
- Sell products at discount or wholesale rates.
- Take pre-orders.
After creating a draft order, you can:
- Send an invoice to the customer using the
mutation. - Complete the draft order using the
mutation. - Update the draft order using the
mutation. - Duplicate a draft order using the
mutation. - Delete the draft order using the
mutation.
NoteWhen you create a draft order, you can't reserve or hold inventory for the items in the order by default. However, you can reserve inventory using the
input.- •mutation
Creates a draft order from order.
- •mutation
Deletes a draft order.
- •mutation
Duplicates a draft order.
- •mutation
Previews a draft order invoice email.
- •mutation
Sends an email invoice for a draft order.
- •mutation
Updates a draft order.
If a checkout has been started for a draft order, any update to the draft will unlink the checkout. Checkouts are created but not immediately completed when opening the merchant credit card modal in the admin, and when a buyer opens the invoice URL. This is usually fine, but there is an edge case where a checkout is in progress and the draft is updated before the checkout completes. This will not interfere with the checkout and order creation, but if the link from draft to checkout is broken the draft will remain open even after the order is created.
- •mutation
Triggers any workflows that begin with the trigger specified in the request body. To learn more, refer to Create Shopify Flow triggers.
- •mutation
Cancels a fulfillment.
- •mutation
Creates a fulfillment for one or many fulfillment orders. The fulfillment orders are associated with the same order and are assigned to the same location.
- •mutation
Creates a fulfillment event for a specified fulfillment.
- •mutation
Accept a cancellation request sent to a fulfillment service for a fulfillment order.
- •mutation
Accepts a fulfillment request sent to a fulfillment service for a fulfillment order.
- •mutation
Marks a fulfillment order as canceled.
- •mutation
Marks an in-progress fulfillment order as incomplete, indicating the fulfillment service is unable to ship any remaining items, and closes the fulfillment request.
This mutation can only be called for fulfillment orders that meet the following criteria:
- Assigned to a fulfillment service location,
- The fulfillment request has been accepted,
- The fulfillment order status is
.
This mutation can only be called by the fulfillment service app that accepted the fulfillment request. Calling this mutation returns the control of the fulfillment order to the merchant, allowing them to move the fulfillment order line items to another location and fulfill from there, remove and refund the line items, or to request fulfillment from the same fulfillment service again.
Closing a fulfillment order is explained in the fulfillment service guide.
- •mutation
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:
- The fulfillment order is closed.
- The destination location doesn't stock the requested inventory item.
- The API client doesn't have the correct permissions.
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
,,, or. 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.How re-assigning line items affects fulfillment orders
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
parameter (available as of the2023-04API 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.
- •mutation
Marks a scheduled fulfillment order as open.
- •mutation
Rejects a cancellation request sent to a fulfillment service for a fulfillment order.
- •mutation
Rejects a fulfillment request sent to a fulfillment service for a fulfillment order.
- •mutation
Sends a cancellation request to the fulfillment service of a fulfillment order.
- •mutation
Sends a fulfillment request to the fulfillment service of a fulfillment order.
- •mutation
Creates a fulfillment service.
Fulfillment service location
When creating a fulfillment service, a new location will be automatically created on the shop and will be associated with this fulfillment service. This location will be named after the fulfillment service and inherit the shop's address.
If you are using API version
2023-10or later, and you need to specify custom attributes for the fulfillment service location (for example, to change its address to a country different from the shop's country), use the LocationEdit mutation after creating the fulfillment service.- •mutation
Deletes a fulfillment service.
- •mutation
Updates a fulfillment service.
If you are using API version
2023-10or later, and you need to update the location managed by the fulfillment service (for example, to change the address of a fulfillment service), use the LocationEdit mutation.- •mutation
Updates tracking information for a fulfillment.
- •mutation
Update a gift card.
- •mutation
Activate an inventory item at a location.
- •mutation
Removes an inventory item's quantities from a location, and turns off inventory at the location.
- •mutation
Updates an inventory item.
- •mutation
Create new marketing activity. Marketing activity app extensions are deprecated and will be removed in the near future.
- •mutation
Updates a marketing activity with the latest information. Marketing activity app extensions are deprecated and will be removed in the near future.
- •mutation
Deletes multiple metafields in bulk.
- •mutation
Cancels an order, with options for refunding, restocking inventory, and customer notification.
CautionOrder cancellation is irreversible. An order that has been cancelled can't be restored to its original state.
Use the
mutation to programmatically cancel orders in scenarios such as:- Customer-requested cancellations due to size, color, or other preference changes
- Payment processing failures or declined transactions
- Fraud detection and prevention
- Insufficient inventory availability
- Staff errors in order processing
- Wholesale or B2B order management workflows
The
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.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:
- The order hasn't already been cancelled.
- The order has no pending payment authorizations.
- The order has no active returns in progress.
- The order has no outstanding fulfillments that can't be cancelled.
Orders might be assigned to locations that become deactivated after the order was created. When cancelling such orders, inventory behavior depends on payment status:
- Paid orders: Cancellation will fail with an error if restocking is enabled, since inventory can't be returned to deactivated locations.
- Unpaid orders: Cancellation succeeds but inventory is not restocked anywhere, even when the restock option is enabled. The committed inventory effectively becomes unavailable rather than being returned to stock at the deactivated location.
After you cancel an order, you can still make limited updates to certain fields (like notes and tags) using the
.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
mutation instead of full order cancellation.Learn how to build apps that integrate with order management and fulfillment processes.
- •mutation
Captures payment for an authorized transaction on an order. Use this mutation to claim the money that was previously reserved by an authorization transaction.
The
mutation can be used in the following scenarios:- To capture the full amount of an authorized transaction
- To capture a partial payment by specifying an amount less than the total order amount
- To perform multiple captures on the same order, as long as the order transaction is multi-capturable
NoteMulti-capture functionality is only available to stores on a Shopify Plus plan. For multi-currency orders, the
currencyfield is required and should match the presentment currency from the order.After capturing a payment, you can:
- View the transaction details including status, amount, and processing information.
- Track the captured amount in both shop and presentment currencies.
- Monitor the transaction's settlement status.
Learn more about order transactions.
- •mutation
Closes an open order.
- •mutation
Adds a custom line item to an existing order. For example, you could add a gift wrapping service as a custom line item. To learn how to edit existing orders, refer to Edit an existing order with Admin API.
- •mutation
Adds a discount to a line item on the current order edit. For more information on how to use the GraphQL Admin API to edit an existing order, refer to Edit existing orders.
- •mutation
Adds a line item from an existing product variant. As of API version 2025-04, the orderEditAddVariant API will respect the contextual pricing of the variant.
- •mutation
Starts editing an order. Mutations are operating on
. All order edits start with, have any number of* mutations made, and end with.- •mutation
Applies and saves staged changes to an order. Mutations are operating on
. All order edits start with, have any number of* mutations made, and end with.- •mutation
Sets the quantity of a line item on an order that is being edited. For more information on how to use the GraphQL Admin API to edit an existing order, refer to Edit existing orders.
- •mutation
Marks an order as paid by recording a payment transaction for the outstanding amount.
Use the
mutation to record payments received outside the standard checkout process. Themutation is particularly useful in scenarios where:- Orders were created with manual payment methods (cash on delivery, bank deposit, money order)
- Payments were received offline and need to be recorded in the system
- Previously authorized payments need to be captured manually
- Orders require manual payment reconciliation due to external payment processing
The mutation validates that the order can be marked as paid before processing. An order can be marked as paid only if it has a positive outstanding balance and its financial status isn't already
. The mutation will either create a new sale transaction for the full outstanding amount or capture an existing authorized transaction, depending on the order's current payment state.After successfully marking an order as paid, the order's financial status is updated to reflect the payment, and payment events are logged for tracking and analytics purposes.
Learn more about managing orders in apps.
- •mutation
Opens a closed order.
- •mutation
Updates the attributes of an order, such as the customer's email, the shipping address for the order, tags, and metafields associated with the order.
If you need to make significant updates to an order, such as adding or removing line items, changing quantities, or modifying discounts, then use the
mutation instead. Themutation initiates an order editing session, allowing you to make multiple changes before finalizing them. Learn more about using themutation to edit existing orders.Learn how to build apps that integrate with order management and fulfillment processes.
- •mutation
Creates a new componentized product.
- •mutation
Updates a componentized product.
- •mutation
Creates a product with attributes such as title, description, vendor, and media.
The
mutation helps you create many products at once, avoiding the tedious or time-consuming process of adding them one by one in the Shopify admin. Common examples include creating products for a new collection, launching a new product line, or adding seasonal products.You can define product options and values, allowing you to create products with different variations like sizes or colors. You can also associate media files to your products, including images and videos.
The
mutation only supports creating a product with its initial product variant. To create multiple product variants for a single product and manage prices, use themutation.NoteThe
mutation has a throttle that takes effect when a store has 50,000 product variants. After this threshold is reached, no more than 1,000 new product variants can be created per day.After you create a product, you can make subsequent edits to the product using one of the following mutations:
: Used to publish the product and make it available to customers. Themutation creates products in an unpublished state by default, so you must perform a separate operation to publish the product.: Used to update a single product, such as changing the product's title, description, vendor, or associated media.: Used to perform multiple operations on products, such as creating or modifying product options and variants.
Learn more about the product model and adding product data.
- •mutation
Permanently deletes a product and all its associated data, including variants, media, publications, and inventory items.
Use the
mutation to programmatically remove products from your store when they need to be permanently deleted from your catalog, such as when removing discontinued items, cleaning up test data, or synchronizing with external inventory management systems.The
mutation removes the product from all associated collections, and removes all associated data for the product, including:- All product variants and their inventory items
- Product media (images, videos) that are not referenced by other products
- Product options and option values
- Product publications across all sales channels
- Product tags and metadata associations
The
mutation also has the following effects on existing orders and transactions:- Draft orders: Existing draft orders that reference this product will retain the product information as stored data, but the product reference will be removed. Draft orders can still be completed with the stored product details.
- Completed orders and refunds: Previously completed orders that included this product aren't affected. The product information in completed orders is preserved for record-keeping, and existing refunds for this product remain valid and processable.
CautionProduct deletion is irreversible. After a product is deleted, it can't be recovered. Consider archiving or unpublishing products instead if you might need to restore them later.
If you need to delete a large product, such as one that has many variants that are active at several locations, you might encounter timeout errors. To avoid these timeout errors, you can set the
synchronousparameter tofalseto run the deletion asynchronously, which returns athat you can monitor for completion status.If you need more granular control over product cleanup, consider using these alternative mutations:
: Update the product status to archived or unpublished instead of deleting.: Delete specific variants while keeping the product.: Delete the choices available for a product, such as size, color, or material.
Learn more about the product model.
- •mutation
Duplicates a product.
If you need to duplicate a large product, such as one that has many variants that are active at several locations, you might encounter timeout errors.
To avoid these timeout errors, you can instead duplicate the product asynchronously.
In API version 2024-10 and higher, include
synchronous: falseargument in this mutation to perform the duplication asynchronously.In API version 2024-07 and lower, use the asynchronous
.Metafield values are not duplicated if the unique values capability is enabled.
- •mutation
Asynchronously reorders the media attached to a product.
- •mutation
Updates a product with attributes such as title, description, vendor, and media.
The
mutation helps you modify many products at once, avoiding the tedious or time-consuming process of updating them one by one in the Shopify admin. Common examples including updating product details like status or tags.The
mutation doesn't support updating product variants. To update multiple product variants for a single product and manage prices, use themutation.NoteThe
mutation has a throttle that takes effect when a store has 50,000 product variants. After this threshold is reached, no more than 1,000 new product variants can be updated per day.After updating a product, you can make additional changes using one of the following mutations:
: Used to perform multiple operations on products, such as creating or modifying product options and variants.: Used to publish the product and make it available to customers, if the product is currently unpublished.
Learn more about the product model and adding product data.
- •mutation
Publishes a resource to a channel. If the resource is a product, then it's visible in the channel only if the product status is
active. Products that are sold exclusively on subscription () can be published only on online stores.- •mutation
Publishes a resource to current channel. If the resource is a product, then it's visible in the channel only if the product status is
active. Products that are sold exclusively on subscription () can be published only on online stores.- •mutation
Unpublishes a resource from a channel. If the resource is a product, then it's visible in the channel only if the product status is
active.- •mutation
Unpublishes a resource from the current channel. If the resource is a product, then it's visible in the channel only if the product status is
active.- •mutation
Creates a refund for an order, allowing you to process returns and issue payments back to customers.
Use the
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
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
refundsfield. 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- •mutation
Creates a saved search.
- •mutation
Delete a saved search.
- •mutation
Updates a saved search.
- •mutation
- Theme app extensions
If your app integrates with a Shopify theme and you plan to submit it to the Shopify App Store, you must use theme app extensions instead of Script tags. Script tags can only be used with vintage themes. Learn more.
Script tag deprecationScript tags will be sunset for the Order status page on August 28, 2025. Upgrade to Checkout Extensibility before this date. Shopify Scripts will continue to work alongside Checkout Extensibility until August 28, 2025.
Creates a new script tag.
- •mutation
- Theme app extensions
If your app integrates with a Shopify theme and you plan to submit it to the Shopify App Store, you must use theme app extensions instead of Script tags. Script tags can only be used with vintage themes. Learn more.
Script tag deprecationScript tags will be sunset for the Order status page on August 28, 2025. Upgrade to Checkout Extensibility before this date. Shopify Scripts will continue to work alongside Checkout Extensibility until August 28, 2025.
Deletes a script tag.
- •mutation
- Theme app extensions
If your app integrates with a Shopify theme and you plan to submit it to the Shopify App Store, you must use theme app extensions instead of Script tags. Script tags can only be used with vintage themes. Learn more.
Script tag deprecationScript tags will be sunset for the Order status page on August 28, 2025. Upgrade to Checkout Extensibility before this date. Shopify Scripts will continue to work alongside Checkout Extensibility until August 28, 2025.
Updates a script tag.
- •mutation
Creates a segment.
- •mutation
Deletes a segment.
- •mutation
Updates a segment.
- •mutation
Deletes a shipping package.
- •mutation
Set a shipping package as the default. The default shipping package is the one used to calculate shipping costs on checkout.
- •mutation
Updates a shipping package.
- •mutation
Deletes a locale for a shop. This also deletes all translations of this locale.
- •mutation
Adds a locale for a shop. The newly added locale is in the unpublished state.
- •mutation
Updates a locale for a shop.
- •mutation
Creates staged upload targets for file uploads such as images, videos, and 3D models.
Use the
mutation instead of direct file creation mutations when:- Uploading large files: Files over a few MB benefit from staged uploads for better reliability
- Uploading media files: Videos, 3D models, and high-resolution images
- Bulk importing: CSV files, product catalogs, or other bulk data
- Using external file sources: When files are stored remotely and need to be transferred to Shopify
For small files or simple use cases, you can use
directly by providing the file content inline.The
mutation is the first step in Shopify's secure two-step upload process:Step 1: Create staged upload targets (this mutation)
- Generate secure, temporary upload URLs for your files.
- Receive authentication parameters for the upload.
Step 2: Upload files and create assets
- Upload your files directly to the provided URLs using the authentication parameters.
- Use the returned
as thein subsequent mutations like.
This approach provides better performance for large files, handles network interruptions gracefully, and ensures secure file transfers to Shopify's storage infrastructure.
After creating staged upload targets, complete the process by:
- Uploading files: Send your files to the returned
urlusing the providedparametersfor authentication - Creating file assets: Use the
as thein mutations such as:
Learn more about uploading media to Shopify.
- •mutation
Creates a storefront access token for use with the Storefront API.
An app can have a maximum of 100 active storefront access tokens for each shop.
- •mutation
Deletes a storefront access token.
- •mutation
Add tags to an order, a draft order, a customer, a product, or an online store article.
- •mutation
Remove tags from an order, a draft order, a customer, a product, or an online store article.
- •mutation
Asynchronously delete URL redirects in bulk.
- •mutation
Creates a new webhook subscription.
Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your
shopify.app.tomlmay be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.- •mutation
Deletes a webhook subscription.
Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your
shopify.app.tomlmay be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.- •mutation
Updates a webhook subscription.
Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your
shopify.app.tomlmay be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read About managing webhook subscriptions.
Deprecated mutations
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated
- •mutationDeprecated