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 access scopes previously granted for an app installation.

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.

Allows an app to charge a store for features or services on a recurring basis.

Updates the capped amount on the usage pricing plan of an app subscription line item.

Extends the trial period for an existing app subscription, giving merchants additional time to evaluate premium features before committing to paid billing. This mutation provides flexibility in trial management and can improve conversion rates by accommodating merchant needs.

Trial extensions are particularly valuable when merchants need more time to fully evaluate complex features, experience technical setup delays, or require additional approval processes within their organization before committing to paid subscriptions.

Use the AppSubscriptionTrialExtend mutation to:

• Accommodate merchant requests for additional evaluation time
• Compensate for service interruptions during trial periods
• Support complex enterprise evaluation and approval workflows
• Implement customer success strategies that improve trial-to-paid conversion
• Handle technical onboarding delays that impact trial effectiveness

The extension modifies the existing trial end date, allowing continued access to subscription features without immediate billing. This approach maintains subscription continuity while providing merchants the flexibility they need for thorough feature evaluation.

Trial extension strategies and conversion techniques are covered in the offer free trials guide.

Enables an app to charge a store for features or services on a per-use basis. The usage charge value is counted towards the cappedAmount limit that was specified in the appUsagePricingDetails field 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 a Total price exceeds balance remaining error is returned.

Creates an article.

Deletes an article.

Updates an article.

Creates a blog.

Deletes a blog.

Updates a blog.

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 mutation.

To learn how to bulk import large volumes of data asynchronously, refer to the bulk import data guide.

Creates and runs a bulk operation query.

See the bulk operations guide for more details.

Creates product feedback for multiple products.

Creates a new carrier service.

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.

Updates the context of a catalog.

Creates a new catalog.

Delete a catalog.

Updates an existing catalog.

Updates the checkout branding settings for a checkout profile.

If the settings don't exist, then new settings are created. The checkout branding settings applied to a published checkout profile will be immediately visible within the store's checkout. The checkout branding settings applied to a draft checkout profile could be previewed within the admin checkout editor.

To learn more about updating checkout branding settings, refer to the checkout branding tutorial.

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.

Asynchronously adds a set of products to a given collection. It can take a long time to run. Instead of returning a collection, it returns a job which should be polled.

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)

---

---

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.

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 comment.

Deletes a comment.

Marks a comment as not spam.

Marks a comment as spam.

Deletes a list of companies.

Deletes a company address.

Assigns the customer as a company contact.

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.

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 company 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.

Updates a company location.

Revokes the main contact from the company.

Updates a company.

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.

Create a new customer. As of API version 2022-10, apps using protected customer data must meet the protected customer data requirements.

Delete a customer. As of API version 2022-10, apps using protected customer data must meet the protected customer data requirements.

Update a customer's email marketing information information.

Generate an account activation URL for a customer.

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.

Create a payment method from remote gateway identifiers. NOTE: This operation processes payment methods asynchronously. The returned payment method will initially have incomplete details. Developers must poll this payment method using customerPaymentMethod query until all payment method details are available, or the payment method is revoked (usually within seconds).

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.

Enqueues a request to erase customer's data. Read more here.

To cancel the data erasure request use the customerCancelDataErasure mutation.

Creates a customer segment members query.

Sends the customer an account invite email.

Update a customer's SMS marketing consent information.

Update a customer's attributes. As of API version 2022-10, apps using protected customer data must meet the protected customer data requirements.

Updates a customer's default address.

Opt out a customer from data sale.

Creates a delegate access token.

To learn more about creating delegate access tokens, refer to Delegate OAuth access tokens to subsystems.

Destroys a delegate access token.

Activates and deactivates delivery customizations.

Creates a delivery customization.

Creates a delivery customization.

Updates a delivery customization.

Create a delivery profile.

Enqueue the removal of a delivery profile.

Update a delivery profile.

Creates or updates a delivery promise provider. Currently restricted to select approved delivery promise partners.

Set the delivery settings for a shop.

Assigns a location as the shipping origin while using legacy compatibility mode for multi-location delivery profiles.

Activates an automatic discount.

Creates an automatic discount that's managed by an app. Use this mutation with Shopify Functions when you need advanced, custom, or dynamic discount capabilities that aren't supported by Shopify's native discount types.

For example, use this mutation to create an automatic discount using an app's "Volume" discount type that applies a percentage off when customers purchase more than the minimum quantity of a product. For an example implementation, refer to our tutorial.

---

---

