Add Batch Queries and Mutations with Enhanced Collection Filters

11/20/2026, 12:00:57 AM

  1. Added root queries batch, batchWorkflow, batches, eventSubscription, fulfillmentOrderBatches, mainMenu and mainNavigationMenu to retrieve single entities, lists, event subscriptions, and navigation data. 2. Introduced a suite of batch mutations – create, add items (by ID or name), move, remove, transfer, close, reopen, assign staff, and delete – expanding developer control over batch workflows. 3. The collections and collectionsCount queries now accept a created_at filter in the search syntax and the query description was updated accordingly. 4. The collectionReorderProducts mutation was rewritten: its description now emphasizes zero‑based positions, the moves argument description was clarified, and a new operation input type allows declarative reordering (up to 1,000 products). 5. The new operation input supports toPosition and toIndexes for bulk block moves, and the moves argument now explicitly requires that either moves or operation be supplied. 6. Related type definitions (Batch, BatchConnection, BatchWorkflow, etc.) have been added, along with new enum values for rejection reasons and batch status.

Query Changes

➕ Added Queries (7)

batch

Returns a batch for the shop.

batchWorkflow

Returns a batch workflow for the shop.

batches

Returns a paginated list of batches for the shop.

eventSubscription

Returns the event subscription that the authenticated app set on the shop with eventSubscriptionsSet,
matched by handle, or null when the app set none with that handle. A subscription the app's
configuration declares is not set on the shop and isn't returned here.

fulfillmentOrderBatches

Returns a paginated list of non-closed batches that can be filtered by fulfillment order attributes.

mainMenu

Returns the Menu that the shop's published theme uses as its main navigation menu, with its nested menu items.

The menu is the one the merchant selected for the main menu setting of the theme's header section. Returns null when the shop has no published theme, when the theme's header section doesn't have exactly one main menu setting, when the theme doesn't store a menu for that setting, or when no menu has the selected handle.

Each item's url is the link as the merchant saved it, so links to the shop's own resources, such as products and collections, are relative paths.

mainNavigationMenu

Returns the main navigation menu for the shop.

🔄 Modified Queries (2)

collections

Retrieves a list of collections
in a store. Collections are groups of products
that merchants can organize for display in their online store and
other sales channels.
For example, an athletics store might create different collections for running attire, shoes, and accessories.

Use the collections query when you need to:

  • Build a browsing interface for a store's product groupings.
  • Create collection searching, sorting, and filtering experiences (for example, by title, type, or published status).
  • Sync collection data with external systems.

The collections query supports pagination
for large catalogs and saved searches
for frequently used collection queries.

The collections query returns collections with their associated metadata, including:

  • Basic collection information (title, description, handle, and type)
  • Collection image and SEO metadata
  • Product count and product relationships
  • Collection rules or conditions
  • Publishing status and publication details
  • Metafields and custom attributes

Learn more about using metafields with collection conditions.

~ Modified argument: query
collectionsCount

Count of collections. Limited to a maximum of 10000 by default.

~ Modified argument: query

Mutation Changes

➕ Added Mutations (11)

batchAddItems

Adds items to the first step of an existing batch.

Supports an optional idempotency key using the @idempotent directive. For more information, see the idempotency documentation.

batchAddItemsByName

Adds items to the most recent open or in-progress batch with the given name. An item goes to a different batch with the same name when that batch is full or when the batch workflow's steps don't allow the item in that batch alongside the items it already has. A full batch's overflow goes to a new batch with the same name, never an older one. Concurrent requests with the same name don't create duplicate batches.

Supports an optional idempotency key using the @idempotent directive. For more information, see the idempotency documentation.

batchClose

Closes a batch. Every item must be in the batch workflow's Done step. An empty batch can be closed at any time. Closing a batch cancels any actions that are still running.

batchCreate

Creates a batch.

batchDelete

Deletes a batch.

batchMoveItems

Moves items between steps within a batch.
Supports an optional idempotency key using the @idempotent directive. Retrying with the same key returns the original move outcome without moving items again.

batchRemoveItems

Removes items from a batch.

batchReopen

Reopens a closed batch.

batchStepAssign

