Mutation

Updates the marketing activities delivery statuses for an abandonment.

Creates a one-time charge for app features or services that don't require recurring billing. This mutation is ideal for apps that sell individual features, premium content, or services on a per-use basis rather than subscription models.

For example, a design app might charge merchants once for premium templates, or a marketing app could bill for individual campaign setups without ongoing monthly fees.

Use the AppPurchaseOneTimeCreate mutation to:

• Charge for premium features or content purchases
• Bill for professional services or setup fees
• Generate revenue from one-time digital product sales

The mutation returns a confirmation URL that merchants must visit to approve the charge. Test and development stores are not charged, allowing safe testing of billing flows.

Explore one-time billing options on the app purchases page.

Revokes previously granted access scopes from an app installation, allowing merchants to reduce an app's permissions without completely uninstalling it. This provides granular control over what data and functionality apps can access.

For example, if a merchant no longer wants an app to access customer information but still wants to use its inventory features, they can revoke the customer-related scopes while keeping inventory permissions active.

Use the appRevokeAccessScopes mutation to:

• Remove specific permissions from installed apps
• Maintain app functionality while minimizing data exposure

The mutation returns details about which scopes were successfully revoked and any errors that prevented certain permissions from being removed.

Learn more about managing app permissions.

Cancels an active app subscription, stopping future billing cycles. The cancellation behavior depends on the replacementBehavior setting - it can either disable auto-renewal (allowing the subscription to continue until the end of the current billing period) or immediately cancel with prorated refunds.

When a merchant decides to discontinue using subscription features, this mutation provides a clean cancellation workflow that respects billing periods and merchant expectations.

Use the AppSubscriptionCancel mutation to:

• Process merchant-initiated subscription cancellations
• Terminate subscriptions due to policy violations or account issues
• Handle subscription cancellations during app uninstallation workflows

The cancellation timing and merchant access depends on the replacementBehavior setting and the app's specific implementation of subscription management.

For subscription lifecycle management and cancellation best practices, consult the subscription management guide.

Creates a recurring or usage-based AppSubscription that charges merchants for app features and services. The subscription includes one or more AppSubscriptionLineItem objects that define the pricing structure, billing intervals, and optional AppSubscriptionDiscount values.

Returns a confirmation URL where the merchant approves or declines the charges. After approval, the subscription becomes active and billing begins after any trial period expires. You can specify AppSubscriptionReplacementBehavior to control how this subscription interacts with existing active subscriptions.

Learn more about creating app subscriptions.

Updates the capped amount on usage-based billing for an AppSubscriptionLineItem. Enables you to modify the maximum charge limit that prevents merchants from exceeding a specified threshold during their billing period.

The mutation returns a confirmation URL where the merchant must approve the new pricing limit before it takes effect. Use this when adjusting usage limits based on merchant needs or changing pricing models.

Learn more about updating the maximum charge for a subscription.

Extends the trial period for an existing app subscription. Trial extensions give merchants additional time to use the app before committing to paid billing.

Requires the subscription ID and the number of days to extend (between one and 1000). The extension modifies the existing trial end date, allowing continued access to subscription features without immediate billing. Returns the updated AppSubscription.

Learn more about offering free trials.

Uninstalls an App from a shop. Apps use this mutation to uninstall themselves programmatically, removing their AppInstallation from the merchant's store.

When an app uninstalls, Shopify automatically performs cleanup tasks, such as deleting WebhookSubscription objects and admin links associated with the app.

Learn more about app lifecycle management.

---

Caution: This action is irreversible. You can't restore an uninstalled app's configuration or data. Before you uninstall an app, make sure that you no longer need to make API calls for the store in which the app has been installed.

---

Creates a usage charge for an app subscription with usage-based pricing. The charge counts toward the capped amount limit set when creating the subscription.

Usage records track consumption of app features or services on a per-use basis. You provide the charge amount, a description of what you consumed, and the subscription line item ID. The optional idempotencyKey parameter prevents duplicate charges if you send the same request multiple times.

If the new charge would cause total usage charges in the current billing interval to exceed the capped amount, then the mutation returns an error.

Learn more about creating usage-based subscriptions.

Creates an Article. Articles are content pieces that include a title, body text, and author information.

You can publish the article immediately or schedule it with a specific publish date. You can customize the article's URL handle, apply custom templates for rendering, and add optional fields like tags, an image, and Metafield objects.

The mutation validates article content and ensures proper blog association. Error handling provides specific feedback for content requirements.

