User Error
Represents an error in the input of a mutation.
Anchor to FieldsFields
- Anchor to fieldfield•[String!]
The path to the input field that caused the error.
- Anchor to messagemessage•String!non-null
The error message.
Anchor to MutationsMutations
- •mutation
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
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.
- •mutation
Cancels an active app subscription, stopping future billing cycles. The cancellation behavior depends on the
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
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
setting and the app's specific implementation of subscription management.
For subscription lifecycle management and cancellation best practices, consult the subscription management guide.
- •mutation
Allows an app to charge a store for features or services on a recurring basis.
- •mutation
Updates the capped amount on the usage pricing plan of an app subscription line item.
- •mutation
Enables an app to charge a store for features or services on a per-use basis. The usage charge value is counted towards the
limit that was specified in the
field when the app subscription was created. If you create an app usage charge that causes the total usage charges in a billing interval to exceed the capped amount, then a
Total price exceeds balance remaining
error is returned.- •mutation
Starts the cancelation process of a running bulk operation.
There may be a short delay from when a cancelation starts until the operation is actually canceled.
- •mutation
Adds 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
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.
- •mutation
Creates a collection to group products together in the online store and other sales channels. For example, an athletics store might create different collections for running attire, shoes, and accessories.
There are two types of collections:
- Custom (manual) collections: You specify the products to include in a collection.
- Smart (automated) collections: You define rules, and products matching those rules are automatically included in the collection.
Use the
mutation when you need to:
- Create a new collection for a product launch or campaign
- Organize products by category, season, or promotion
- Automate product grouping using rules (for example, by tag, type, or price)
NoteLearn more about using metafields with smart collections.
- •mutation
Deletes a collection 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
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.
- •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
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.
- •mutation
Asynchronously reorders products within a specified collection. Instead of returning an updated collection, this mutation returns a job, which should be polled. The
must be
.
How to use this mutation:
- Provide only the products that actually moved in the
moves
list; do not send the entire product list. For example: to move the product at index 1 to index N, send a single move for that product with.
- Each move is applied sequentially in the order provided.
is a zero-based index within the collection at the moment the move is applied (after any prior moves in the list).
- Products not included in
moves
keep their relative order, aside from any displacement caused by the moves. - If
is greater than or equal to the number of products, the product is placed at the end.
Example:
- Initial order: [A, B, C, D, E] (indices 0..4)
- Moves (applied in order):
- E -> newPosition: 1
- C -> newPosition: 4
- Result: [A, E, B, D, C]
Displaced products will have their position altered in a consistent manner with no gaps.
- Provide only the products that actually moved in the
- •mutation
Updates a collection, modifying its properties, products, or publication settings. Collections help organize products together in the online store and other sales channels.
Use the
mutation to programmatically modify collections in scenarios such as:
- Updating collection details, like title, description, or image
- Modifying SEO metadata for better search visibility
- Changing which products are included (using rule updates for smart collections)
- Publishing or unpublishing collections across different sales channels
- Updating custom data using metafields
There are two types of collections with different update capabilities:
- Custom (manual) collections: You can update collection properties, but rule sets can't be modified since products are manually selected.
- Smart (automated) collections: You can update both collection properties and the rules that automatically determine which products are included.
When updating rule sets for smart collections, the operation might be processed asynchronously. In these cases, the mutation returns a
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
and
mutations.
Learn more about using metafields with smart collections.
- •mutation
Create a new customer address.
- •mutation
Deletes a customer's address.
- •mutation
Update a customer's address information.
- •mutation
Add tax exemptions for the customer.
- •mutation
Create a new customer. As of API version 2022-10, apps using protected customer data must meet the protected customer data requirements.
- •mutation
Delete a customer. As of API version 2022-10, apps using protected customer data must meet the protected customer data requirements.
- •mutation
Generate an account activation URL for a customer.
- •mutation
Creates a credit card payment method for a customer using a session id. These values are only obtained through card imports happening from a PCI compliant environment. Please use customerPaymentMethodRemoteCreate if you are not managing credit cards directly.
- •mutation
Updates the credit card payment method for a customer.
- •mutation
Revokes a customer's payment method.
- •mutation
Sends a link to the customer so they can update a specific payment method.
- •mutation
Remove tax exemptions from a customer.