Assigns a staff member to a batch step. Pass a null staffMemberId to unassign.

batchTransferItems

Transfers items from one batch to another. Items land in the target batch's first step.

batchUpdate

Updates a batch.

🔄 Modified Mutations (1)

collectionReorderProducts

Asynchronously reorders the products of a manually sorted collection. Instead of returning an updated collection, this mutation returns a job, which should be polled. The Collection.sortOrder must be MANUAL.

Positions are zero-based indexes in the collection's list of products. Products that the request doesn't list keep their relative order, and the reorder leaves no gaps. The description of each argument that reorders products says how it places them.

~ Modified argument: moves
+ New argument: operation

Type Changes

➕ Added Types (81)

🏗️Batch➕ AddedOBJECT

A group of items being processed through a batch workflow.

Fields: createdAt, currentStep, events, hasTimelineComment, id ... +6 more
🏗️BatchAddItemsByNamePayload➕ AddedOBJECT

Return type for batchAddItemsByName mutation.

Fields: batchItemRejections, batches, createdBatches, userErrors
🏗️BatchAddItemsByNameUserError➕ AddedOBJECT

An error that occurs during the execution of BatchAddItemsByName.

Fields: code, field, message
📋BatchAddItemsByNameUserErrorCode➕ AddedENUM

Possible error codes that can be returned by BatchAddItemsByNameUserError.

Values: BLANK, TOO_LONG, WORKFLOW_NOT_FOUND, ITEMS_NOT_FOUND, NO_ITEMS, SERVICE_UNAVAILABLE, IDEMPOTENCY_CONCURRENT_REQUEST, IDEMPOTENCY_KEY_PARAMETER_MISMATCH ... +1 more
🏗️BatchAddItemsPayload➕ AddedOBJECT

Return type for batchAddItems mutation.

Fields: addedItems, batch, batchItemRejections, userErrors
🏗️BatchAddItemsUserError➕ AddedOBJECT

An error that occurs during the execution of BatchAddItems.

Fields: code, field, message
📋BatchAddItemsUserErrorCode➕ AddedENUM

Possible error codes that can be returned by BatchAddItemsUserError.

Values: BATCH_NOT_FOUND, BATCH_CLOSED, ITEMS_NOT_FOUND, NO_ITEMS, IDEMPOTENCY_CONCURRENT_REQUEST, IDEMPOTENCY_KEY_PARAMETER_MISMATCH, IDEMPOTENCY_SYSTEM_ERROR
🏗️BatchClosePayload➕ AddedOBJECT

Return type for batchClose mutation.

Fields: batch, userErrors
🏗️BatchCloseUserError➕ AddedOBJECT

An error that occurs during the execution of BatchClose.

Fields: code, field, message
📋BatchCloseUserErrorCode➕ AddedENUM

Possible error codes that can be returned by BatchCloseUserError.

Values: BATCH_NOT_FOUND, ITEMS_NOT_IN_DONE_STEP
🏗️BatchConnection➕ AddedOBJECT

An auto-generated type for paginating through multiple Batches.

Fields: edges, nodes, pageInfo
🏗️BatchCreatePayload➕ AddedOBJECT

Return type for batchCreate mutation.

Fields: batch, batchItemRejections, userErrors
🏗️BatchCreateUserError➕ AddedOBJECT

An error that occurs during the execution of BatchCreate.

Fields: code, field, message
📋BatchCreateUserErrorCode➕ AddedENUM

Possible error codes that can be returned by BatchCreateUserError.

Values: WORKFLOW_NOT_FOUND, ITEMS_NOT_FOUND, NO_ITEMS, SERVICE_UNAVAILABLE, BLANK, TOO_LONG
🏗️BatchDeletePayload➕ AddedOBJECT

Return type for batchDelete mutation.

Fields: deletedBatchId, userErrors
🏗️BatchDeleteUserError➕ AddedOBJECT

An error that occurs during the execution of BatchDelete.

Fields: code, field, message
📋BatchDeleteUserErrorCode➕ AddedENUM

Possible error codes that can be returned by BatchDeleteUserError.

Values: BATCH_NOT_FOUND
🏗️BatchEdge➕ AddedOBJECT

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