Updates an existing automatic discount that's managed by an app using Shopify Functions. Use this mutation when you need advanced, custom, or dynamic discount capabilities that aren't supported by Shopify's native discount types.

For example, use this mutation to update a new "Volume" discount type that applies a percentage off when customers purchase more than the minimum quantity of a product. For an example implementation, refer to our tutorial.

---

---

Creates an amount off discount that's automatically applied on a cart and at checkout.

---

---

Updates an existing amount off discount that's automatically applied on a cart and at checkout.

---

---

Deletes multiple automatic discounts in a single operation, providing efficient bulk management for stores with extensive discount catalogs. This mutation processes deletions asynchronously to handle large volumes without blocking other operations.

For example, when cleaning up expired seasonal promotions or removing outdated automatic discounts across product categories, merchants can delete dozens of discounts simultaneously rather than processing each individually.

Use DiscountAutomaticBulkDelete to:

• Remove multiple automatic discounts efficiently
• Clean up expired or obsolete promotions
• Streamline discount management workflows
• Process large-scale discount removals asynchronously

The operation returns a job object for tracking deletion progress and any validation errors encountered during processing.

Learn more about discount management.

Creates a buy X get Y discount (BXGY) that's automatically applied on a cart and at checkout.

---

---

Updates an existing buy X get Y discount (BXGY) that's automatically applied on a cart and at checkout.

---

---

Deactivates an automatic discount.

Deletes an existing automatic discount from the store, permanently removing it from all future order calculations. This mutation provides a clean way to remove promotional campaigns that are no longer needed.

For example, when a seasonal promotion ends or a flash sale concludes, merchants can use this mutation to ensure the discount no longer applies to new orders while preserving historical order data.

Use DiscountAutomaticDelete to:

• Remove expired promotional campaigns
• Clean up test discounts during development
• Delete automatic discounts that conflict with new promotions
• Maintain a clean discount configuration

The mutation returns the ID of the deleted discount for confirmation and any validation errors if the deletion cannot be completed. Once deleted, the automatic discount will no longer appear in discount lists or apply to new customer orders.

Creates automatic free shipping discounts that apply to qualifying orders without requiring discount codes. These promotions automatically activate when customers meet specified criteria, streamlining the checkout experience.

For example, a store might create an automatic free shipping discount for orders over variable pricing to encourage larger purchases, or offer free shipping to specific customer segments during promotional periods.

Use DiscountAutomaticFreeShippingCreate to:

• Set up code-free shipping promotions
• Create order value-based shipping incentives
• Target specific customer groups with shipping benefits
• Establish location-based shipping discounts

The mutation validates discount configuration and returns the created automatic discount node along with any configuration errors that need resolution.

Learn more about automatic discounts.

Updates existing automatic free shipping discounts, allowing merchants to modify promotion criteria, shipping destinations, and eligibility requirements without recreating the entire discount structure.

For example, extending a holiday free shipping promotion to include additional countries, adjusting the minimum order value threshold, or expanding customer eligibility to include new segments.

Use DiscountAutomaticFreeShippingUpdate to:

• Modify shipping discount thresholds and criteria
• Expand or restrict geographic availability
• Update customer targeting and eligibility rules
• Adjust promotion timing and activation periods

Changes take effect immediately for new orders, while the mutation validates all modifications and reports any configuration conflicts through user errors.

Learn more about managing automatic discounts.

Activates a previously created code discount, making it available for customers to use during checkout. This mutation transitions inactive discount codes into an active state where they can be applied to orders.

For example, after creating a "SUMMER20" discount code but leaving it inactive during setup, merchants can activate it when ready to launch their summer promotion campaign.

Use DiscountCodeActivate to:

• Launch scheduled promotional campaigns
• Reactivate previously paused discount codes
• Enable discount codes after configuration changes
• Control the timing of discount availability

The mutation returns the updated discount code node with its new active status and handles any validation errors that might prevent activation, such as conflicting discount rules or invalid date ranges.

Creates a code discount. The discount type must be provided by an app extension that uses Shopify Functions. Functions can implement order, product, or shipping discount functions. Use this mutation with Shopify Functions when you need custom logic beyond Shopify's native discount types.

For example, use this mutation to create a code discount using an app's "Volume" discount type that applies a percentage off when customers purchase more than the minimum quantity of a product. For an example implementation, refer to our tutorial.

---

---

Updates a code discount, where the discount type is provided by an app extension that uses Shopify Functions. Use this mutation when you need advanced, custom, or dynamic discount capabilities that aren't supported by Shopify's native discount types.

---

---

