UserError

The path to the input field that caused the error.

The error message.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

---

---

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.

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.

Updates a Customer's attributes including personal information and tax exemptions.

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

Updates a customer's default address.

Creates a DeliveryProfile that defines shipping rates for specific products and locations.

A delivery profile groups products with their shipping zones and rates. You can associate profiles with SellingPlanGroup objects to customize shipping for subscriptions and pre-orders. Each profile contains DeliveryProfileLocationGroup objects that specify which Location objects ship to which DeliveryZone objects with specific DeliveryMethodDefinition objects and rates.

Learn more about building delivery profiles.

Enqueue the removal of a delivery profile.

Updates a DeliveryProfile's configuration, including its shipping zones, rates, and associated products.

Modify location groups to control which fulfillment Location objects serve specific geographic areas. Add or remove shipping zones with custom countries and provinces. Create or update shipping methods with rate definitions and delivery conditions. Associate or dissociate ProductVariant objects and SellingPlanGroup objects to determine which products use this profile's shipping rules.

The mutation supports partial updates through dedicated input fields for creating, updating, and deleting specific components without affecting the entire profile structure.

Learn more about building delivery profiles.

Updates the delivery promise participants by adding or removing owners based on a branded promise handle.

Set the delivery settings for a shop.

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

Adds tags to multiple draft orders.

Deletes multiple draft orders.

Removes tags from multiple draft orders.

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

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

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 invoice email for a DraftOrder. The invoice includes a secure checkout link for reviewing and paying for the order. Use the email argument to customize the email, such as the subject and message.

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.

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

Cancels an existing Fulfillment and reverses its effects on associated FulfillmentOrder objects. When you cancel a fulfillment, the system creates new fulfillment orders for the cancelled items so they can be fulfilled again.

The cancellation affects fulfillment orders differently based on their fulfillment status. If a fulfillment order was entirely fulfilled, then it automatically closes. If a fulfillment order is partially fulfilled, then the remaining quantities adjust to include the cancelled items. The system creates new fulfillment orders at the original Location when items are still stocked there, or at alternative locations based on the store's fulfillment priority settings.

Learn more about canceling fulfillments.

Creates a fulfillment for one or more FulfillmentOrder objects. The fulfillment orders are associated with the same Order and are assigned to the same Location.

Use this mutation to mark items as fulfilled when they're ready to ship. You can specify tracking information, customer notification preferences, and which FulfillmentOrderLineItem objects to fulfill from each fulfillment order. If you don't specify line items, then the mutation fulfills all items in the fulfillment order.

Learn more about building fulfillment solutions.

Creates a FulfillmentEvent to track the shipment status and location of items that have shipped. Events capture status updates like carrier pickup, in transit, out for delivery, or delivered.

Each event records the timestamp and current status of the Fulfillment. You can include optional details such as the location where the event occurred, estimated arrival time, and messages for tracking purposes.

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

Accepts a fulfillment request that the fulfillment service has received for a FulfillmentOrder which signals that the fulfillment service will process and fulfill the order. The fulfillment service can optionally provide a message to the merchant and an estimated shipped date when accepting the request.

Learn more about accepting fulfillment requests.

Cancels a FulfillmentOrder and creates a replacement fulfillment order to represent the work left to be done. The original fulfillment order will be marked as closed.

This mutation works when the fulfillment order has a SUBMITTED or CANCELLATION_REQUESTED status. For SUBMITTED orders, cancellation happens immediately because the fulfillment service hasn't accepted the request.

---

---

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.

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 fulfillment order has had progress manually reported. To move a fulfillment order that has had progress manually reported, the fulfillment order must first be marked as open resolving the ongoing progress state.
• 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.

From API version 2026-01, this will also mark a fulfillment order as open when it is assigned to a merchant managed location and has had progress reported.

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.

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

Sends a fulfillment request to the fulfillment service assigned to a FulfillmentOrder. The fulfillment service must then accept or reject the request before processing can begin.

You can either request fulfillment for all line items or specify individual items with quantities for partial fulfillment. When requesting partial fulfillment, Shopify splits the original fulfillment order into two: one with the submitted items and another with the remaining unsubmitted items. Include an optional message to communicate special instructions to the fulfillment service, such as gift wrapping or handling requirements.

Learn more about managing fulfillment requests as a fulfillment service.

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 the FulfillmentService configuration, including its name, callback URL, and operational settings.

The mutation modifies how the fulfillment service handles inventory tracking, shipping requirements, and package tracking support.

---

---

Learn more about editing fulfillment service locations.

Updates tracking information for a fulfillment, including the carrier name, tracking numbers, and tracking URLs. You can provide either single or multiple tracking numbers for shipments with multiple packages.

The mutation accepts a FulfillmentTrackingInput that supports both single tracking (using number and url fields) and multi-package tracking (using numbers and urls fields). When you specify a supported carrier name, Shopify automatically generates tracking URLs for the provided tracking numbers.

You can optionally notify customers about tracking updates with the notifyCustomer argument. When enabled, customers receive shipping update emails with tracking details and receive notifications about future updates to the fulfillment.

Learn more about enabling tracking support for fulfillment services.

Update a gift card.

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

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

---

---

Learn more about managing inventory quantities and states.

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

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

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

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

Deletes Metafield objects in bulk by specifying combinations of owner ID, namespace, and key.