Fields: cursor, node
🏗️BatchItemRejection➕ AddedOBJECT

A group of items rejected from a batch for the same reason.

Fields: actionDetails, count, items, message, reason ... +1 more
🏗️BatchItemRejectionDetail➕ AddedOBJECT

A finer-grained batch item rejection detail produced by a batch workflow step action.

Fields: code, count, items, message
📋BatchItemRejectionReason➕ AddedENUM

The reason an item was rejected from a batch operation.

Values: ALREADY_BATCHED, BATCH_LIMIT_REACHED, NOT_IN_BATCH, UNSUPPORTED_TYPE, NOT_ELIGIBLE, NOT_ADDABLE_FOR_ACTION, NOT_IN_STEP, UNKNOWN_ACTION
🏗️BatchMoveItemsPayload➕ AddedOBJECT

Return type for batchMoveItems mutation.

Fields: batch, batchItemRejections, movedItems, userErrors
🏗️BatchMoveItemsUserError➕ AddedOBJECT

An error that occurs during the execution of BatchMoveItems.

Fields: code, field, message
📋BatchMoveItemsUserErrorCode➕ AddedENUM

Possible error codes that can be returned by BatchMoveItemsUserError.

Values: BATCH_NOT_FOUND, BATCH_CLOSED, ITEMS_NOT_FOUND, NO_ITEMS, BATCH_STEP_NOT_FOUND, NO_STEP_IN_DIRECTION, CONCURRENT_MODIFICATION, INVALID ... +3 more
🏗️BatchRemoveItemsPayload➕ AddedOBJECT

Return type for batchRemoveItems mutation.

Fields: batch, removedItems, userErrors
📥BatchRemoveItemsTargetInput➕ AddedINPUT_OBJECT

Specifies what to remove from a batch. Provide exactly one of stepId (bulk-remove all items currently in the step) or itemIds (remove specific items regardless of which step they belong to).

🏗️BatchRemoveItemsUserError➕ AddedOBJECT

An error that occurs during the execution of BatchRemoveItems.

Fields: code, field, message
📋BatchRemoveItemsUserErrorCode➕ AddedENUM

Possible error codes that can be returned by BatchRemoveItemsUserError.

Values: BATCH_NOT_FOUND, BATCH_CLOSED, INVALID_TARGET, ITEMS_NOT_FOUND, NO_ITEMS, BATCH_STEP_NOT_FOUND
🏗️BatchReopenPayload➕ AddedOBJECT

Return type for batchReopen mutation.

Fields: batch, userErrors
🏗️BatchReopenUserError➕ AddedOBJECT

An error that occurs during the execution of BatchReopen.

Fields: code, field, message
📋BatchReopenUserErrorCode➕ AddedENUM

Possible error codes that can be returned by BatchReopenUserError.

Values: BATCH_NOT_FOUND
📋BatchSortKeys➕ AddedENUM

The set of valid sort keys for the Batch query.

Values: CREATED_AT, ID, UPDATED_AT
📋BatchStatus➕ AddedENUM

A batch's current status.

Values: OPEN, IN_PROGRESS, CLOSED
🏗️BatchStep➕ AddedOBJECT

A step within a batch, representing a stage of processing.

Fields: actionReadiness, actions, assignedStaff, events, id ... +4 more
🏗️BatchStepAction➕ AddedOBJECT

A single execution of a batch workflow action within a batch step.

Fields: id, isCompletedForCurrentItems, items, resources, status ... +1 more
🏗️BatchStepActionConnection➕ AddedOBJECT

An auto-generated type for paginating through multiple BatchStepActions.

Fields: edges, nodes, pageInfo
🏗️BatchStepActionEdge➕ AddedOBJECT

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

Fields: cursor, node
🏗️BatchStepActionItem➕ AddedOBJECT

The result of a specific item within a batch step action execution.

Fields: batchableItem, errorMessage, id, outcome, resources ... +1 more
🏗️BatchStepActionItemConnection➕ AddedOBJECT

An auto-generated type for paginating through multiple BatchStepActionItems.

Fields: edges, nodes, pageInfo
🏗️BatchStepActionItemEdge➕ AddedOBJECT

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

