Product variants expanded to 2048, bulk ops added, groupObjects removed

10/29/2025, 12:00:55 AM

New topโ€‘level queries bulkOperation and bulkOperations allow retrieving individual and paginated bulk operations, with BulkOperationConnection and BulkOperationEdge types added. The bulkOperationRunMutation mutation no longer accepts the groupObjects argument. The bulkOperationRunQuery mutation now defaults groupObjects to false and its description reflects that grouping is optional and slower. Product configuration mutations (productOptionsCreate, productSet, productVariantsBulkCreate, productVariantsBulkUpdate) and the Product.variants field now support up to 2048 variants per product instead of the former 100. The BillingAttemptUserErrorCode enum now includes THROTTLED. The FulfillmentService.permitsSkuSharing field is deprecated and should not be set to false. New error codes COMPARE_QUANTITY_STALE and MarketsSortKeys.STATUS were added.

Query Changes

โž• Added Queries (2)

bulkOperation

Returns a specific bulk operation by ID.

bulkOperations

Returns the app's bulk operations meeting the specified filters.

Mutation Changes

๐Ÿ”„ Modified Mutations (6)

bulkOperationRunMutation

Creates and runs a bulk operation mutation.

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

- Removed argument: groupObjects
bulkOperationRunQuery

Creates and runs a bulk operation query.

See the bulk operations guide for more details.

~ Modified argument: groupObjects
productOptionsCreate

Creates one or more options
on a product,
such as size, color, or material. Each option includes a name, position, and a list of values. The combination
of a product option and value creates a product variant.

Use the productOptionsCreate mutation for the following use cases:

  • Add product choices: Add a new option, like "Size" (Small, Medium, Large) or
    "Color" (Red, Blue, Green), to an existing product so customers can select their preferred variant.
  • Enable personalization features: Add options such as "Engraving text" to let customers customize their purchase.
  • Offer seasonal or limited edition products: Add a new value
    (for example, "Holiday red") to an existing option to support limited-time or seasonal variants.
  • Integrate with apps that manage product configuration: Allow third-party apps to add options, like
    "Bundle size", when customers select or customize
    product bundles.
  • Link options to metafields: Associate a product option with a custom
    metafield, like "Fabric code", for
    richer integrations with other systems or apps.

Note:
The productOptionsCreate mutation enforces strict data integrity for product options and variants.
All option positions must be sequential, and every option should be used by at least one variant.
If you use the CREATE variant strategy, consider the maximum allowed number of variants for each product is 2048.

After you create product options, you can further manage a product's configuration using related mutations:

Learn more about the product model
and adding product data.

productSet

Performs multiple operations to create or update products in a single request.

Use the productSet mutation to sync information from an external data source into Shopify, manage large
product catalogs, and perform batch updates. The mutation is helpful for bulk product management, including price
adjustments, inventory updates, and product lifecycle management.

The behavior of productSet depends on the type of field it's modifying:

  • For list fields: Creates new entries, updates existing entries, and deletes existing entries
    that aren't included in the mutation's input. Common examples of list fields include
    collections,
    metafields,
    and variants.

  • For all other field types: Updates only the included fields. Any omitted fields will remain unchanged.

Note:
By default, stores have a limit of 2048 product variants for each product.

You can run productSet in one of the following modes:

  • Synchronously: Returns the updated product in the response.
  • Asynchronously: Returns a ProductSetOperation object.
    Use the productOperation query to check the status of the operation and
    retrieve details of the updated product and its product variants.

If you need to only manage product variants, then use one of the following mutations:

If you need to only manage product options, then use one of the following mutations:

Learn more about syncing product data from an external source.

productVariantsBulkCreate

Creates multiple product variants
for a single product in one operation.
You can run this mutation directly or as part of a bulk operation
for large-scale catalog updates.

Use the productVariantsBulkCreate mutation to efficiently add new product variantsโ€”such as different sizes,
colors, or materialsโ€”to an existing product. The mutation is helpful if you need to add product variants in bulk,
such as importing from an external system.

The mutation supports:

  • Creating variants with custom option values
  • Associating media (for example, images, videos, and 3D models) with the product or its variants
  • Handling complex product configurations

Note:
By default, stores have a limit of 2048 product variants for each product.

After creating variants, you can make additional changes using one of the following mutations:

  • productVariantsBulkUpdate:
    Updates multiple product variants for a single product in one operation.
  • productSet:
    Used to perform multiple operations on products, such as creating or modifying product options and variants.

You can also specifically manage product options through related mutations:

Learn more about the product model
and adding product data.

productVariantsBulkUpdate

Updates multiple product variants
for a single product in one operation.
You can run this mutation directly or as part of a bulk operation
for large-scale catalog updates.

Use the productVariantsBulkUpdate mutation to efficiently modify product variantsโ€”such as different sizes,
colors, or materialsโ€”associated with an existing product. The mutation is helpful if you need to update a
product's variants in bulk, such as importing from an external system.

The mutation supports:

  • Updating variants with custom option values
  • Associating media (for example, images, videos, and 3D models) with the product or its variants
  • Handling complex product configurations

Note:
By default, stores have a limit of 2048 product variants for each product.

After creating variants, you can make additional changes using the
productSet mutation,
which is used to perform multiple operations on products, such as creating or modifying product options and variants.

You can also specifically manage product options through related mutations:

Learn more about the product model
and adding product data.

Type Changes

โž• Added Types (3)

๐Ÿ—๏ธBulkOperationConnectionโž• AddedOBJECT

An auto-generated type for paginating through multiple BulkOperations.

Fields: edges, nodes, pageInfo
๐Ÿ—๏ธBulkOperationEdgeโž• AddedOBJECT

An auto-generated type which holds one BulkOperation and a cursor during pagination.

Fields: cursor, node
๐Ÿ“‹BulkOperationsSortKeysโž• AddedENUM

The set of valid sort keys for the BulkOperations query.

Values: COMPLETED_AT, CREATED_AT, STATUS

๐Ÿ”„ Modified Types (6)

๐Ÿ—๏ธBillingAttemptUserErrorCode๐Ÿ”„ Modified
โž• Enum value added: THROTTLED
๐Ÿ—๏ธFulfillmentService๐Ÿ”„ Modified
๐Ÿ”„ Field modified: permitsSkuSharing
๐Ÿ—๏ธInventorySetOnHandQuantitiesUserErrorCode๐Ÿ”„ Modified
โž• Enum value added: COMPARE_QUANTITY_STALE
๐Ÿ—๏ธMarketsSortKeys๐Ÿ”„ Modified
โž• Enum value added: STATUS
๐Ÿ—๏ธProduct๐Ÿ”„ Modified
๐Ÿ”„ Field modified: variants
๐Ÿ—๏ธShopPlan๐Ÿ”„ Modified
๐Ÿ”„ Field modified: publicDisplayName