Permanently deletes a blog article from a shop's blog. This mutation removes the article and all associated metadata.

For example, when outdated product information or seasonal content needs removal, merchants can use this mutation to clean up their blog.

Use the articleDelete mutation to:

• Remove outdated or incorrect blog content
• Clean up seasonal or time-sensitive articles
• Maintain blog organization

The deletion is permanent and returns the deleted article's ID for confirmation.

Updates an existing Article. You can modify the article's content, metadata, publication status, and associated properties like author information and tags.

If you update the handle, then you can optionally create a redirect from the old URL to the new one by setting redirectNewHandle to true.

Update the backup region that is used when we have no better signal of what region a buyer is in.

Creates a new blog within a shop, establishing a container for organizing articles.

For example, a fitness equipment retailer launching a wellness blog would use this mutation to create the blog, enabling them to publish workout guides and nutrition tips.

Use the blogCreate mutation to:

• Launch new content marketing initiatives
• Create separate blogs for different content themes
• Establish spaces for article organization

The mutation validates blog settings and establishes the structure for article publishing.

Permanently deletes a blog from a shop. This mutation removes the blog container and its organizational structure.

For example, when consolidating multiple seasonal blogs into a single year-round content strategy, merchants can use this mutation to remove unused blogs.

Use the blogDelete mutation to:

• Remove unused or outdated blogs
• Consolidate content organization
• Clean up blog structure

The deletion is permanent and returns the deleted blog's ID for confirmation.

Updates an existing blog's configuration and settings. This mutation allows merchants to modify blog properties to keep their content strategy current.

For example, a merchant might update their blog's title from "Company News" to "Sustainability Stories" when shifting their content focus, or modify the handle to improve URL structure.

Use the blogUpdate mutation to:

• Change blog titles for rebranding
• Modify blog handles for better URLs
• Adjust comment settings and moderation preferences

The mutation returns the updated blog with any validation errors.

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.

Creates and runs a bulk operation to import data asynchronously. This mutation executes a specified GraphQL mutation multiple times using input data from a JSONL file that you've uploaded to Shopify.

The operation processes each line in your JSONL file as a separate mutation execution. The operation delivers results in a JSONL file when it completes. You can run one bulk mutation operation at a time per shop, though a bulkOperationRunQuery operation can run simultaneously.

Learn more about bulk importing data.

Creates and runs a bulk operation to fetch data asynchronously. The operation processes your GraphQL query in the background and returns results in a JSONL file when complete.

Apps can run one bulk query operation and one bulk mutation operation at a time per shop. The query must include at least one connection field and supports up to five connections with a maximum nesting depth of two levels.

---

Note: Results remain available for seven days after completion.

---

For more information, see the bulk operations guide.

Creates product feedback for multiple products.

Creates a carrier service that provides real-time shipping rates to Shopify. Carrier services provide real-time shipping rates from external providers like FedEx, UPS, or custom shipping solutions. The carrier service connects to your external shipping rate calculation system through a callback URL.

When customers reach checkout, Shopify sends order details to your callback URL and displays the returned shipping rates. The service must be active to provide rates during checkout.

Removes an existing carrier service.

Updates a carrier service. Only the app that creates a carrier service can update it.

Creates a cart transform function that lets merchants customize how products are bundled and presented during checkout. This gives merchants powerful control over their merchandising strategy by allowing apps to modify cart line items programmatically, supporting advanced approaches like dynamic bundles or personalized product recommendations.

For example, a bundle app might create a cart transform that automatically groups related products (like a camera, lens, and case) into a single bundle line item when customers add them to their cart, complete with bundle pricing and unified presentation.

Use CartTransformCreate to:

• Deploy custom bundling logic to merchant stores
• Enable dynamic product grouping during checkout
• Implement personalized product recommendations
• Create conditional offers based on cart contents
• Support complex pricing strategies for product combinations

The mutation processes synchronously and returns the created cart transform along with any validation errors. Once created, the cart transform function becomes active for the shop and will process cart modifications according to your defined logic. Cart transforms integrate with Shopify Functions to provide powerful customization capabilities while maintaining checkout performance.

Cart Transform functions can be configured to block checkout on failure or allow graceful degradation, giving you control over how errors are handled in the customer experience.

Learn more about customized bundles.

Removes an existing cart transform function from the merchant's store, disabling any customized bundle or cart modification logic it provided. This mutation persistently deletes the transform configuration and stops all associated cart processing.

