Track changes across API versions with diffs, summaries, and details.
2/3/2026, 8:00:11 PM
Channel queries and mutations now use flattened argument names; the `collectionCreate` and `collectionUpdate` mutations no longer accept an `input` object, which means callers must now provide individual fields directly. Event filtering across many resource types has been updated to reference a one‑year retention window, with the `created_at` filter description amended accordingly in all Event connections and the `eventsCount` query. The `channelFullSync` mutation's `language` and `country` arguments have been clarified to perform a full sync for all languages or countries when omitted. The `inventorySetScheduledChanges` mutation has been marked deprecated and will be removed in a future release. New metafield capability types (`MetafieldCapabilityCartToOrderCopyable` and its input) were introduced and the `MetafieldCapabilities` type now exposes the `cartToOrderCopyable` field. Additional enum values were added to `CheckoutBrandingColorSchemeSelection` (COLOR_SCHEME5 and COLOR_SCHEME6) along with new scheme fields in `CheckoutBrandingColorSchemes`. Several new error code enum values (`INVENTORY_STATE_NOT_ACTIVE`, `ACTIVATION_FAILED`, `MISSING_COUNTRY_CODE`, `INVALID_COUNTRY_AND_PROVINCE_CONDITIONS`) were added to improve inventory, market, and transfer error handling. Subsequent document updates throughout object types (Article, Blog, Collection, Comment, Company, etc.) updated the details of the events field arguments, specifically the retention period of event data.
1/28/2026, 12:00:23 AM
Shopify now exposes the inventoryShipmentSetBarcode mutation, allowing clients to assign a unique barcode to an existing InventoryShipment by supplying its ID and a barcode string. The mutation returns an InventoryShipmentSetBarcodePayload containing the updated InventoryShipment (now with a new barcode field) and a list of user errors. New error codes include INVENTORYSHIPMENTSETBARCODEUSERERRORCODE.BARCODE_DUPLICATE and INVENTORYSHIPMENTSETBARCODEUSERERRORCODE.SHIPMENT_NOT_FOUND. The InventoryShipment type now includes a nullable String field called barcode, and the InventoryShipmentCreateUserErrorCode enum gains BARCODE_DUPLICATE. A new field remainingLineItemsWeight (type Weight) was added to FulfillmentOrder, representing the weight of unfulfilled line items. The OrderTransactionErrorCode enum omitted the INCORRECT_NAME value, and SubscriptionBillingAttemptErrorCode and SubscriptionBillingAttemptPaymentErrorCode enums received numerous new payment‑related codes reflecting detailed card decline and processing errors. Developers must update error handling for these new codes and consider setting or reading the barcode field in shipments, ensuring barcodes are unique across the system.
1/27/2026, 12:00:57 AM
The schema now exposes the **fulfillmentOrderReportProgress** mutation, allowing fulfillment services to mark an order as in‑progress or report progress, along with optional notes via the new *FulfillmentOrderReportProgressInput*. The mutation returns the updated *FulfillmentOrder* and a list of *FulfillmentOrderReportProgressUserError* objects, covering status and ownership validation errors. Two new *FulfillmentOrderAction* enum values—REPORT_PROGRESS and MARK_AS_IN_PROGRESS—enable finer‑grained action control. Webhook topics *FULFILLMENT_ORDERS_PROGRESS_REPORTED* and *FULFILLMENT_ORDERS_MANUALLY_REPORTED_PROGRESS_STOPPED* are added for real‑time progress notifications. A new enum **SubscriptionBillingAttemptPaymentProcessingPolicy** introduces two payment options, and the arguments *paymentProcessingPolicy* are added to both **subscriptionBillingCycleBulkCharge** and **subscriptionBillingCycleCharge** mutations for explicit payment‑handling behavior. Developers should update request payloads to include the new args where needed and handle the expanded error codes in their fulfillment logic.
1/24/2026, 12:00:55 AM
Shopify’s GraphQL API now supports a comprehensive delivery method rate system, introducing DeliveryRateGroup and associated connection/edge types to represent grouped rates. DeliveryMethodDefinition now exposes currencyCode, freeConditions, and a rateGroups list, while DeliveryRateDefinition gains conditions, maxTransitTime, and minTransitTime fields. New enumerations and connection types enable paginated access to delivery rate range conditions and weight/value rules. Subscription billing attempts have been refactored: legacy fields errorCode, errorMessage, nextActionUrl, order, processingError, and ready are deprecated in favor of a new non‑nullable state union that aggregates ActionRequiredState, FailedState, PendingState, and SuccessState. Associated error code enums (General, Inventory, Payment) and the InventoryShipmentCreateInTransitUserErrorCode now include SHIPMENT_NOT_FOUND. The OrderTransaction receiptJson description emphasizes that it is gateway‑specific, discouraging apps from relying on it for business logic.
1/23/2026, 12:00:58 AM
A new query, channelByHandle, lets apps retrieve a Channel by its unique handle. Four mutations—channelCreate, channelUpdate, channelDelete, and channelFullSync—provide full CRUD and full‑sync capabilities, each returning payloads with detailed userErrors and trace information. Pagination support is added for App.channels and AppCatalog.channels via a ChannelConnection type, enabling efficient listing of channel connections. Channel objects now expose accountId, accountName, specificationHandle, and a resourceFeedback link. Feedback types (AppFeedback and ProductResourceFeedback) now include a channel field. ProductFeed gets a required channelId field to associate feeds with channels. All new input objects (ChannelCreateInput, ChannelUpdateInput) require specificationHandle, accountId, and accountName, and support optional handle overrides and restoration flags. Developers should update their schemas to use the new fields and mutations for full channel lifecycle management.
1/22/2026, 12:00:57 AM
The hidden scalar type named "Scalar" was removed, so any field previously defined as Scalar must be updated. BillingPlanFeatureValue.value now returns a JSON type instead of a generic scalar, requiring callers to parse JSON. OrderTransactionErrorCode now includes the new PAYMENT_PROVIDER_ERROR enumeration value. ShopifyPaymentsTransactionType gained four new enum variants for non‑target revenue adjustment debit/credit and their reversals. StoreCreditAccount.transactions added an additional filter named remaining_amount for credit and debit transaction types. Developers should update their queries, mutation calls, and type handling to accommodate these changes and replace any deprecated Scalar references.
1/18/2026, 12:01:05 AM
The deliverySettings query and the DeliverySetting type and input have been removed, so the shop‑wide shipping configuration can no longer be retrieved or updated through the GraphQL API. The deliverySettingUpdate mutation now has no arguments, reflecting the removal of the DeliverySettingInput and simplifying the payload. BulkOperations now defaults to sorting by created_at with newest first, and this behavior is described in its updated description. ProductsCount queries (and Channel.productsCount) now accept an optional limit argument (default 10000) to bound the count returned. Metafield lookups on many objects, including AppInstallation, Article, Blog, Channel, Collection, Customer, and others, no longer default to the app‑reserved namespace; if namespace is omitted all namespaces are returned, which removes implicit filtering. Finally, deliveryShippingOriginAssign has been deprecated and will be removed in a future version as single‑origin shipping mode is retired.
12/17/2025, 12:00:49 AM
API changes: 0 queries added, 0 removed. 0 mutations added, 0 removed. 18 types affected.
12/9/2025, 12:00:48 AM
The API now includes a new `returnReasonDefinitions` query that returns the entire library of available return reason definitions, allowing clients to query by ID, handle, and paginate with sorting and filter options. Several core queries such as `abandonedCheckouts`, `app`, `appByHandle`, and `appByKey` have updated descriptions to clarify returned data and scope, improving understanding of installed apps, checkout states, and return reasons. The `currentAppInstallation` and `currentBulkOperation` descriptions have been refined to better explain their purpose, including permission checks and bulk operation status handling. Content‑related queries like `articles`, `blogs`, `carrierServices`, `channels`, and `markets` now include more descriptive summaries and filtering capabilities, enhancing discoverability of blogs, carrier services, and market configurations. Additional queries such as `giftCard`, `giftCards`, `deliveryProfile`, and `deliveryProfiles` have expanded descriptions detailing balance history, delivery zone data, and filtering mechanisms. Overall, the changes aim to clarify returned fields, improve pagination and filtering details, and provide guidance on related mutations and documentation links.
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.
10/17/2025, 12:00:54 AM
New allChannels query lists all active sales channels and supports pagination and reverse ordering. Description of appInstallation and appInstallations query now explicitly outlines usage for access scopes, subscriptions, billing, and installation state, including the availability of read_apps scope for custom and public apps. The automaticDiscount query continues to be deprecated but its description now clarifies that it returns a DiscountAutomatic union rather than an old generic resource. The customerSegmentMembersCount query now explains real‑time segment size calculations using provided criteria. Operators can now use more detailed filter syntax for customers, orders, and giftCards queries; giftCards’ default search now includes code matching; orders’ discount code filter now limits to the first code used. The mutation appRevokeAccessScopes has been rewritten to explain that it will remove specific permissions while keeping other app functionality and returns granular success or error information. WebhookSubscriptions’ description was expanded to detail the returned data, pagination, and how app‑scoped versus shop‑scoped subscriptions are distinguished.
9/18/2025, 7:38:39 AM
The updated schema now includes a new `menusCount` query to return the number of menus, with optional filtering and limit. The `cartTransformCreate` and `fulfillmentConstraintRuleCreate` mutations now use a `functionHandle` argument instead of `functionId`; the old argument has been removed, so calls must be updated accordingly. New enum values – such as `MISSING_FUNCTION_IDENTIFIER`, `MULTIPLE_FUNCTION_IDENTIFIERS`, and `LOCATION_REQUIRED` – have been added to several error enums to better indicate function or location issues. Several other enums have received new values, including `INVENTORY_QUANTITIES_LIMIT_EXCEEDED` for bulk variant mutations, `ON_FULFILLMENT` for selling plan triggers, and `ORDERS_LINK_REQUESTED` for webhook topics. The schema also introduces bank account payment instrument types (`BankAccount`, `BankAccountHolderType`, `BankAccountType`) to support detailed banking information. Additional fields are added: `DeliveryProfile.version` for version tracking, `Order.sharedCheckout` to flag orders created via shared checkouts, and the `handle` field on `Channel` is no longer deprecated. All query descriptions have been updated for clarity, but otherwise their behavior remains unchanged.
9/11/2025, 12:00:19 AM
The unstable schema adds a new query, shopifyqlQuery, that returns a ShopifyqlQueryResponse containing parseErrors and tabular tableData with detailed column metadata (ShopifyqlTableData, ShopifyqlTableDataColumn) and a new ColumnDataType enum covering many data kinds. The CompanyLocation type now exposes a paginated storeCreditAccounts field with filtering by currency_code and id. Typical error enums receive new values: InventoryShipmentRemoveItemsUserErrorCode gains LOCATION_NOT_ACTIVE, and ProductSetUserErrorCode gets INVENTORY_QUANTITIES_LIMIT_EXCEEDED and VARIANT_METAFIELDS_LIMIT_EXCEEDED. The ShopifyPaymentsPayoutSummary type is expanded with required MoneyV2 fields capitalRemittanceAmount and creditRemittanceAmount. The ShopifyPaymentsTransactionType enum has had four platform adjustment values removed. CartTransforms query and related mutations (create/delete) retain their original behavior but have updated verbose descriptions for clarity. No existing query or mutation is deprecated or removed, preserving backward compatibility while providing these new capabilities.
9/5/2025, 8:31:44 PM
Developers should note that metaobjects now expose an "adminFilterable" capability, with new types MetaobjectFieldCapabilityAdminFilterable and MetaobjectFieldDefinitionCapabilities added. CustomerPaymentMethod gains a paginated "mandates" field for payment mandates and the previous resourceId/resourceType fields are removed; the MandateResourceType enum changes, dropping CARD_ON_FILE and adding CREDENTIAL_ON_FILE. Images and MediaImage now include a "translations" field that supports locale and marketId filtering. The stagedUploadsCreate mutation’s description adds a 10 MB payload limit, and the metafieldsSet mutation also notes the same limit. Queries such as channel, domain, market, orders, and sellingPlanGroup have updated descriptions for clarity, though channel remains deprecated in favor of publication. Finally, new enum values (COLLECTION_NOT_FOUND, MANUALLY_SORTED_COLLECTION, INVALID_MOVE) appear in CollectionReorderProductsUserErrorCode, and PaymentTerms receives a new "canPayEarly" boolean field. These changes affect how your queries and mutations construct request payloads and handle responses in the latest unstable schema.
8/28/2025, 2:17:16 PM
The GraphQL API now features more detailed, developer‑facing descriptions across key fields. The deprecated `collectionByHandle` query’s description has been expanded to explain its use as a URL‑friendly getter and to clarify the recommendation to use `collectionByIdentifier`. `productResourceFeedback` has an enriched description that explains its role in guiding app‑specific product optimization, with concrete examples and use‑case scenarios. Query arguments on both `products` and `productsCount` have updated descriptions clarifying the list of possible operators and example usage, while retaining the same signature. New object types `MarketRegionProvince` and its nested `MarketRegionProvinceCountry` have been added for market‑region data. A new enum value `LOCATION_NOT_ACTIVE` is now available in `InventoryTransferSetItemsUserErrorCode`. The `Channel.productsCount` field has been re‑described as “ChannelProductsCount” to emphasize that it returns the count of published products for a particular channel, with a limited default cap of 10 000. Lastly, the `productParents` fields on both `Product` and `ProductVariant` have clearer descriptions of their relationship to constituent components or parent products.
8/23/2025, 12:01:09 AM
The mutation `marketCurrencySettingsUpdate` has been deprecated and will be removed in a future release; developers should now use `marketCreate` for creating a market and `marketUpdate` for updating its currency settings. A new error type `CollectionReorderProductsUserError` replaces the generic `UserError` in the `CollectionReorderProductsPayload`, providing a more specific error code `TOO_MANY_ATTEMPTS_TO_REORDER_PRODUCTS`. The `CustomerPaymentMethod` type now includes a `resourceId` and a `resourceType` (`MandateResourceType` enum) to represent the specific resource the payment method was created for (e.g., Order, Subscriptions). The `MandateResourceType` enum lists supported resource types: CARD_ON_FILE, CHECKOUT, DRAFT_ORDER, ORDER, and SUBSCRIPTIONS. The `MarketUserErrorCode` enum gains three new values – `PROVINCE_DOES_NOT_EXIST`, `MISSING_PROVINCE_CODE`, and `INVALID_PROVINCE_FORMAT` – to signal province‑related validation issues. The `SubscriptionBillingAttemptErrorCode` enum is extended with `PAYMENT_METHOD_NOT_SPECIFIED` to indicate missing payment methods during billing attempts. Existing queries remain unchanged, but developers should adjust mutations and error handling to align with these new types and deprecations.
8/19/2025, 3:25:48 PM
The `collectionReorderProducts` mutation’s description and arguments were rewritten to clarify that only moved products should be sent, that moves are applied sequentially, and that `newPosition` is a zero‑based index evaluated after each prior move; the mutation now returns a job object. The `moves` list’s documentation was updated to emphasize sending only changed products, allowing non‑unique `newPosition` values and moving items to the end if the value exceeds the list length. The mutation’s return type remains `CollectionReorderProductsPayload`. Additional schema changes include converting `CheckoutAndAccountsAppConfiguration.brandingConfiguration` from a raw JSON scalar to a typed `CheckoutBranding` object, removing the `resourceType` field from `CustomerPaymentMethod`, and adding several new enum values for various error codes (`TAG_EXCEEDS_MAX_LENGTH`, `ACTIVATION_FAILED`, etc.). A new field `disputeEvidence` was added to `ShopifyPaymentsDispute` to expose dispute evidence details, and a set of LENDING‑related transaction types was added to `ShopifyPaymentsTransactionType`. The enum `StagedUploadTargetGenerateUploadResource` now includes `DISPUTE_FILE_UPLOAD`. Finally, the entire `MandateResourceType` enum was removed from the schema. Developers must adjust mutation payloads for collection reordering, update type handling for the new branding object, and account for the removed field and added enums in error handling and transaction logic.
8/12/2025, 12:00:46 AM
1. The order‑count query (`ordersCount`) now accepts a `limit` argument (default 10,000) to cap how many results are returned. 2. The `orders` and `ordersCount` query arguments gained a new filter key: `metafields.{namespace}.{key}` allowing queries by metafield values. 3. Discount types now expose a `context` field (union `DiscountContext`) that replaces the previously used `customerSelection`. 4. The `customerSelection` field is deprecated with a note to use `context` instead. 5. New enum `DiscountBuyerSelection` and helper object `DiscountBuyerSelectionAll` were added to describe “all buyers” scenarios. 6. The Shop type’s `orders` field is deprecated in favor of using the root `orders` query, so developers should migrate queries accordingly. 7. The description of the `Shop.orders` field still mirrors the root query but will be removed in a future release. 8. All updated descriptions remain unchanged but the added filters and fields should be considered in API calls.
8/11/2025, 2:54:34 PM
The `dispute` query’s description now states it returns a `ShopifyPaymentsDispute` resource by ID, and the `disputeEvidence` query similarly clarifies it returns a `ShopifyPaymentsDisputeEvidence`. A new enum, `MandateResourceType`, is added to list resource types for payment mandates (CARD_ON_FILE, CHECKOUT, DRAFT_ORDER, ORDER, SUBSCRIPTIONS). The `CustomerPaymentMethod` type now includes a `resourceType` field that references this new enum, indicating the specific resource a mandate supports. The `OnlineStoreTheme` type’s `files` field now allows up to 2,500 items per page (instead of 250) while keeping the same filename filtering and pagination arguments. The `ProductStatus` enum now contains an additional value, `UNLISTED`. These changes are mostly descriptive and structural; existing functionality remains unchanged, but developers should update field selections and pagination limits to take advantage of the new enum and expanded file list capacity.
8/7/2025, 3:52:43 PM
The webhookSubscriptions query no longer accepts the callbackUrl argument, simplifying subscription filtering. A parentRelationship field has been added to AbandonedCheckoutLineItem along with a new AbandonedCheckoutLineItemParentRelationship type that exposes the parent line item through its parent property. The Publication type now contains an includedProductsCount field, which counts included products and accepts optional filtering and a limit variable. Both the includedProducts and products connection fields on Publication have been extended with sortKey, query, and savedSearchId arguments; products additionally gain the same sortKey as their existing filters. Enumeration ShopifyPaymentsTransactionType now includes four new members for managed markets dispute fee debit/credit and their reversals. Minor description changes on several query return types have been made for consistency.