Returns the identifiers of successfully deleted metafields. If a specified metafield doesn't exist, then the mutation still succeeds but returns null for that identifier in the response.

Cancels an order, with options for refunding, restocking inventory, and customer notification.

---

---

Use the orderCancel 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 orderCancel mutation provides flexible refund options including refunding to original payment methods or issuing store credit. If a payment was only authorized (temporarily held) but not yet charged, that hold will be automatically released when the order is cancelled, even if you choose not to refund other payments.

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

For partial refunds or more complex refund scenarios on active orders, such as refunding only specific line items while keeping the rest of the order fulfilled, consider using the refundCreate mutation instead of full order cancellation.

Learn how to build apps that integrate with order management and fulfillment processes.

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 orderCapture 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

---

---

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.

Marks an open Order as closed. A closed order is one where merchants fulfill or cancel all LineItem objects and complete all financial transactions.

Once closed, the order indicates that no further work is required. The order's closedAt timestamp is set when this mutation completes successfully.

Adds a custom line item to an existing Order. Custom line items represent products or services not in your catalog, such as gift wrapping, installation fees, or one-off charges.

Creates a CalculatedLineItem with the specified title, price, and quantity. Changes remain in the edit session until you commit them with the orderEditCommit mutation.

Learn more about adding custom line items.

Applies a discount to a LineItem during an order edit session. The discount can be either a fixed amount or percentage value.

To modify pricing on specific line items, use this mutation after starting an order edit with the orderEditBegin mutation. The changes remain staged until you commit them with the orderEditCommit mutation.

Learn more about editing existing orders.

Adds a ProductVariant as a line item to an Order that's being edited. The mutation respects the variant's contextual pricing.

You can specify a Location to check for inventory availability and control whether duplicate variants are allowed. The quantity must be a positive value.

Learn more about editing existing orders.

Starts an order editing session that enables you to modify an existing Order. This mutation creates an OrderEditSession and returns a CalculatedOrder showing how the order looks with your changes applied.

Order editing follows a three-step workflow: Begin the edit with orderEditBegin, apply changes using mutations like orderEditAddVariant or orderEditSetQuantity, and then save the changes with the orderEditCommit mutation. The session tracks all staged changes until you commit or abandon them.

Learn more about editing existing orders.

Applies staged changes from an order editing session to the original order. This finalizes all modifications made during the edit session, including changes to line items, quantities, discounts, and shipping lines.

Order editing follows a three-step workflow: start with orderEditBegin to create an editing session, apply changes using various orderEdit mutations, and then save the changes with the orderEditCommit mutation. The mutation can optionally notify the customer of changes and add staff notes for internal tracking.

You can only edit unfulfilled line items. If an edit changes the total order value, then the customer might need to pay a balance or receive a refund.

Learn more about editing existing orders.

Sets the quantity of a line item on an order that's being edited. Use this mutation to increase, decrease, or remove items by adjusting their quantities.

Setting the quantity to zero effectively removes the line item from the order. The item still exists as a data structure with zero quantity. When decreasing quantities, you can optionally restock the removed items to inventory by setting the restock parameter to true.

Learn more about editing workflows for existing orders.

Marks an order as paid by recording a payment transaction for the outstanding amount.

Use the orderMarkAsPaid mutation to record payments received outside the standard checkout process. The orderMarkAsPaid mutation 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 PAID. 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.

Opens a closed order.

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 orderEditBegin mutation instead. The orderEditBegin mutation initiates an order editing session, allowing you to make multiple changes before finalizing them. Learn more about using the orderEditBegin mutation to edit existing orders.

If you need to remove a customer from an order, then use the orderCustomerRemove mutation instead.

Learn how to build apps that integrate with order management and fulfillment processes.

Creates a product bundle that groups multiple Product objects together as components. The bundle appears as a single product in the store, with its price determined by the parent product and inventory calculated from the component products.

The mutation runs asynchronously and returns a ProductBundleOperation object to track the creation status. Poll the operation using the productOperation query to determine when the bundle is ready.

Learn more about creating product fixed bundles.

Updates a product bundle or componentized product.

Creates a product with attributes such as title, description, vendor, and media.

The productCreate 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 productCreate mutation only supports creating a product with its initial product variant. To create multiple product variants for a single product and manage prices, use the productVariantsBulkCreate mutation.

---

---

After you create a product, you can make subsequent edits to the product using one of the following mutations:

• publishablePublish: Used to publish the product and make it available to customers. The productCreate mutation creates products in an unpublished state by default, so you must perform a separate operation to publish the product.
• productUpdate: Used to update a single product, such as changing the product's title, description, vendor, or associated media.
• productSet: 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.

Permanently deletes a product and all its associated data, including variants, media, publications, and inventory items.

Use the productDelete 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 productDelete 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 productDelete 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.

---

---

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 synchronous parameter to false to run the deletion asynchronously, which returns a ProductDeleteOperation that you can monitor for completion status.

If you need more granular control over product cleanup, consider using these alternative mutations:

• productUpdate: Update the product status to archived or unpublished instead of deleting.
• productVariantsBulkDelete: Delete specific variants while keeping the product.
• productOptionsDelete: Delete the choices available for a product, such as size, color, or material.

Learn more about the product model.

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: false argument in this mutation to perform the duplication asynchronously.

In API version 2024-07 and lower, use the asynchronous ProductDuplicateAsyncV2.

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