--- title: UserError - GraphQL Admin description: An error in the input of a mutation. Mutations return `UserError` objects to indicate validation failures, such as invalid field values or business logic violations, that prevent the operation from completing. api_version: 2025-10 api_name: admin type: object api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/latest/objects/usererror md: https://shopify.dev/docs/api/admin-graphql/latest/objects/usererror.md --- # User​Error object An error in the input of a mutation. Mutations return `UserError` objects to indicate validation failures, such as invalid field values or business logic violations, that prevent the operation from completing. ## Fields * field [\[String!\]](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The path to the input field that caused the error. * message [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null The error message. *** ## Map ### Fields with this object * {}[AppFeedback.messages](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppFeedback#field-AppFeedback.fields.messages) * {}[MarketingActivityExtensionAppErrors.userErrors](https://shopify.dev/docs/api/admin-graphql/latest/objects/MarketingActivityExtensionAppErrors#field-MarketingActivityExtensionAppErrors.fields.userErrors) * {}[ProductDeleteOperation.userErrors](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductDeleteOperation#field-ProductDeleteOperation.fields.userErrors) * {}[ProductDuplicateOperation.userErrors](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductDuplicateOperation#field-ProductDuplicateOperation.fields.userErrors) *** ## Mutations * [app​Purchase​One​Time​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appPurchaseOneTimeCreate) mutation 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](https://shopify.dev/docs/apps/launch/billing/support-one-time-purchases). * [app​Subscription​Cancel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCancel) mutation 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](https://shopify.dev/docs/apps/launch/billing/subscription-billing). * [app​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate) mutation Creates a recurring or usage-based [`AppSubscription`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscription) that charges merchants for app features and services. The subscription includes one or more [`AppSubscriptionLineItem`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscriptionLineItem) objects that define the pricing structure, billing intervals, and optional [`AppSubscriptionDiscount`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppSubscriptionDiscount) values. Returns a [confirmation URL](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate#returns-confirmationUrl) 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`](https://shopify.dev/docs/api/admin-graphql/latest/enums/AppSubscriptionReplacementBehavior) to control how this subscription interacts with existing active subscriptions. Learn more about [creating app subscriptions](https://shopify.dev/docs/apps/launch/billing/subscription-billing/create-time-based-subscriptions). * [app​Subscription​Line​Item​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionLineItemUpdate) mutation Updates the capped amount on usage-based billing for an [`AppSubscriptionLineItem`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate#returns-confirmationUrl) 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](https://shopify.dev/docs/apps/launch/billing/subscription-billing/update-max-charge). * [app​Usage​Record​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appUsageRecordCreate) mutation 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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-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](https://shopify.dev/docs/apps/launch/billing/subscription-billing/create-usage-based-subscriptions). * [bulk​Operation​Cancel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/bulkOperationCancel) mutation Starts the cancelation process of a running bulk operation. There may be a short delay from when a cancelation starts until the operation is actually canceled. * [collection​Add​Products](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionAddProducts) mutation 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](https://shopify.dev/docs/api/admin-graphql/latest/objects/Collection). * [collection​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionCreate) mutation Creates a [collection](https://shopify.dev/docs/api/admin-graphql/latest/objects/Collection) to group [products](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product) together in the [online store](https://shopify.dev/docs/apps/build/online-store) and other [sales channels](https://shopify.dev/docs/apps/build/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](https://help.shopify.com/manual/products/collections/manual-shopify-collection)**: You specify the products to include in a collection. * **[Smart (automated) collections](https://help.shopify.com/manual/products/collections/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 [`publishablePublish`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/publishablePublish) mutation after creation. *** Learn more about [using metafields with smart collections](https://shopify.dev/docs/apps/build/custom-data/metafields/use-metafield-capabilities). * [collection​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionDelete) mutation 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](https://shopify.dev/docs/api/admin-graphql/latest/objects/Collection). * [collection​Remove​Products](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionRemoveProducts) mutation 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](https://shopify.dev/docs/api/admin-graphql/latest/objects/Collection). * [collection​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionUpdate) mutation Updates a [collection](https://shopify.dev/docs/api/admin-graphql/latest/objects/Collection), modifying its properties, products, or publication settings. Collections help organize [products](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product) together in the [online store](https://shopify.dev/docs/apps/build/online-store) and other [sales channels](https://shopify.dev/docs/apps/build/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](https://shopify.dev/docs/apps/build/custom-data/metafields) There are two types of collections with different update capabilities: * **[Custom (manual) collections](https://help.shopify.com/manual/products/collections/manual-shopify-collection)**: You can update collection properties, but rule sets can't be modified since products are manually selected. * **[Smart (automated) collections](https://help.shopify.com/manual/products/collections/automated-collections)**: You can update both collection properties and the rules that automatically determine which products are included. When updating [rule sets](https://shopify.dev/docs/api/admin-graphql/latest/objects/CollectionRuleConditions) for smart collections, the operation might be processed asynchronously. In these cases, the mutation returns a [`job`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/publishablePublish) and [`publishableUnpublish`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/publishableUnpublish) mutations. Learn more about [using metafields with smart collections](https://shopify.dev/docs/apps/build/custom-data/metafields/use-metafield-capabilities). * [customer​Address​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerAddressCreate) mutation Creates a new [`MailingAddress`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MailingAddress) for a [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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. * [customer​Address​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerAddressDelete) mutation Deletes a customer's address. * [customer​Address​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerAddressUpdate) mutation Updates a [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer)'s [`MailingAddress`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MailingAddress). You can modify any field of the address and optionally set it as the customer's default address. * [customer​Add​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerAddTaxExemptions) mutation Add tax exemptions for the customer. * [customer​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerCreate) mutation Creates a new [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer) in the store. Accepts customer details including contact information, marketing consent preferences, and tax exemptions through the [`CustomerInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/CustomerInput) input object. You can also associate [`metafields`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MetafieldInput) and tags to organize and extend customer data. Apps using protected customer data must meet Shopify's [protected customer data requirements](https://shopify.dev/docs/apps/launch/protected-customer-data#requirements). * [customer​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerDelete) mutation Deletes a [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer) from the store. You can only delete customers who haven't placed any [orders](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order). Apps using protected customer data must meet Shopify's [protected customer data requirements](https://shopify.dev/docs/apps/launch/protected-customer-data#requirements). * [customer​Generate​Account​Activation​Url](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerGenerateAccountActivationUrl) mutation Generates a one-time activation URL for a [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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 [`account states`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer#field-Customer.fields.state). Attempting to generate a URL for an already-enabled customer returns an error. *** * [customer​Payment​Method​Credit​Card​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerPaymentMethodCreditCardCreate) mutation Creates a credit card payment method for a customer using a session id. These values are only obtained through card imports happening from a PCI compliant environment. Please use customerPaymentMethodRemoteCreate if you are not managing credit cards directly. * [customer​Payment​Method​Credit​Card​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerPaymentMethodCreditCardUpdate) mutation Updates the credit card payment method for a customer. * [customer​Payment​Method​Revoke](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerPaymentMethodRevoke) mutation Revokes a customer's payment method. * [customer​Payment​Method​Send​Update​Email](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerPaymentMethodSendUpdateEmail) mutation Sends a link to the customer so they can update a specific payment method. * [customer​Remove​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerRemoveTaxExemptions) mutation Remove tax exemptions from a customer. * [customer​Replace​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerReplaceTaxExemptions) mutation Replace tax exemptions for a customer. * [customer​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerUpdate) mutation Updates a [`Customer`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer)'s attributes including personal information and [`tax exemptions`](https://shopify.dev/docs/api/admin-graphql/latest/enums/TaxExemption). Apps using protected customer data must meet Shopify's [protected customer data requirements](https://shopify.dev/docs/apps/launch/protected-customer-data#requirements). * [customer​Update​Default​Address](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerUpdateDefaultAddress) mutation Updates a customer's default address. * [delivery​Profile​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryProfileCreate) mutation Creates a [`DeliveryProfile`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/SellingPlanGroup) objects to customize shipping for subscriptions and pre-orders. Each profile contains [`DeliveryProfileLocationGroup`](https://shopify.dev/docs/api/admin-graphql/latest/objects/DeliveryProfileLocationGroup) objects that specify which [`Location`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Location) objects ship to which [`DeliveryZone`](https://shopify.dev/docs/api/admin-graphql/latest/objects/DeliveryZone) objects with specific [`DeliveryMethodDefinition`](https://shopify.dev/docs/api/admin-graphql/latest/objects/DeliveryMethodDefinition) objects and rates. Learn more about [building delivery profiles](https://shopify.dev/docs/apps/build/purchase-options/deferred/delivery-and-deferment/build-delivery-profiles). * [delivery​Profile​Remove](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryProfileRemove) mutation Enqueue the removal of a delivery profile. * [delivery​Profile​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryProfileUpdate) mutation Updates a [`DeliveryProfile`](https://shopify.dev/docs/api/admin-graphql/latest/objects/DeliveryProfile)'s configuration, including its shipping zones, rates, and associated products. Modify location groups to control which fulfillment [`Location`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductVariant) objects and [`SellingPlanGroup`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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](https://shopify.dev/docs/apps/build/purchase-options/deferred/delivery-and-deferment/build-delivery-profiles). * [delivery​Promise​Participants​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryPromiseParticipantsUpdate) mutation Updates the delivery promise participants by adding or removing owners based on a branded promise handle. * [delivery​Setting​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliverySettingUpdate) mutation Set the delivery settings for a shop. * [delivery​Shipping​Origin​Assign](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryShippingOriginAssign) mutation Assigns a location as the shipping origin while using legacy compatibility mode for multi-location delivery profiles. * [draft​Order​Bulk​Add​Tags](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderBulkAddTags) mutation Adds tags to multiple draft orders. * [draft​Order​Bulk​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderBulkDelete) mutation Deletes multiple draft orders. * [draft​Order​Bulk​Remove​Tags](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderBulkRemoveTags) mutation Removes tags from multiple draft orders. * [draft​Order​Calculate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderCalculate) mutation Calculates the properties of a draft order. Useful for determining information such as total taxes or price without actually creating a draft order. * [draft​Order​Complete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderComplete) mutation Completes a [draft order](https://shopify.dev/docs/api/admin-graphql/latest/objects/DraftOrder) and converts it into a [regular order](https://shopify.dev/docs/api/admin-graphql/latest/objects/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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderComplete#arguments-sourceName) argument, [cart validation](https://shopify.dev/docs/apps/build/checkout/cart-checkout-validation) controls for app integrations, and detailed error reporting for failed completions. You can complete a draft order with different [payment scenarios](https://help.shopify.com/manual/fulfillment/managing-orders/payments): * Mark the order as paid immediately. * Set the order as payment pending using [payment terms](https://shopify.dev/docs/api/admin-graphql/latest/objects/PaymentTerms). * Specify a custom payment amount. * Select a specific payment gateway. *** Note When completing a draft order, inventory is [reserved](https://shopify.dev/docs/apps/build/orders-fulfillment/inventory-management-apps#inventory-states) for the items in the order. This means the items will no longer be available for other customers to purchase. Make sure to verify inventory availability before completing the draft order. *** * [draft​Order​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderCreate) mutation Creates a [draft order](https://shopify.dev/docs/api/admin-graphql/latest/objects/DraftOrder) 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderInvoiceSend) mutation. * Complete the draft order using the [`draftOrderComplete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderComplete) mutation. * Update the draft order using the [`draftOrderUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderUpdate) mutation. * Duplicate a draft order using the [`draftOrderDuplicate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderDuplicate) mutation. * Delete the draft order using the [`draftOrderDelete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderDelete) mutation. *** Note When you create a draft order, you can't [reserve or hold inventory](https://shopify.dev/docs/apps/build/orders-fulfillment/inventory-management-apps#inventory-states) for the items in the order by default. However, you can reserve inventory using the [`reserveInventoryUntil`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderCreate#arguments-input.fields.reserveInventoryUntil) input. *** * [draft​Order​Create​From​Order](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderCreateFromOrder) mutation Creates a draft order from order. * [draft​Order​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderDelete) mutation Deletes a draft order. * [draft​Order​Duplicate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderDuplicate) mutation Duplicates a draft order. * [draft​Order​Invoice​Preview](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderInvoicePreview) mutation Previews a draft order invoice email. * [draft​Order​Invoice​Send](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderInvoiceSend) mutation Sends an invoice email for a [`DraftOrder`](https://shopify.dev/docs/api/admin-graphql/latest/objects/DraftOrder). The invoice includes a secure checkout link for reviewing and paying for the order. Use the [`email`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderInvoiceSend#arguments-email) argument to customize the email, such as the subject and message. * [draft​Order​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/draftOrderUpdate) mutation Updates a draft order. If a checkout has been started for a draft order, any update to the draft will unlink the checkout. Checkouts are created but not immediately completed when opening the merchant credit card modal in the admin, and when a buyer opens the invoice URL. This is usually fine, but there is an edge case where a checkout is in progress and the draft is updated before the checkout completes. This will not interfere with the checkout and order creation, but if the link from draft to checkout is broken the draft will remain open even after the order is created. * [flow​Trigger​Receive](https://shopify.dev/docs/api/admin-graphql/latest/mutations/flowTriggerReceive) mutation Triggers any workflows that begin with the trigger specified in the request body. To learn more, refer to [*Create Shopify Flow triggers*](https://shopify.dev/apps/flow/triggers). * [fulfillment​Cancel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentCancel) mutation Cancels a fulfillment. * [fulfillment​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentCreate) mutation Creates a fulfillment for one or many fulfillment orders. The fulfillment orders are associated with the same order and are assigned to the same location. * [fulfillment​Event​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentEventCreate) mutation Creates a fulfillment event for a specified fulfillment. * [fulfillment​Order​Accept​Cancellation​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentOrderAcceptCancellationRequest) mutation Accept a cancellation request sent to a fulfillment service for a fulfillment order. * [fulfillment​Order​Accept​Fulfillment​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentOrderAcceptFulfillmentRequest) mutation Accepts a fulfillment request sent to a fulfillment service for a fulfillment order. * [fulfillment​Order​Cancel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentOrderCancel) mutation Marks a fulfillment order as canceled. * [fulfillment​Order​Close](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentOrderClose) mutation Marks an in-progress fulfillment order as incomplete, indicating the fulfillment service is unable to ship any remaining items, and closes the fulfillment request. This mutation can only be called for fulfillment orders that meet the following criteria: * Assigned to a fulfillment service location, * The fulfillment request has been accepted, * The fulfillment order status is `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](https://shopify.dev/apps/build/orders-fulfillment/fulfillment-service-apps/build-for-fulfillment-services#step-7-optional-close-a-fulfillment-order). * [fulfillment​Order​Move](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentOrderMove) mutation Changes the location which is assigned to fulfill a number of unfulfilled fulfillment order line items. Moving a fulfillment order will fail in the following circumstances: * The fulfillment order is closed. * The 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](https://shopify.dev/docs/api/admin-graphql/latest/enums/FulfillmentOrderRequestStatus) 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](https://shopify.dev/docs/api/admin-graphql/latest/objects/fulfillmentorder#field-fulfillmentorder-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. * [fulfillment​Order​Open](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentOrderOpen) mutation 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. * [fulfillment​Order​Reject​Cancellation​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentOrderRejectCancellationRequest) mutation Rejects a cancellation request sent to a fulfillment service for a fulfillment order. * [fulfillment​Order​Reject​Fulfillment​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentOrderRejectFulfillmentRequest) mutation Rejects a fulfillment request sent to a fulfillment service for a fulfillment order. * [fulfillment​Order​Submit​Cancellation​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentOrderSubmitCancellationRequest) mutation Sends a cancellation request to the fulfillment service of a fulfillment order. * [fulfillment​Order​Submit​Fulfillment​Request](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentOrderSubmitFulfillmentRequest) mutation Sends a fulfillment request to the fulfillment service of a fulfillment order. * [fulfillment​Service​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentServiceCreate) mutation Creates a fulfillment service. ## Fulfillment service location When creating a fulfillment service, a new location will be automatically created on the shop and will be associated with this fulfillment service. This location will be named after the fulfillment service and inherit the shop's address. If you are using API version `2023-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](https://shopify.dev/api/admin-graphql/latest/mutations/locationEdit) mutation after creating the fulfillment service. * [fulfillment​Service​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentServiceDelete) mutation Deletes a fulfillment service. * [fulfillment​Service​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentServiceUpdate) mutation Updates a fulfillment service. If you need to update the location managed by the fulfillment service (for example, to change the address of a fulfillment service), use the [LocationEdit](https://shopify.dev/api/admin-graphql/latest/mutations/locationEdit) mutation. * [fulfillment​Tracking​Info​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentTrackingInfoUpdate) mutation Updates tracking information for a fulfillment. * [gift​Card​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/giftCardUpdate) mutation Update a gift card. * [inventory​Activate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/inventoryActivate) mutation Activate an inventory item at a location. * [inventory​Deactivate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/inventoryDeactivate) mutation Removes an inventory item's quantities from a location, and turns off inventory at the location. * [inventory​Item​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/inventoryItemUpdate) mutation Updates an inventory item. * [marketing​Activity​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/marketingActivityCreate) mutation Create new marketing activity. Marketing activity app extensions are deprecated and will be removed in the near future. * [marketing​Activity​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/marketingActivityUpdate) mutation Updates a marketing activity with the latest information. Marketing activity app extensions are deprecated and will be removed in the near future. * [metafields​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldsDelete) mutation Deletes [`Metafield`](https://shopify.dev/docs/api/admin-graphql/current/objects/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. * [order​Cancel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderCancel) mutation Cancels an order, with options for refunding, restocking inventory, and customer notification. *** Caution Order cancellation is irreversible. An order that has been cancelled can't be restored to its original state. *** 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](https://help.shopify.com/manual/fulfillment/setup/locations-management#deactivate-and-reactivate-locations) 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/refundCreate) mutation instead of full order cancellation. Learn how to build apps that integrate with [order management and fulfillment processes](https://shopify.dev/docs/apps/build/orders-fulfillment). * [order​Capture](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderCapture) mutation Captures payment for an authorized transaction on an order. Use this mutation to claim the money that was previously reserved by an authorization transaction. The `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](https://shopify.dev/docs/api/admin-graphql/latest/objects/ordertransaction#field-OrderTransaction.fields.multiCapturable) *** Note Multi-capture functionality is only available to stores on a [Shopify Plus plan](https://help.shopify.com/manual/intro-to-shopify/pricing-plans/plans-features/shopify-plus-plan). For multi-currency orders, the [`currency`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderCapture#arguments-input.fields.currency) field is required and should match the presentment currency from the order. *** After capturing a payment, you can: * View the transaction details including status, amount, and processing information. * Track the captured amount in both shop and presentment currencies. * Monitor the transaction's settlement status. Learn more about [order transactions](https://shopify.dev/docs/api/admin-graphql/latest/objects/OrderTransaction). * [order​Close](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderClose) mutation Marks an open [`Order`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order) as closed. A closed order is one where merchants fulfill or cancel all [`LineItem`](https://shopify.dev/docs/api/admin-graphql/latest/objects/LineItem) objects and complete all financial transactions. Once closed, the order indicates that no further work is required. The order's [`closedAt`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order#field-closedAt) timestamp is set when this mutation completes successfully. * [order​Edit​Add​Custom​Item](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderEditAddCustomItem) mutation Adds a custom line item to an existing order. For example, you could add a gift wrapping service as a [custom line item](https://shopify.dev/apps/fulfillment/order-management-apps/order-editing#add-a-custom-line-item). To learn how to edit existing orders, refer to [Edit an existing order with Admin API](https://shopify.dev/apps/fulfillment/order-management-apps/order-editing). * [order​Edit​Add​Line​Item​Discount](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderEditAddLineItemDiscount) mutation Adds a discount to a line item on the current order edit. For more information on how to use the GraphQL Admin API to edit an existing order, refer to [Edit existing orders](https://shopify.dev/apps/fulfillment/order-management-apps/order-editing). * [order​Edit​Add​Variant](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderEditAddVariant) mutation Adds a line item from an existing product variant. As of API version 2025-04, the [orderEditAddVariant](https://shopify.dev/api/admin-graphql/latest/mutations/ordereditaddvariant) API will respect the contextual pricing of the variant. * [order​Edit​Begin](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderEditBegin) mutation Starts editing an order. Mutations are operating on `OrderEdit`. All order edits start with `orderEditBegin`, have any number of `orderEdit`\* mutations made, and end with `orderEditCommit`. * [order​Edit​Commit](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderEditCommit) mutation Applies and saves staged changes to an order. Mutations are operating on `OrderEdit`. All order edits start with `orderEditBegin`, have any number of `orderEdit`\* mutations made, and end with `orderEditCommit`. * [order​Edit​Set​Quantity](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderEditSetQuantity) mutation 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](https://shopify.dev/docs/apps/build/orders-fulfillment/order-management-apps/edit-orders). * [order​Mark​As​Paid](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderMarkAsPaid) mutation 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](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order#field-Order.fields.displayFinancialStatus) 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](https://shopify.dev/docs/apps/build/orders-fulfillment/order-management-apps) in apps. * [order​Open](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderOpen) mutation Opens a closed order. * [order​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderUpdate) mutation Updates the attributes of an order, such as the customer's email, the shipping address for the order, tags, and [metafields](https://shopify.dev/docs/apps/build/custom-data) 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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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](https://shopify.dev/docs/apps/build/orders-fulfillment/order-management-apps/edit-orders). If you need to remove a customer from an order, then use the [`orderCustomerRemove`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderCustomerRemove) mutation instead. Learn how to build apps that integrate with [order management and fulfillment processes](https://shopify.dev/docs/apps/build/orders-fulfillment). * [product​Bundle​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productBundleCreate) mutation Creates a product bundle that groups multiple [`Product`](https://shopify.dev/docs/api/admin-graphql/latest/objects/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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductBundleOperation) object to track the creation status. Poll the operation using the [`productOperation`](https://shopify.dev/docs/api/admin-graphql/latest/queries/productOperation) query to determine when the bundle is ready. Learn more about [creating product fixed bundles](https://shopify.dev/docs/apps/build/product-merchandising/bundles/add-product-fixed-bundle#step-1-create-a-bundle). * [product​Bundle​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productBundleUpdate) mutation Updates a product bundle or componentized product. * [product​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productCreate) mutation Creates a [product](https://shopify.dev/docs/api/admin-graphql/latest/objects/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](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductOption) and [values](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductOptionValue), 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](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductVariant). To create multiple product variants for a single product and manage prices, use the [`productVariantsBulkCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productVariantsBulkCreate) mutation. *** Note The `productCreate` mutation has a [throttle](https://shopify.dev/docs/api/usage/rate-limits#resource-based-rate-limits) that takes effect when a store has 50,000 product variants. After this threshold is reached, no more than 1,000 new product variants can be created per day. *** After you create a product, you can make subsequent edits to the product using one of the following mutations: * [`publishablePublish`](https://shopify.dev/docs/api/admin-graphql/latest/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`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productUpdate): Used to update a single product, such as changing the product's title, description, vendor, or associated media. * [`productSet`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productSet): Used to perform multiple operations on products, such as creating or modifying product options and variants. Learn more about the [product model](https://shopify.dev/docs/apps/build/graphql/migrate/new-product-model) and [adding product data](https://shopify.dev/docs/apps/build/graphql/migrate/new-product-model/add-data). * [product​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productDelete) mutation 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](https://shopify.dev/api/admin-graphql/latest/objects/ProductOption) and [option values](https://shopify.dev/api/admin-graphql/latest/objects/ProductOptionValue) * 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. *** Caution Product deletion is irreversible. After a product is deleted, it can't be recovered. Consider archiving or unpublishing products instead if you might need to restore them later. *** If you need to delete a large product, such as one that has many [variants](https://shopify.dev/api/admin-graphql/latest/objects/ProductVariant) that are active at several [locations](https://shopify.dev/api/admin-graphql/latest/objects/Location), you might encounter timeout errors. To avoid these timeout errors, you can set the [`synchronous`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productDelete#arguments-synchronous) parameter to `false` to run the deletion asynchronously, which returns a [`ProductDeleteOperation`](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductDeleteOperation) that you can monitor for completion status. If you need more granular control over product cleanup, consider using these alternative mutations: * [`productUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productUpdate): Update the product status to archived or unpublished instead of deleting. * [`productVariantsBulkDelete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productVariantsBulkDelete): Delete specific variants while keeping the product. * [`productOptionsDelete`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productOptionsDelete): Delete the choices available for a product, such as size, color, or material. Learn more about the [product model](https://shopify.dev/docs/apps/build/graphql/migrate/new-product-model). * [product​Duplicate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productDuplicate) mutation Duplicates a product. If you need to duplicate a large product, such as one that has many [variants](https://shopify.dev/api/admin-graphql/latest/input-objects/ProductVariantInput) that are active at several [locations](https://shopify.dev/api/admin-graphql/latest/input-objects/InventoryLevelInput), 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`](https://shopify.dev/api/admin-graphql/2024-07/mutations/productDuplicateAsyncV2). Metafield values are not duplicated if the unique values capability is enabled. * [product​Reorder​Media](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productReorderMedia) mutation Asynchronously reorders the media attached to a product, changing the sequence in which images, videos, and other media appear in product displays. This affects how media is presented across all sales channels. For example, merchants can move their best product photo to the first position or reorder images to tell a better product story, with changes appearing in storefronts once processing completes. Use `ProductReorderMedia` to: * Optimize media presentation order for better customer experience * Implement drag-and-drop media management interfaces * Automate media sequencing based on performance or quality metrics The operation processes asynchronously to handle products with large media collections without blocking other operations. Learn more about [product media](https://shopify.dev/docs/api/admin-graphql/latest/objects/Media). * [product​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productUpdate) mutation Updates a [product](https://shopify.dev/docs/api/admin-graphql/latest/objects/Product) with attributes such as title, description, vendor, and media. The `productUpdate` mutation helps you modify many products at once, avoiding the tedious or time-consuming process of updating them one by one in the Shopify admin. Common examples including updating product details like status or tags. The `productUpdate` mutation doesn't support updating [product variants](https://shopify.dev/docs/api/admin-graphql/latest/objects/ProductVariant). To update multiple product variants for a single product and manage prices, use the [`productVariantsBulkUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productVariantsBulkUpdate) mutation. *** Note The `productUpdate` mutation has a [throttle](https://shopify.dev/docs/api/usage/rate-limits#resource-based-rate-limits) that takes effect when a store has 50,000 product variants. After this threshold is reached, no more than 1,000 new product variants can be updated per day. *** After updating a product, you can make additional changes using one of the following mutations: * [`productSet`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productSet): Used to perform multiple operations on products, such as creating or modifying product options and variants. * [`publishablePublish`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/publishablePublish): Used to publish the product and make it available to customers, if the product is currently unpublished. Learn more about the [product model](https://shopify.dev/docs/apps/build/graphql/migrate/new-product-model) and [adding product data](https://shopify.dev/docs/apps/build/graphql/migrate/new-product-model/add-data). * [publishable​Publish](https://shopify.dev/docs/api/admin-graphql/latest/mutations/publishablePublish) mutation Publishes a resource to a channel. If the resource is a product, then it's visible in the channel only if the product status is `active`. Products that are sold exclusively on subscription (`requiresSellingPlan: true`) can be published only on online stores. * [publishable​Publish​To​Current​Channel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/publishablePublishToCurrentChannel) mutation Publishes a resource to current channel. If the resource is a product, then it's visible in the channel only if the product status is `active`. Products that are sold exclusively on subscription (`requiresSellingPlan: true`) can be published only on online stores. * [publishable​Unpublish](https://shopify.dev/docs/api/admin-graphql/latest/mutations/publishableUnpublish) mutation Unpublishes a resource from a channel. If the resource is a product, then it's visible in the channel only if the product status is `active`. * [publishable​Unpublish​To​Current​Channel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/publishableUnpublishToCurrentChannel) mutation Unpublishes a resource from the current channel. If the resource is a product, then it's visible in the channel only if the product status is `active`. * [refund​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/refundCreate) mutation Creates a refund for an order, allowing you to process returns and issue payments back to customers. Use the `refundCreate` mutation to programmatically process refunds in scenarios where you need to return money to customers, such as when handling returns, processing chargebacks, or correcting order errors. The `refundCreate` mutation supports various refund scenarios: * Refunding line items with optional restocking * Refunding shipping costs * Refunding duties and import taxes * Refunding additional fees * Processing refunds through different payment methods * Issuing store credit refunds (when enabled) You can create both full and partial refunds, and optionally allow over-refunding in specific cases. After creating a refund, you can track its status and details through the order's [`refunds`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order#field-Order.fields.refunds) field. The refund is associated with the order and can be used for reporting and reconciliation purposes. Learn more about [managing returns](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/build-return-management) and [refunding duties](https://shopify.dev/docs/apps/build/orders-fulfillment/returns-apps/view-and-refund-duties). *** Note The refunding behavior of the `refundCreate` mutation is similar to the [`refundReturn`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/returnRefund) mutation. The key difference is that the `refundCreate` mutation lets you to specify restocking behavior for line items, whereas the `returnRefund` mutation focuses solely on handling the financial refund without any restocking input. *** * [saved​Search​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/savedSearchCreate) mutation Creates a saved search. * [saved​Search​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/savedSearchDelete) mutation Delete a saved search. * [saved​Search​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/savedSearchUpdate) mutation Updates a saved search. * [script​Tag​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/scriptTagCreate) mutation Theme app extensions If your app integrates with a Shopify theme and you plan to submit it to the Shopify App Store, you must use theme app extensions instead of Script tags. Script tags can only be used with vintage themes. [Learn more](https://shopify.dev/apps/online-store#what-integration-method-should-i-use). Script tag deprecation Script tags will be sunset for the **Order status** page on August 28, 2025. [Upgrade to Checkout Extensibility](https://www.shopify.com/plus/upgrading-to-checkout-extensibility) before this date. [Shopify Scripts](https://shopify.dev/docs/api/liquid/objects#script) will continue to work alongside Checkout Extensibility until August 28, 2025. Creates a new script tag. * [script​Tag​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/scriptTagDelete) mutation Theme app extensions If your app integrates with a Shopify theme and you plan to submit it to the Shopify App Store, you must use theme app extensions instead of Script tags. Script tags can only be used with vintage themes. [Learn more](https://shopify.dev/apps/online-store#what-integration-method-should-i-use). Script tag deprecation Script tags will be sunset for the **Order status** page on August 28, 2025. [Upgrade to Checkout Extensibility](https://www.shopify.com/plus/upgrading-to-checkout-extensibility) before this date. [Shopify Scripts](https://shopify.dev/docs/api/liquid/objects#script) will continue to work alongside Checkout Extensibility until August 28, 2025. Deletes a script tag. * [script​Tag​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/scriptTagUpdate) mutation Theme app extensions If your app integrates with a Shopify theme and you plan to submit it to the Shopify App Store, you must use theme app extensions instead of Script tags. Script tags can only be used with vintage themes. [Learn more](https://shopify.dev/apps/online-store#what-integration-method-should-i-use). Script tag deprecation Script tags will be sunset for the **Order status** page on August 28, 2025. [Upgrade to Checkout Extensibility](https://www.shopify.com/plus/upgrading-to-checkout-extensibility) before this date. [Shopify Scripts](https://shopify.dev/docs/api/liquid/objects#script) will continue to work alongside Checkout Extensibility until August 28, 2025. Updates a script tag. * [segment​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/segmentCreate) mutation Creates a segment. * [segment​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/segmentDelete) mutation Deletes a segment. * [segment​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/segmentUpdate) mutation Updates a segment. * [shipping​Package​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/shippingPackageDelete) mutation Deletes a shipping package. * [shipping​Package​Make​Default](https://shopify.dev/docs/api/admin-graphql/latest/mutations/shippingPackageMakeDefault) mutation Set a shipping package as the default. The default shipping package is the one used to calculate shipping costs on checkout. * [shipping​Package​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/shippingPackageUpdate) mutation Updates a shipping package. * [shop​Locale​Disable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/shopLocaleDisable) mutation Deletes a locale for a shop. This also deletes all translations of this locale. * [shop​Locale​Enable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/shopLocaleEnable) mutation Adds a locale for a shop. The newly added locale is in the unpublished state. * [shop​Locale​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/shopLocaleUpdate) mutation Updates a locale for a shop. * [staged​Uploads​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/stagedUploadsCreate) mutation Creates staged upload targets for file uploads such as images, videos, and 3D models. Use the `stagedUploadsCreate` mutation instead of direct file creation mutations when: * **Uploading large files**: Files over a few MB benefit from staged uploads for better reliability * **Uploading media files**: Videos, 3D models, and high-resolution images * **Bulk importing**: CSV files, product catalogs, or other bulk data * **Using external file sources**: When files are stored remotely and need to be transferred to Shopify The `stagedUploadsCreate` mutation is the first step in Shopify's secure two-step upload process: **Step 1: Create staged upload targets** (this mutation) * Generate secure, temporary upload URLs for your files. * Receive authentication parameters for the upload. **Step 2: Upload files and create assets** * Upload your files directly to the provided URLs using the authentication parameters. * Use the returned `resourceUrl` as the `originalSource` in subsequent mutations like `fileCreate`. This approach provides better performance for large files, handles network interruptions gracefully, and ensures secure file transfers to Shopify's storage infrastructure. *** Note File size is required when uploading [`VIDEO`](https://shopify.dev/docs/api/admin-graphql/latest/enums/StagedUploadTargetGenerateUploadResource#enums-VIDEO) or [`MODEL_3D`](https://shopify.dev/docs/api/admin-graphql/latest/enums/StagedUploadTargetGenerateUploadResource#enums-MODEL_3D) resources. *** After creating staged upload targets, complete the process by: 1. **Uploading files**: Send your files to the returned [`url`](https://shopify.dev/docs/api/admin-graphql/latest/objects/StagedMediaUploadTarget#field-StagedMediaUploadTarget.fields.url) using the provided [`parameters`](https://shopify.dev/docs/api/admin-graphql/latest/objects/StagedMediaUploadTarget#field-StagedMediaUploadTarget.fields.parameters) for authentication 2. **Creating file assets**: Use the [`resourceUrl`](https://shopify.dev/docs/api/admin-graphql/latest/objects/StagedMediaUploadTarget#field-StagedMediaUploadTarget.fields.resourceUrl) as the `originalSource` in mutations such as: * [`fileCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fileCreate): Creates file assets from staged uploads * [`productUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productUpdate): Updates products with new media from staged uploads Learn more about [uploading media to Shopify](https://shopify.dev/apps/online-store/media/products). * [storefront​Access​Token​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/storefrontAccessTokenCreate) mutation Creates a storefront access token that delegates unauthenticated access scopes to clients using the [Storefront API](https://shopify.dev/docs/api/storefront). The token provides public access to storefront resources without requiring customer authentication. Each shop can have up to 100 active [`StorefrontAccessToken`](https://shopify.dev/docs/api/admin-graphql/latest/objects/StorefrontAccessToken) objects. Headless storefronts, mobile apps, and other client applications typically use these tokens to access public storefront data. Learn more about [building with the Storefront API](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/getting-started). * [storefront​Access​Token​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/storefrontAccessTokenDelete) mutation Deletes a storefront access token. * [tags​Add](https://shopify.dev/docs/api/admin-graphql/latest/mutations/tagsAdd) mutation Add tags to an order, a draft order, a customer, a product, or an online store article. * [tags​Remove](https://shopify.dev/docs/api/admin-graphql/latest/mutations/tagsRemove) mutation Remove tags from an order, a draft order, a customer, a product, or an online store article. * [url​Redirect​Bulk​Delete​All](https://shopify.dev/docs/api/admin-graphql/latest/mutations/urlRedirectBulkDeleteAll) mutation Asynchronously delete [URL redirects](https://shopify.dev/api/admin-graphql/latest/objects/UrlRedirect) in bulk. * [webhook​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/webhookSubscriptionCreate) mutation Creates a webhook subscription that notifies your [`App`](https://shopify.dev/docs/api/admin-graphql/latest/objects/App) when specific events occur in a shop. Webhooks push event data to your endpoint immediately when changes happen, eliminating the need for polling. The subscription configuration supports multiple endpoint types including HTTPS URLs, Google Pub/Sub topics, and AWS EventBridge event sources. You can filter events using [Shopify API search syntax](https://shopify.dev/docs/api/usage/search-syntax) to receive only relevant webhooks, control which data fields are included in webhook payloads, and specify metafield namespaces to include. *** Note The Webhooks API version [configured in your app](https://shopify.dev/docs/apps/build/webhooks/subscribe/use-newer-api-version) determines the API version for webhook events. You can't specify it per subscription. *** Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your `shopify.app.toml` may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read [About managing webhook subscriptions](https://shopify.dev/docs/apps/build/webhooks/subscribe). * [webhook​Subscription​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/webhookSubscriptionDelete) mutation Deletes a [`WebhookSubscription`](https://shopify.dev/docs/api/admin-graphql/latest/objects/WebhookSubscription) and stops all future webhooks to its endpoint. Returns the deleted subscription's ID for confirmation. Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your `shopify.app.toml` may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read [About managing webhook subscriptions](https://shopify.dev/docs/apps/build/webhooks/subscribe). * [webhook​Subscription​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/webhookSubscriptionUpdate) mutation Updates a webhook subscription's configuration. Modify the endpoint URL, event filters, included fields, or metafield namespaces without recreating the subscription. The mutation accepts a [`WebhookSubscriptionInput`](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/WebhookSubscriptionInput) that specifies the new configuration. You can switch between endpoint types (HTTP, Pub/Sub, EventBridge) by providing a different URI format. Updates apply atomically without interrupting webhook delivery. Building an app? If you only use app-specific webhooks, you won't need this. App-specific webhook subscriptions specified in your `shopify.app.toml` may be easier. They are automatically kept up to date by Shopify & require less maintenance. Please read [About managing webhook subscriptions](https://shopify.dev/docs/apps/build/webhooks/subscribe). ### Deprecated mutations * [collection​Publish](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionPublish) mutation Deprecated * [collection​Unpublish](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionUnpublish) mutation Deprecated * [event​Bridge​Webhook​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/eventBridgeWebhookSubscriptionCreate) mutation Deprecated * [event​Bridge​Webhook​Subscription​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/eventBridgeWebhookSubscriptionUpdate) mutation Deprecated * [fulfillment​Create​V2](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentCreateV2) mutation Deprecated * [fulfillment​Tracking​Info​Update​V2](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentTrackingInfoUpdateV2) mutation Deprecated * [order​Edit​Remove​Line​Item​Discount](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderEditRemoveLineItemDiscount) mutation Deprecated * [product​Create​Media](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productCreateMedia) mutation Deprecated * [product​Delete​Media](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productDeleteMedia) mutation Deprecated * [product​Publish](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productPublish) mutation Deprecated * [product​Unpublish](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productUnpublish) mutation Deprecated * [product​Update​Media](https://shopify.dev/docs/api/admin-graphql/latest/mutations/productUpdateMedia) mutation Deprecated * [staged​Upload​Target​Generate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/stagedUploadTargetGenerate) mutation Deprecated * [staged​Upload​Targets​Generate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/stagedUploadTargetsGenerate) mutation Deprecated *** ## <\~> UserError Mutations ### Mutated by * <\~>[app​Purchase​One​Time​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appPurchaseOneTimeCreate) * <\~>[app​Subscription​Cancel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCancel) * <\~>[app​Subscription​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionCreate) * <\~>[app​Subscription​Line​Item​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appSubscriptionLineItemUpdate) * <\~>[app​Usage​Record​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appUsageRecordCreate) * <\~>[bulk​Operation​Cancel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/bulkOperationCancel) * <\~>[collection​Add​Products](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionAddProducts) * <\~>[collection​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionCreate) * <\~>[collection​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionDelete) * <\~>[collection​Remove​Products](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionRemoveProducts) * <\~>[collection​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/collectionUpdate) * <\~>[customer​Add​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerAddTaxExemptions) * <\~>[customer​Address​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerAddressCreate) * <\~>[customer​Address​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerAddressDelete) * <\~>[customer​Address​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerAddressUpdate) * <\~>[customer​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerCreate) * <\~>[customer​Delete](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerDelete) * <\~>[customer​Generate​Account​Activation​Url](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerGenerateAccountActivationUrl) * <\~>[customer​Payment​Method​Credit​Card​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerPaymentMethodCreditCardCreate) * <\~>[customer​Payment​Method​Credit​Card​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerPaymentMethodCreditCardUpdate) * <\~>[customer​Payment​Method​Revoke](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerPaymentMethodRevoke) * <\~>[customer​Payment​Method​Send​Update​Email](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerPaymentMethodSendUpdateEmail) * <\~>[customer​Remove​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerRemoveTaxExemptions) * <\~>[customer​Replace​Tax​Exemptions](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerReplaceTaxExemptions) * <\~>[customer​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerUpdate) * <\~>[customer​Update​Default​Address](https://shopify.dev/docs/api/admin-graphql/latest/mutations/customerUpdateDefaultAddress) * <\~>[delivery​Profile​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryProfileCreate) * <\~>[delivery​Profile​Remove](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryProfileRemove) * <\~>[delivery​Profile​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryProfileUpdate) * <\~>[delivery​Promise​Participants​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/deliveryPromiseParticipantsUpdate) *** ## Interfaces * [Displayable​Error](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/DisplayableError) interface *** ## ||-UserError Implements ### Implements * ||-[Displayable​Error](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/DisplayableError)