For example, when discontinuing a bundle app or removing specific merchandising features, you would delete the corresponding cart transform to ensure customers no longer see the bundled products or modified cart behavior.

Use CartTransformDelete to:

• Deactivate customized bundle logic when removing app features
• Clean up unused transform functions
• Disable cart modifications during app uninstallation
• Remove outdated merchandising strategies
• Restore default cart behavior for merchants

The deletion processes immediately and returns the ID of the removed cart transform for confirmation. Once deleted, the transform function stops processing new cart operations, though existing cart sessions may retain their current state until refresh. This ensures a clean transition without disrupting active customer sessions.

Consider the timing of deletions carefully, as removing transforms during peak shopping periods could affect customer experience if they have active carts with transformed items.

Learn more about managing cart transforms.

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.

Publications and Price Lists

• Publication objects control which products are visible in a catalog. Publications are optional. When a publication isn't associated with a catalog, product availability is determined by the sales channel.
• PriceList objects define custom pricing for products in a catalog.

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

When to use Publications

Create a publication only if you need to:

• Limit which products are visible in a specific context (e.g., show different products to different company locations or markets)
• Publish a curated subset of your product catalog

Do NOT create a publication if:

• You want product availability determined by the sales channel
• You only need to customize pricing (use a price list without a publication)

Important: For company location catalogs that only require custom pricing, create the catalog with a price list but without a publication.

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

Delete a catalog.

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.

Updates the visual branding for a CheckoutProfile, customizing how checkout displays to customers. Creates new branding settings if none exist, or modifies existing settings.

The mutation accepts two levels of customization through the CheckoutBrandingInput input object. designSystem defines foundational brand attributes like colors, typography, and corner radius that apply consistently throughout checkout. customizations defines styles for specific parts of the UI, individual components, or groups of components like the header, buttons, form fields, and sections.

Changes to a published checkout profile display immediately in the store's checkout. You can preview draft profiles in the Shopify admin's checkout editor before publishing.

Learn more about checkout styling.

Adds multiple products to an existing collection in a single operation. This mutation provides an efficient way to bulk-manage collection membership without individual product updates.

For example, when merchants create seasonal collections, they can add dozens of related products at once rather than updating each product individually. A clothing store might add all winter jackets to a "Winter Collection" in one operation.

Use CollectionAddProducts to:

• Bulk-add products to collections for efficient catalog management
• Implement collection building tools in admin interfaces
• Organize collection membership during bulk product operations
• Reduce API calls when managing large product sets

The mutation processes multiple product additions and returns success status along with any errors encountered during the operation. Products are added to the collection while preserving existing collection settings.

This operation only works with manual collections where merchants explicitly choose which products to include. It will return an error if used with smart collections that automatically include products based on conditions.

Learn more about collection management.

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 <a href="https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionAddProducts#arguments-productIds"><code><span class="PreventFireFoxApplyingGapToWBR">product<wbr/>Ids</span></code></a> argument.

---

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 collectionCreate 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)

---

Note: The created collection is unpublished by default. To make it available to customers, use the <a href="https://shopify.dev/docs/api/admin-graphql/latest/mutations/publishablePublish"><code><span class="PreventFireFoxApplyingGapToWBR">publishable<wbr/>Publish</span></code></a> mutation after creation.

---

Learn more about using metafields with smart collections.

Deletes a collection and removes it permanently from the store. This operation cannot be undone and will remove the collection from all sales channels where it was published.

For example, when merchants discontinue seasonal promotions or reorganize their catalog structure, they can delete outdated collections like "Back to School 2023" to keep their store organized.

Use CollectionDelete to:

• Remove outdated or unused collections from stores
• Clean up collection structures during catalog reorganization
• Implement collection management tools with deletion capabilities

Products within the deleted collection remain in the store but are no longer grouped under that collection.

Learn more about collection management.

Duplicates a collection.

An existing collection ID and new title are required.

Publication Duplication

Publications may be excluded by passing copyPublications: false in the input.

Metafields

Metafield values are not duplicated if the unique values capability is enabled.

Removes multiple products from a collection in a single operation. This mutation can process large product sets (up to 250 products) and may take significant time to complete for collections with many products.

For example, when ending a seasonal promotion, merchants can remove all sale items from a "Summer Clearance" collection at once rather than editing each product individually.

Use CollectionRemoveProducts to:

• Bulk-remove products from collections efficiently
• Clean up collection membership during catalog updates
• Implement automated collection management workflows