Creates an amount off discount that's applied on a cart and at checkout when a customer enters a code. Amount off discounts can be a percentage off or a fixed amount off.

---

---

Updates an amount off discount that's applied on a cart and at checkout when a customer enters a code. Amount off discounts can be a percentage off or a fixed amount off.

---

---

Activates multiple code discounts asynchronously using one of the following:

• A search query
• A saved search ID
• A list of discount code IDs

For example, you can activate discounts for all codes that match a search criteria, or activate a predefined set of discount codes.

Deactivates multiple code-based discounts asynchronously using one of the following:

• A search query
• A saved search ID
• A list of discount code IDs

For example, you can deactivate discounts for all codes that match a search criteria, or deactivate a predefined set of discount codes.

Deletes multiple code-based discounts asynchronously using one of the following:

• A search query
• A saved search ID
• A list of discount code IDs

For example, you can delete discounts for all codes that match a search criteria, or delete a predefined set of discount codes.

Creates a buy X get Y discount (BXGY) that's applied on a cart and at checkout when a customer enters a code.

---

---

Updates a buy X get Y discount (BXGY) that's applied on a cart and at checkout when a customer enters a code.

---

---

Temporarily suspends a code discount without permanently removing it from the store. Deactivation allows merchants to pause promotional campaigns while preserving the discount configuration for potential future use.

For example, when a flash sale needs to end immediately or a discount code requires temporary suspension due to inventory issues, merchants can deactivate it to stop new redemptions while keeping the discount structure intact.

Use DiscountCodeDeactivate to:

• Pause active promotional campaigns timely
• Temporarily suspend problematic discount codes
• Control discount availability during inventory shortages
• Maintain discount history while stopping usage

Deactivated discounts remain in the system and can be reactivated later, unlike deletion which persistently removes the code. Customers attempting to use deactivated codes will receive appropriate error messages.

Removes a code discount from the store, making it permanently unavailable for customer use. This mutation provides a clean way to eliminate discount codes that are no longer needed or have been replaced.

For example, when a seasonal promotion ends or a discount code has been compromised, merchants can delete it entirely rather than just deactivating it, ensuring customers cannot attempt to use expired promotional codes.

Use DiscountCodeDelete to:

• persistently remove outdated promotional codes
• Clean up discount code lists after campaigns end
• Eliminate compromised or leaked discount codes
• Maintain organized discount management

Once deleted, the discount code cannot be recovered and any customer attempts to use it will fail. This differs from deactivation, which preserves the code for potential future reactivation.

Creates an free shipping discount that's applied on a cart and at checkout when a customer enters a code.

---

---

Updates a free shipping discount that's applied on a cart and at checkout when a customer enters a code.

---

---

Asynchronously delete discount codes in bulk that customers can use to redeem a discount.

Asynchronously add discount codes in bulk that customers can use to redeem a discount. You can use the discountRedeemCodeBulkAdd mutation to automate the distribution of discount codes through emails or other marketing channels.

Updates a dispute evidence.

Adds tags to multiple draft orders.

Deletes multiple draft orders.

Removes tags from multiple draft orders.

Calculates the properties of a draft order. Useful for determining information such as total taxes or price without actually creating a draft order.

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 draftOrderComplete mutation when a merchant is ready to finalize a draft order and create a real order in their store. The draftOrderComplete mutation also supports sales channel attribution for tracking order sources using the sourceName argument, 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.

---

---

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 draftOrderInvoiceSend mutation.
• Complete the draft order using the draftOrderComplete mutation.
• Update the draft order using the draftOrderUpdate mutation.
• Duplicate a draft order using the draftOrderDuplicate mutation.
• Delete the draft order using the draftOrderDelete mutation.

---

---

Creates a draft order from order.

Deletes a draft order.

Duplicates a draft order.

Previews a draft order invoice email.

Sends an email invoice for a draft order.

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.

Updates the server pixel to connect to an EventBridge endpoint. Running this mutation deletes any previous subscriptions for the server pixel.

Acknowledges file update failure by resetting FAILED status to READY and clearing any media errors.

Creates file assets for a store from external URLs or files that were previously uploaded using the stagedUploadsCreate mutation.

Use the fileCreate mutation to add various types of media and documents to your store. These files are added to the Files page in the Shopify admin and can be referenced by other resources in your store.

The fileCreate mutation supports multiple file types:

• Images: Product photos, variant images, and general store imagery
• Videos: Shopify-hosted videos for product demonstrations and marketing
• External videos: YouTube and Vimeo videos for enhanced product experiences
• 3D models: Interactive 3D representations of products
• Generic files: PDFs, documents, and other file types for store resources