Fields: cursor, node
📋BatchStepActionItemStatus➕ AddedENUM

The status of an individual item within a batch step action execution.

Values: PENDING, COMPLETED, FAILED, SKIPPED
🏗️BatchStepActionReadiness➕ AddedOBJECT

A batch workflow step action's readiness for the current items in a batch step.

Fields: executable, rejections, workflowStepAction
📋BatchStepActionStatus➕ AddedENUM

The status of a batch step action execution.

Values: EXECUTING, COMPLETED, CANCELLED, FAILED
🏗️BatchStepAssignPayload➕ AddedOBJECT

Return type for batchStepAssign mutation.

Fields: batchStep, userErrors
🏗️BatchStepAssignUserError➕ AddedOBJECT

An error that occurs during the execution of BatchStepAssign.

Fields: code, field, message
📋BatchStepAssignUserErrorCode➕ AddedENUM

Possible error codes that can be returned by BatchStepAssignUserError.

Values: BATCH_STEP_NOT_FOUND, BATCH_CLOSED, STAFF_MEMBER_NOT_FOUND
🏗️BatchStepConnection➕ AddedOBJECT

An auto-generated type for paginating through multiple BatchSteps.

Fields: edges, nodes, pageInfo
🏗️BatchStepDocument➕ AddedOBJECT

A generated document produced by a successful batch step action.

Fields: assetUrl, documentKey, id
🏗️BatchStepEdge➕ AddedOBJECT

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

Fields: cursor, node
📋BatchStepMoveDirection➕ AddedENUM

The direction to move items between batch steps.

Values: NEXT, PREVIOUS
🏗️BatchStepResource➕ AddedOBJECT

A resource produced by a batch step action, with metadata about its kind and associated item.

Fields: batchItem, id, kind, resourceNode
🏗️BatchStepResourceConnection➕ AddedOBJECT

An auto-generated type for paginating through multiple BatchStepResources.

Fields: edges, nodes, pageInfo
🏗️BatchStepResourceEdge➕ AddedOBJECT

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

Fields: cursor, node
🔀BatchStepResourceType➕ AddedUNION

A union of underlying resource types produced by batch step actions.

🏗️BatchTransferItemsPayload➕ AddedOBJECT

Return type for batchTransferItems mutation.

Fields: batchItemRejections, sourceBatch, targetBatch, userErrors
🏗️BatchTransferItemsUserError➕ AddedOBJECT

An error that occurs during the execution of BatchTransferItems.

Fields: code, field, message
📋BatchTransferItemsUserErrorCode➕ AddedENUM

Possible error codes that can be returned by BatchTransferItemsUserError.

Values: BATCH_NOT_FOUND, BATCH_CLOSED, SAME_BATCH, ITEMS_NOT_FOUND, NO_ITEMS, BATCH_STEP_NOT_FOUND
🏗️BatchUpdatePayload➕ AddedOBJECT

Return type for batchUpdate mutation.

Fields: batch, userErrors
🏗️BatchUpdateUserError➕ AddedOBJECT

An error that occurs during the execution of BatchUpdate.

Fields: code, field, message
📋BatchUpdateUserErrorCode➕ AddedENUM

Possible error codes that can be returned by BatchUpdateUserError.

Values: BATCH_NOT_FOUND, BLANK, TOO_LONG
🏗️BatchWorkflow➕ AddedOBJECT

A batch workflow. Its configurations define the steps and actions that batches go through.

Fields: currentConfiguration, id, updatedAt
🏗️BatchWorkflowAction➕ AddedOBJECT

An action that can run on the items in a batch workflow step.

Fields: description, handle, id, name
🏗️BatchWorkflowConfiguration➕ AddedOBJECT

A versioned configuration of a batch workflow, defining steps and actions for processing batches.

Fields: current, id, steps, version, workflow
🏗️BatchWorkflowStep➕ AddedOBJECT

A step in a batch workflow configuration.

Fields: actions, displayName, id, key, position
🏗️BatchWorkflowStepAction➕ AddedOBJECT

An action configuration for a batch workflow step.

Fields: action, displayName, id, position
🏗️BatchWorkflowStepActionConnection➕ AddedOBJECT