The operation processes asynchronously to avoid timeouts and performance issues, especially for large product sets.

Learn more about collection management.

Asynchronously reorders products within a specified collection. Instead of returning an updated collection, this mutation returns a job, which should be polled. The Collection.sortOrder must be MANUAL.

How to use this mutation:

• Provide only the products that actually moved in the moves list; do not send the entire product list. For example: to move the product at index 1 to index N, send a single move for that product with newPosition: N.
• Each move is applied sequentially in the order provided.
• newPosition is a zero-based index within the collection at the moment the move is applied (after any prior moves in the list).
• Products not included in moves keep their relative order, aside from any displacement caused by the moves.
• If newPosition is greater than or equal to the number of products, the product is placed at the end.

Example:

• Initial order: [A, B, C, D, E] (indices 0..4)
• Moves (applied in order):
• E -> newPosition: 1
• C -> newPosition: 4
• Result: [A, E, B, D, C]

Displaced products will have their position altered in a consistent manner with no gaps.

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 collectionUpdate 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 job object that you can use to track the progress of the update.

To publish or unpublish collections to specific sales channels, use the dedicated publishablePublish and publishableUnpublish mutations.

Learn more about using metafields with smart collections.

Add, remove and update CombinedListings of a given Product.

CombinedListings are comprised of multiple products to create a single listing. There are two kinds of products used in a CombinedListing:

1. Parent products
2. Child products

The parent product is created with a productCreate with a CombinedListingRole of PARENT. Once created, you can associate child products with the parent product using this mutation. Parent products represent the idea of a product (e.g. Shoe).

Child products represent a particular option value (or combination of option values) of a parent product. For instance, with your Shoe parent product, you may have several child products representing specific colors of the shoe (e.g. Shoe - Blue). You could also have child products representing more than a single option (e.g. Shoe - Blue/Canvas, Shoe - Blue/Leather, etc...).

The combined listing is the association of parent product to one or more child products.

Learn more about Combined Listings.

Approves a pending comment, making it visible to store visitors on the associated blog article.

For example, when a customer submits a question about a product in a blog post, merchants can approve the comment to make it publicly visible.

Use the commentApprove mutation to:

• Publish pending comments after review
• Enable customer discussions on blog articles
• Maintain quality control over comments

Once approved, the comment becomes visible to all store visitors.

Permanently removes a comment from a blog article.

For example, when a comment contains spam links or inappropriate language that violates store policies, merchants can delete it entirely.

Use the commentDelete mutation to:

• Remove spam or inappropriate comments permanently
• Clean up irrelevant discussions
• Maintain content standards on blog articles

Deletion is permanent and can't be undone.

Reverses a spam classification on a comment, restoring it to normal moderation status. This mutation allows merchants to change their decision when a comment has been manually marked as spam.

For example, when a merchant reviews comments marked as spam and finds a legitimate customer question, they can use this mutation to restore the comment's normal status and make it eligible for approval.

Use the commentNotSpam mutation to:

• Unmark comments that were marked as spam
• Restore comments to normal moderation status
• Move comments back to the approval queue

This action changes the comment's status from spam back to pending, where it can then be approved or managed according to standard moderation practices.

Marks a comment as spam, removing it from public view. This mutation enables merchants to quickly handle unwanted promotional content, malicious links, or other spam that appears in blog discussions.

For example, when a comment contains suspicious links to unrelated products or services, merchants can mark it as spam to immediately hide it from customers.

Use the commentSpam mutation to:

• Hide promotional or malicious comments from public view
• Protect customers from potentially harmful links
• Maintain professional discussion quality on blog articles

Spam-marked comments can be reviewed later and potentially restored using the commentNotSpam mutation if they were incorrectly classified.

Deletes a list of companies.

Deletes a company address.

Adds an existing Customer as a contact to a Company. Companies are business entities that make purchases from the merchant's store. Use this mutation when you have a customer who needs to be associated with a B2B company to make purchases on behalf of that company.

The mutation returns the newly created CompanyContact that links the customer to the company. After assignment, the customer becomes a company contact who can place orders on behalf of the company with access to any catalogs, pricing, and payment terms configured for the company's locations.

Assigns the main contact for the company.

Assigns a role to a contact for a location.

Assigns roles on a company contact.

Creates a company contact and the associated customer.

Deletes a company contact.

Removes a company contact from a Company.

Revokes a role on a company contact.

Revokes roles on a company contact.

Deletes one or more company contacts.