The mutation handles duplicate filenames using configurable resolution modes that automatically append UUIDs, replace existing files, or raise errors when conflicts occur.

---

---

After creating files, you can make subsequent updates using the following mutations:

• fileUpdate: Update file properties such as alt text or replace file contents while preserving the same URL.
• fileDelete: Remove files from your store when they are no longer needed.

To list all files in your store, use the files query.

Learn how to manage product media and file assets in your app.

Deletes file assets that were previously uploaded to your store.

Use the fileDelete mutation to permanently remove media and file assets from your store when they are no longer needed. This mutation handles the complete removal of files from both your store's file library and any associated references to products or other resources.

The fileDelete mutation supports removal of multiple file types:

• Images: Product photos, variant images, and general store imagery
• Videos: Shopify-hosted videos for product demonstrations and marketing content
• External Videos: YouTube and Vimeo videos linked to your products
• 3D models: Interactive 3D representations of products
• Generic files: PDFs, documents, and other file types stored in your Files page

When you delete files that are referenced by products, the mutation automatically removes those references and reorders any remaining media to maintain proper positioning. Product file references are database relationships managed through a media reference system, not just links in product descriptions. The Shopify admin provides a UI to manage these relationships, and when files are deleted, the system automatically cleans up all references. Files that are currently being processed by other operations are rejected to prevent conflicts.

---

---

Learn how to manage product media and file assets in your app.

Updates properties, content, and metadata associated with an existing file asset that has already been uploaded to Shopify.

Use the fileUpdate mutation to modify various aspects of files already stored in your store. Files can be updated individually or in batches.

The fileUpdate mutation supports updating multiple file properties:

• Alt text: Update accessibility descriptions for images and other media.
• File content: Replace image or generic file content while maintaining the same URL.
• Filename: Modify file names (extension must match the original).
• Product references: Add or remove associations between files and products. Removing file-product associations deletes the file from the product's media gallery and clears the image from any product variants that were using it.

The mutation handles different file types with specific capabilities:

• Images: Update preview images, original source, filename, and alt text.
• Generic files: Update original source, filename, and alt text.
• Videos and 3D models: Update alt text and product references.

---

---

After updating files, you can use related mutations for additional file management:

• fileCreate: Create new file assets from external URLs or staged uploads.
• fileDelete: Remove files from your store when they are no longer needed.

Learn how to manage product media and file assets in your app.

Triggers any workflows that begin with the trigger specified in the request body. To learn more, refer to Create Shopify Flow triggers.

Cancels a fulfillment.

Creates a fulfillment constraint rule and its metafield.

Deletes a fulfillment constraint rule and its metafields.

Update a fulfillment constraint rule.

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.

Creates a fulfillment event for a specified fulfillment.

Accept a cancellation request sent to a fulfillment service for a fulfillment order.

Accepts a fulfillment request sent to a fulfillment service for a fulfillment order.

Marks a fulfillment order as canceled.

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 IN_PROGRESS.

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.

Applies a fulfillment hold on a fulfillment order.

As of the 2025-01 API version, the mutation can be successfully executed on fulfillment orders that are already on hold. To place multiple holds on a fulfillment order, apps need to supply the handle field. Each app can place up to 10 active holds per fulfillment order. If an app attempts to place more than this, the mutation will return a user error indicating that the limit has been reached. The app would need to release one of its existing holds before being able to apply a new one.

Mark line items associated with a fulfillment order as being ready for pickup by a customer.

Sends a Ready For Pickup notification to the customer to let them know that their order is ready to be picked up.

Merges a set or multiple sets of fulfillment orders together into one based on line item inputs and quantities.

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 SUBMITTED, ACCEPTED, CANCELLATION_REQUESTED, or CANCELLATION_REJECTED. These request statuses mean that a fulfillment order is awaiting action by a fulfillment service and can't be re-assigned without first having the fulfillment service accept a cancellation request. This behavior is intended to prevent items from being fulfilled by multiple locations or fulfillment services.

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 fulfillmentOrderLineItems parameter (available as of the 2023-04 API version), or specify that the original fulfillment order contains line items which have already been fulfilled.

If the new location is already assigned to another active fulfillment order, on the same order, then a new fulfillment order is created. The existing fulfillment order is closed and line items are recreated in a new fulfillment order.

Marks a scheduled fulfillment order as open.

Rejects a cancellation request sent to a fulfillment service for a fulfillment order.