An auto-generated type for paginating through multiple BatchWorkflowStepActions.

Fields: edges, nodes, pageInfo
🏗️BatchWorkflowStepActionEdge➕ AddedOBJECT

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

Fields: cursor, node
🏗️BatchWorkflowStepConnection➕ AddedOBJECT

An auto-generated type for paginating through multiple BatchWorkflowSteps.

Fields: edges, nodes, pageInfo
🏗️BatchWorkflowStepEdge➕ AddedOBJECT

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

Fields: cursor, node
🔌Batchable➕ AddedINTERFACE

An entity that can be added to a batch.

Fields: id
🔀BatchableItem➕ AddedUNION

A union of types that can be added as items to a batch.

🏗️BatchableItemConnection➕ AddedOBJECT

An auto-generated type for paginating through multiple BatchableItems.

Fields: edges, nodes, pageInfo
🏗️BatchableItemEdge➕ AddedOBJECT

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

Fields: cursor, node
📋CollectionReorderEdge➕ AddedENUM

An end of a collection's product list, where toPosition can place a block of products.

Values: TOP, BOTTOM
📥CollectionReorderIndexedProductInput➕ AddedINPUT_OBJECT

The input fields for the final index of one product in the collection.

📥CollectionReorderOperationInput➕ AddedINPUT_OBJECT

The input fields for a declarative reorder: the request says where products end up, not how to move them
one at a time. Specify exactly one of toPosition or toIndexes.

The reorder is resolved against the collection's order when the job runs.

📥CollectionReorderTargetInput➕ AddedINPUT_OBJECT

The input fields for the place where toPosition puts its block of products. Specify exactly one.

📥CollectionReorderToPositionInput➕ AddedINPUT_OBJECT

The input fields for moving a block of products to one place in the collection.

The block keeps the order of productIds. Products that the request doesn't list keep their relative order
around the block. Products that aren't in the collection are skipped.

🏗️NavigationMenu➕ AddedOBJECT

The top level navigation menu for the shop.

Fields: id, items, title, translations
🏗️NavigationMenuItem➕ AddedOBJECT

A menu item to send in Admin GraphQL response.

Fields: id, items, resourceId, title, type ... +1 more
📋NavigationMenuItemType➕ AddedENUM

A menu item type.

Values: FRONTPAGE, COLLECTION, COLLECTIONS, PRODUCT, CATALOG, PAGE, BLOG, ARTICLE ... +5 more

🔄 Modified Types (6)

🏗️CollectionReorderProductsUserErrorCode🔄 Modified
➕ Enum value added: DUPLICATE_PRODUCT
➕ Enum value added: POSITION_COLLISION
➕ Enum value added: INVALID_POSITION
🏗️CollectionSortKeys🔄 Modified
➕ Enum value added: CREATED_AT
🏗️EventSubjectType🔄 Modified
➕ Enum value added: BATCH
➕ Enum value added: BATCH_STEP
🏗️Product🔄 Modified
🔄 Field modified: collections
🏗️Shop🔄 Modified
🔄 Field modified: collections
🏗️WebhookSubscriptionTopic🔄 Modified
➕ Enum value added: BATCH_ACTION_CREATED
➕ Enum value added: BATCH_ACTION_COMPLETED
➕ Enum value added: BATCH_CLOSED
➕ Enum value added: BATCH_CREATED
➕ Enum value added: BATCH_DELETED
➕ Enum value added: BATCH_ITEM_ADDED
➕ Enum value added: BATCH_ITEM_MOVED
➕ Enum value added: BATCH_ITEM_REMOVED
➕ Enum value added: BATCH_ITEM_TRANSFERRED
➕ Enum value added: BATCH_ITEM_VERIFIED
➕ Enum value added: BATCH_ITEM_UNVERIFIED
➕ Enum value added: BATCH_RENAMED
➕ Enum value added: BATCH_REOPENED
➕ Enum value added: BATCH_STEP_ASSIGNED
➕ Enum value added: BATCH_STEP_UNASSIGNED
➕ Enum value added: BATCH_WORKFLOW_CREATED
➕ Enum value added: BATCH_WORKFLOW_VERSION_PUBLISHED