Updates a company contact.

Creates a Company for B2B commerce. This mutation creates the company and can optionally create an initial CompanyContact and CompanyLocation in a single operation. Company contacts are people who place orders on behalf of the company. Company locations are branches or offices with their own billing and shipping addresses.

---

Note: Creating a company without a <code>name</code> <a href="https://shopify.dev/docs/api/admin-graphql/latest/mutations/companycreate?example=creating-a-company-without-a-name-returns-an-error">returns an error</a>.

---

Learn more about creating companies for B2B.

Deletes a company.

Updates an address on a company location.

Assigns roles on a company location.

Creates one or more mappings between a staff member at a shop and a company location.

Creates a new location for a Company. Company locations are branches or offices where B2B customers can place orders with specific pricing, catalogs, and payment terms.

Creates a company location. Each location can have its own billing and shipping addresses, tax settings, and buyer experience configuration. You can assign staff members and CompanyContact objects to manage the location.

Deletes a company location.

Deletes one or more existing mappings between a staff member at a shop and a company location.

Revokes roles on a company location.

Deletes a list of company locations.

Sets the tax settings for a company location.

Updates a company location's information and B2B checkout settings. Company locations are branches or offices where CompanyContact members place orders on behalf of the company. Contacts must be assigned to a location through roleAssignments to place orders.

The mutation modifies details such as the location's name, contact information, preferred locale, and internal notes. You can also configure the B2B checkout experience through BuyerExperienceConfiguration settings that control whether orders require merchant review, PaymentTermsTemplate settings, shipping address editing permissions, and DepositConfiguration requirements.

Learn more about managing company locations.

Revokes the main contact from the company.

Updates a Company with new information. Companies represent business customers that can have multiple contacts and locations with specific pricing, payment terms, and checkout settings.

The mutation accepts the company's ID and an input object containing the fields to update. You can modify the company name, add or update internal notes, set an external ID for integration with other systems, or adjust the customer relationship start date.

Learn more about building B2B features.

Update or create consent policies in bulk.

Creates a new MailingAddress for a Customer. You can optionally set the address as the customer's default address.

You can only add addresses to existing customers. Each customer can have multiple addresses.

Deletes a customer's address.

Updates a Customer's MailingAddress. You can modify any field of the address and optionally set it as the customer's default address.

Add tax exemptions for the customer.

Cancels a pending erasure of a customer's data. Read more here.

To request an erasure of a customer's data use the customerRequestDataErasure mutation.

Creates a new Customer in the store.

Accepts customer details including contact information, marketing consent preferences, and tax exemptions through the CustomerInput input object. You can also associate metafields and tags to organize and extend customer data.

Apps using protected customer data must meet Shopify's protected customer data requirements.

Deletes a Customer from the store. You can only delete customers who haven't placed any orders.

Apps using protected customer data must meet Shopify's protected customer data requirements.

Updates a Customer's email marketing consent information. The customer must have an email address to update their consent. Records the marketing state (such as subscribed, pending, unsubscribed), opt-in level, and when and where the customer gave or withdrew consent.

Generates a one-time activation URL for a Customer whose legacy customer account isn't yet enabled. Use this after importing customers or creating accounts that need activation.

The generated URL expires after 30 days and becomes invalid if you generate a new one.

---

Note: The generated URL only works when legacy customer accounts are enabled on the shop. It only works for customers with disabled or invited <a href="https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer#field-Customer.fields.state"><code>account states</code></a>. Attempting to generate a URL for an already-enabled customer returns an error.

---

Merges two customers.

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.

Updates the credit card payment method for a customer.

Returns a URL that allows the customer to update a specific payment method.

Currently, customerPaymentMethodGetUpdateUrl only supports Shop Pay.

Creates a PayPal billing agreement for a customer.

Updates a PayPal billing agreement for a customer.

Creates a customer payment method using identifiers from remote payment gateways like Stripe, Authorize.Net, or Braintree. Imports existing payment methods from external gateways and associates them with Customer objects in Shopify.

The operation processes payment methods asynchronously. The returned CustomerPaymentMethod initially has incomplete details while Shopify validates and processes the remote gateway information. Use the customerPaymentMethod query to retrieve the payment method status until all details are available or the payment method is revoked.

Learn more about migrating customer payment methods from remote gateways.

Revokes a customer's payment method.

Sends a link to the customer so they can update a specific payment method.

Remove tax exemptions from a customer.

Replace tax exemptions for a customer.