Rejects a fulfillment request sent to a fulfillment service for a fulfillment order.

Releases the fulfillment hold on a fulfillment order.

Reschedules a scheduled fulfillment order.

Updates the value of the fulfillAt field on a scheduled fulfillment order.

The fulfillment order will be marked as ready for fulfillment at this date and time.

Splits a fulfillment order or orders based on line item inputs and quantities.

Sets the latest date and time by which the fulfillment orders need to be fulfilled.

Sends a cancellation request to the fulfillment service of a fulfillment order.

Sends a fulfillment request to the fulfillment service of a fulfillment order.

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-10 or 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.

Deletes a fulfillment service.

Updates a fulfillment service.

If you are using API version 2023-10 or 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.

Updates tracking information for a fulfillment.

Create a gift card.

Credit a gift card.

Deactivate a gift card. A deactivated gift card cannot be used by a customer. A deactivated gift card cannot be re-enabled.

Debit a gift card.

Send notification to the customer of a gift card.

Send notification to the recipient of a gift card.

Update a gift card.

Activate an inventory item at a location.

Apply changes to inventory quantities.

Modify the activation status of an inventory item at locations. Activating an inventory item at a particular location allows that location to stock that inventory item. Deactivating an inventory item at a location removes the inventory item's quantities and turns off the inventory item from that location.

Removes an inventory item's quantities from a location, and turns off inventory at the location.

Updates an inventory item.

Moves inventory between inventory quantity names at a single location.

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.

---

---

Set up scheduled changes of inventory items.

Activates a location so that you can stock inventory at the location. Refer to the isActive and activatable fields on the Location object.

Adds a new location.

Deactivates a location and moves inventory, pending orders, and moving transfers to a destination location.

Deletes a location.

Edits an existing location.

As of the 2023-10 API version, apps can change the name and address of their fulfillment service locations.

Disables local pickup for a location.

Enables local pickup for a location.

Creates a new market.

Deletes a market definition.

Deletes all external marketing activities. Deletion is performed by a background job, as it may take a bit of time to complete if a large number of activities are to be deleted. Attempting to create or modify external activities before the job has completed will result in the create/update/upsert mutation returning an error.

Create new marketing activity. Marketing activity app extensions are deprecated and will be removed in the near future.

Creates a new external marketing activity.

Deletes an external marketing activity.

Updates a marketing activity with the latest information. Marketing activity app extensions are deprecated and will be removed in the near future.

Update an external marketing activity.

Creates a new external marketing activity or updates an existing one. When optional fields are absent or null, associated information will be removed from an existing marketing activity.

Creates a new marketing engagement for a marketing activity or a marketing channel.

Marks channel-level engagement data such that it no longer appears in reports. Activity-level data cannot be deleted directly, instead the MarketingActivity itself should be deleted to hide it from reports.

Creates or updates market localizations.

Deletes market localizations.

Updates the properties of a market.

Creates a menu.

Deletes a menu.

Updates a menu.

Creates a metafield definition. Any metafields existing under the same owner type, namespace, and key will be checked against this definition and will have their type updated accordingly. For metafields that are not valid, they will remain unchanged but any attempts to update them must align with this definition.

Delete a metafield definition. Optionally deletes all associated metafields asynchronously when specified.

You can organize your metafields in your Shopify admin by pinning/unpinning metafield definitions. The order of your pinned metafield definitions determines the order in which your metafields are displayed on the corresponding pages in your Shopify admin. By default, only pinned metafields are automatically displayed.

You can organize your metafields in your Shopify admin by pinning/unpinning metafield definitions. The order of your pinned metafield definitions determines the order in which your metafields are displayed on the corresponding pages in your Shopify admin. By default, only pinned metafields are automatically displayed.

Updates a metafield definition.

Deletes multiple metafields in bulk.

Sets metafield values. Metafield values will be set regardless if they were previously created or not.

Allows a maximum of 25 metafields to be set at a time, with a maximum total request payload size of 10MB.

This operation is atomic, meaning no changes are persisted if an error is encountered.

As of 2024-07, this operation supports compare-and-set functionality to better handle concurrent requests. If compareDigest is set for any metafield, the mutation will only set that metafield if the persisted metafield value matches the digest used on compareDigest. If the metafield doesn't exist yet, but you want to guarantee that the operation will run in a safe manner, set compareDigest to null. The compareDigest value can be acquired by querying the metafield object and selecting compareDigest as a field. If the compareDigest value does not match the digest for the persisted value, the mutation will return an error. You can opt out of write guarantees by not sending compareDigest in the request.