2024-04 release notes

Anchor to HighlightsHighlights

Here are some highlights of version 2024-04 of Shopify's APIs:

Anchor to Deprecations: Storefront API and REST Admin APIDeprecations: Storefront API and REST Admin API

This release deprecates the following parts of Shopify's APIs:

• Storefront API: Checkout mutations, queries, and types
• REST Admin API: Checkout resource

These items will sunset on April 1, 2025 (API version 2025-04). Before then, migrate your apps to:

• Cart API. To learn more, read Migrate to the Storefront Cart API.
• Checkout Kit. This library enables one-page checkout for iOS, Android, and React Native apps.

For more information, refer to Deprecation of Checkout APIs.

Anchor to GraphQL Admin APIGraphQL Admin API

The GraphQL Admin API now includes new product types that support up to 2048 variants, increasing per-product variant support from our historical maximum of 100. As part of these changes, GraphQL types and REST resources for managing product variants and options are deprecated.

All public apps that are built on existing GraphQL product APIs or REST product APIs must migrate to the new GraphQL product APIs by February 1, 2025.

Custom apps that are built using the existing GraphQL product APIs must migrate to the new GraphQL product APIs by April 1, 2025.

Custom apps that are built on REST will also need to migrate if they need to support more than 100 variants.

Custom apps that don't need to support more than 100 variants can continue to use the deprecated REST product APIs. However, please note the following:

• Developers should expect that the GraphQL API will be the only supported API over the long term and will be made aware of these timelines as they become available.

• The deprecated REST product APIs are in maintenance mode. All new features and support will be built only for the new GraphQL product APIs.

• Any merchant using custom apps that are built with these deprecated APIs will not be able to increase their variant limit past 100.

Anchor to Breaking changesBreaking changes

These changes require special attention. If your app uses these API resources, and you don’t adjust your usage of the resources according to the following instructions, then your app might break when you update to this API version.

Anchor to Checkout API DeprecationCheckout API Deprecation

We've deprecated the Checkout APIs. For more information, refer to Deprecation of Checkout APIs.

Anchor to Count field unificationCount field unification

Fields that returned a count of resources are removed and replaced with new count fields that have consistent API design and improved features. Count fields are now standalone fields with a common naming pattern and their own arguments instead of being a field under a connection type.

Anchor to Inventory mutations and fields removalInventory mutations and fields removal

The following fields and mutations are removed:

• InventoryLevel.available
• InventoryLevel.incoming
• InventoryLevel.deactivationAlertHtml
• Mutation.InventoryAdjustQuantity
• Mutation.InventoryBulkAdjustQuantityAtLocation

Replace InventoryLevel.available and InventoryLevel.incoming with InventoryLevel.quantities.

Replace InventoryLevel.deactivationAlertHtml with InventoryLevel.deactivationAlert.

Replace Mutation.InventoryAdjustQuantity and Mutation.InventoryBulkAdjustQuantityAtLocation with Mutation.InventoryAdjustQuantities or Mutation.InventoryMoveQuantities.

Anchor to Locale fields on ,[object Object]Locale fields on MarketWebPresence

The following fields on the MarketWebPresence object no longer return locale strings and instead make use of the ShopLocale type:

• defaultLocale
• alternateLocales

Update your API calls using MarketWebPresence.defaultLocale or MarketWebPresence.alternateLocales to use the ShopLocale type.

Anchor to Fulfillment request validationFulfillment request validation

We now validate that there are no duplicate fulfillment orders in requests to create a fulfillment.

GraphQL Admin API

You can no longer have have multiples of the same fulfillmentOrderId in a single request to the fulfillmentCreateV2 mutation.

Instead, you must combine any payload with the same fulfillmentOrderId into one group.

REST Admin API

You can no longer have multiples of the same fulfillment_order_id within the line_items_by_fulfillment_order parameter, for POST calls to the REST Admin API that create a fulfillment for one or many fulfillment orders.

Instead, you must combine any payload with the same fulfillment_order_id into one group.

Anchor to [object Object], deprecationOrderTransaction.receipt deprecation

The OrderTransaction.receipt field has been removed, and is replaced by receiptJson.

Anchor to Payment and billing error codes and mappingPayment and billing error codes and mapping

Payment error codes and mappings have changed. For detailed information on the changes, refer to the changelog.

Anchor to Sunset of ,[object Object], mutation, GraphQL Admin APISunset of productDuplicateAsync mutation, GraphQL Admin API

We've removed the productDuplicateAsync mutation, which has been deprecated since version 2023-07, from the GraphQL Admin API.

Use the productDuplicateAsyncV2 mutation instead.

Anchor to Customer Account APICustomer Account API

Version 2024-04 of the Customer Account API introduces the following changes:

Anchor to Company and CompanyLocation metafieldsCompany and CompanyLocation metafields

You now have read access to metafields on Company and CompanyLocation objects on the Customer Account API.

Learn more about the Metafield object on the Customer Account API.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

Version 2024-04 of the GraphQL Admin API introduces the following changes:

Anchor to Additional information for delivery methodsAdditional information for delivery methods

The DeliveryMethodAdditionalInformation object has been added, which supports additional information on delivery methods to assist during the delivery process.

The additionalInformation field is added to the deliveryMethod object, which enables additional information to be read when performing a delivery.

Anchor to Charge custom amountsCharge custom amounts

• The amount argument has been added to the orderCreateMandatePayment mutation.

  Use this argument to specify custom amounts to be charged from a vaulted card for Shopify Plus merchants.

Anchor to Checkout header and footer customizationCheckout header and footer customization

The CheckoutBranding object now enables you to customize the header and footer that displays at Checkout and Thank you pages to represent a merchant's brand. In the object and mutation, header and footer customizations are available on the customizations data object.

For example, you can hide the logo, breadcrumbs, default footer content, and Back to cart link, and control the footer position and alignment. On one-page checkout, you can customize the back to cart link with a custom icon.

The following new fields are available:

Learn how to customize the header and footer for common use cases, using the GraphQL Admin API and checkout UI extensions.

Anchor to Checkout section stylingCheckout section styling

You can now use the CheckoutBranding object to style sections of checkout and order summary. Section styling is used to highlight or contour the look of a page, creating high visual impact and expressiveness in structured content.

In the object and mutation, section customizations are available on the customizations and design-system data objects.

The following are the data structures, which illustrate the customization capabilities now available through the API:

designSystem {
  colors {
    schemes {
      scheme3 {
        base {
          background
          text
          border
          icon
          accent
          decorative
        }
        control {
          background
          text
          border
          icon
          accent
          decorative
          selected {
            background
            text
            border
            icon
            accent
            decorative
          }
        }
        primaryButton {
          background
          text
          border
          icon
          accent
          decorative
          hover {
            background
            text
            border
            icon
            accent
            decorative
          }
        }
        secondaryButton {
          background
          text
          border
          icon
          accent
          decorative
          hover {
            background
            text
            border
            icon
            accent
            decorative
          }
        }
      }
      scheme4 {
        base {
          background
          text
          border
          icon
          accent
          decorative
        }
        control {
          background
          text
          border
          icon
          accent
          decorative
          selected {
            background
            text
            border
            icon
            accent
            decorative
          }
        }
        primaryButton {
          background
          text
          border
          icon
          accent
          decorative
          hover {
            background
            text
            border
            icon
            accent
            decorative
          }
        }
        secondaryButton {
          background
          text
          border
          icon
          accent
          decorative
          hover {
            background
            text
            border
            icon
            accent
            decorative
          }
        }
      }
    }
  }
}

customizations {
  main {
    section {
      background
      colorScheme
      cornerRadius
      border
      borderStyle
      borderWidth
      padding
      shadow
    }
  }
  orderSummary {
    section {
      background
      colorScheme
      cornerRadius
      border
      borderStyle
      borderWidth
      padding
      shadow
    }
  }
  expressCheckout {
    button {
      cornerRadius
    }
  }
}

To learn more, refer to our tutorial on checkout section styling.

Anchor to Checkout color schemesCheckout color schemes

The CheckoutBranding object now supports configuring two new color schemes, scheme3 and scheme4.

Previously, only two color schemes were available. Now you can configure up to four schemes and assign any of them to the following sections in the customizations data object:

• main
• main.section
• orderSummary
• orderSummary.section

Anchor to Code-based discounts on line itemsCode-based discounts on line items

The withCodeDiscounts argument has been added to the LineItem object's discountedTotalSet field.

Use this field to either include or exclude line item discounts that originate from a discount code.

Anchor to Count field unificationCount field unification

Anchor to BreakingBreaking

Fields that returned a count of resources are removed and replaced with new count fields that have consistent API design and improved features. Count fields are now standalone fields with a common naming pattern and their own arguments instead of being a field under a connection type.

Instead of varying Int or UnsignedInt64 return types, all count fields now return a Count object type with precision and count fields.

Some count fields now accept filter arguments matching that of a neighboring connection, such as products and productsCount.

For detailed information on the changes, refer to the changelog.

Anchor to Create options linked to metafieldsCreate options linked to metafields

You can now use the productOptionsCreate, productCreate, and productOptionUpdate mutations to create metafield-linked product options.

Metafield-linked product options are only available in Shopify taxonomy early access.

Learn more about metafield-linked product options.

Anchor to Customer redaction supportCustomer redaction support

The error code CUSTOMER_REDACTED has been added to the subscriptionContractAtomicCreate and subscriptionContractCreate mutations.

This error code is returned when you create new subscription contracts for customers whose data is scheduled for redaction or has been redacted.

Learn more about erasing a customer's personal data.

Learn more about customer redaction here.

Anchor to Customer subscription contractsCustomer subscription contracts

The subscriptionContract and subscriptionContracts fields have been added to the Customer object.

Use these fields to query for all subscription contracts that belong to a customer, or to query for a specific subscription contract, respectively.

Anchor to Custom storefront attribution for abandonment eventsCustom storefront attribution for abandonment events

The isFromCustomStorefront field has been added to the Abandonment object, enabling you to determine whether an abandonment event comes from a custom storefront channel.

Anchor to Error codes for creating product mediaError codes for creating product media

The following error codes have been added to the FilesErrorCode enum:

• PRODUCT_MEDIA_LIMIT_EXCEEDED: Thrown when you exceed the limit of 250 media items per product
• MISSING_ARGUMENTS: Thrown when zero arguments are provided with the media file upload

Anchor to Fulfillment request validationFulfillment request validation

Anchor to BreakingBreaking

We now validate that there are no duplicate fulfillment orders in requests to create a fulfillment.

You can no longer have multiples of the same fulfillmentOrderId in a request to the fulfillmentCreateV2 mutation.

Instead, you must combine any payload with the same fulfillmentOrderId into one group.

Anchor to Fulfillment service opt-in deprecationFulfillment service opt-in deprecation

The fulfillmentOrdersOptIn field on the FulfillmentService object, along with its related types, is being deprecated because the migration to the Fulfillment Orders API is complete. All properly functioning fulfillment services now have the fulfillmentOrdersOptIn field set to true.

In the 2024-04 API version, the fulfillmentOrdersOptIn field becomes nullable and defaults to true in the fulfillmentServiceCreate mutation. This field will be removed from the mutation input in the next API version.

To prepare for the 2024-07 API version release, stop supplying the fulfillmentOrdersOptIn parameter when you create a new fulfillment service.

Anchor to Google Cloud Pub/Sub webhook duplicate error handlingGoogle Cloud Pub/Sub webhook duplicate error handling

The TAKEN enum value has been added to the list of error codes in PubSubWebhookSubscriptionCreatePayload returns, indicating when an address for the webhook topic has already been taken.

Anchor to Inventory management when updating fulfillment servicesInventory management when updating fulfillment services

The inventory_management argument has been added to the fulfillmentServiceUpdate mutation.

Use this field to specify whether the fulfillment service tracks product inventory and provides updates to Shopify.

Anchor to Inventory mutations and fields removalInventory mutations and fields removal

Anchor to BreakingBreaking

The following fields and mutations are removed:

• InventoryLevel.available
• InventoryLevel.incoming
• InventoryLevel.deactivationAlertHtml
• Mutation.InventoryAdjustQuantity
• Mutation.InventoryBulkAdjustQuantityAtLocation

Replace InventoryLevel.available and InventoryLevel.incoming with InventoryLevel.quantities.

Replace InventoryLevel.deactivationAlertHtml with InventoryLevel.deactivationAlert.

Replace Mutation.InventoryAdjustQuantity and Mutation.InventoryBulkAdjustQuantityAtLocation with Mutation.InventoryAdjustQuantities or Mutation.InventoryMoveQuantities.

Learn more about how to use the new fields.

Anchor to Locale fields returnLocale fields return

Anchor to BreakingBreaking

The following fields on the MarketWebPresence object no longer return locale strings and instead make use of the ShopLocale object:

• defaultLocale
• alternateLocales

Update your API calls using MarketWebPresence.defaultLocale or MarketWebPresence.alternateLocales to use the ShopLocale object instead.

Anchor to Media type query for product connectionMedia type query for product connection

The media connection on the Product object now includes a media_type filter on its query argument. The following are the valid values:

• IMAGE
• VIDEO
• MODEL_3D
• EXTERNAL_VIDEO

Use this filter to search the media that's associated with a product, such as images, 3D models, or videos.

Anchor to Metafield capability violation error codeMetafield capability violation error code

We've added the CAPABILITY_VIOLATION error code to additional mutations that write metafields.

Anchor to New fulfillment order assignment statusNew fulfillment order assignment status

The FULFILLMENT_UNSUBMITTED value has been added to the set of FulfillmentOrderAssignmentStatus enum.

Use this value to filter fulfillment orders for which the merchant hasn't yet requested fulfillment.

Anchor to New fulfillment order search optionsNew fulfillment order search options

You can now use the following new sort options in the fulfillmentOrders query.

• createdAt: The date that the fulfillment order was created.
• fulfillBy: The date by which the fulfillment order should be fulfilled by the merchant.

Anchor to New fulfillment order sort keyNew fulfillment order sort key

The UPDATED_AT enum value has been added to the set of FulfillmentOrderSortKeys.

Use this value to prioritize your work on fulfillment orders, and reduce the query cost when you're sorting and searching through other filters.

Learn more about sort and search parameters for fulfillment orders.

Anchor to New inventory item fields and product variant deprecationsNew inventory item fields and product variant deprecations

The following new fields are exposed on the InventoryItem object and its related input types, and some fields on ProductVariant, and related input types, that were marked as deprecated. These changes are all in support of removing long-deprecated fields on ProductVariant and removing the duplicated fields between ProductVariant and InventoryItem.

The following changes were made to InventoryItem and related input types:

The following changes were made to ProductVariant and related input types:

Anchor to Order payment status transactionOrder payment status transaction

The transactions field has been added to the OrderPaymentStatus object.

Use this field to retrieve the transaction that's associated with an order's payment.

Anchor to Order risk deprecationOrder risk deprecation

The OrderRisk object and associated fields are deprecated.

Use the new OrderRiskAssessment object and related types instead. For example, to create assessments, you can use the new orderRiskAssessmentCreate mutation.

We've also added the new ORDERS_RISK_ASSESSMENT_CHANGED webhook, which is triggered when a new risk assessment is available on an order.

Anchor to Payment and error code mappingPayment and error code mapping

Anchor to BreakingBreaking

The following fields have been added to the SubscriptionBillingAttemptErrorCode enum:

• CARD_NUMBER_INCORRECT
• INSUFFICIENT_FUNDS
• PAYPAL_ERROR_GENERAL
• PURCHASE_TYPE_NOT_SUPPORTED
• FRAUD_SUSPECTED

Additionally, payment error code mappings have changed, and codes from payment processors have changed. For more information, refer to the changelog.

Anchor to Product model and components changesProduct model and components changes

We've introduced a new product model that includes enhancing product-related components in the GraphQL Admin API. These changes include deprecating product-related components.

• The number of variants and options are no longer fixed at 100 and 3, respectively. Instead, the limits can vary by shop. We expect to have most shops support an initial rollout of 2K variants and 3+ options.

• We've introduced new mutations and fields for managing product options.

• We've elevated options and option values as first class entities within the data model.

• We've separated variant and option operations from product operations. Depending on your workflow, we recommend that you start managing your product variants using bulk product variant mutations.

• A variant_gids field will be retroactively added to all webhook versions. Product webhooks will return a full variants payload for the first 100 records, and only the variant_ids for variants 101+.

Learn more about mutations for managing product options and variants, and refer to the list of deprecated fields and what you should use instead.

Anchor to Product taxonomyProduct taxonomy

Shopify has introduced a public product taxonomy, serving as an open-source, standardized, and global classification of products sold on Shopify. This taxonomy, composed of product categories, attributes, and attribute values, is utilized across Shopify and integrated with numerous marketplaces.

This feature enables developers to navigate the taxonomy tree for categories, attributes, and values.

To support this change the following types have been deprecated and replaced in favor of queryRoot.taxonomy.categories:

• queryRoot.productTaxonomy

• queryRoot.productTaxonomyNodes

• The ProductTaxonomyNode type has been replaced with a TaxonomyCategory type.

• The productCategory field on the Product object has been deprecated and replaced by category. This field points towards the new TaxonomyCategory object.

View the latest product taxonomy on the taxonomy explorer.

Anchor to Receipt field removalReceipt field removal

Anchor to BreakingBreaking

The OrderTransaction.receipt field has been removed, and is replaced by receiptJson.

Anchor to Return sales and exchange APIsReturn sales and exchange APIs

Returns now create corresponding sales entries.

• The ReturnAgreement type has been added to the SalesAgreement interface.
• The RETURN value has been added to the OrderActionType enum.
• The FEE value has been added to the SaleLineType enum. Fees can be of the type RestockingFee or ReturnShippingFee, which represent corresponding fees on a return.

Any GraphQL Admin API consumers of OrderActionType or SaleLineType need to accept these new enum values. Previous versions of the Admin API will show these values as UNKNOWN.

You can now view ExchangeLineItems on their associated return. This provides context on returns that will be resolved with an exchange.

A new webhook returns/update has been added. This webhook fires when fees or line items on a return are modified or removed. All returns webhooks will now display restock and shipping fees, as well as exchange line items.

Dispositions can no longer be created for canceled reverse fulfillment orders. This will result in the new error code INVALID_STATE.

Anchor to Shipping lines on order editingShipping lines on order editing

You can now add new shipping lines or remove existing shipping lines when editing an order. You can also continue to query removed shipping lines.

For detailed information, refer to the changelog.

Anchor to Shipping line price with currencyShipping line price with currency

The priceWithCurrency field has been added to the ShippingLineInput input object, providing the price of the shipping rate, with currency.

Anchor to Transaction details on voided transactionsTransaction details on voided transactions

You can now void a transaction, and receive the corresponding transaction details, using the transactionVoid mutation.

Anchor to REST Admin API changesREST Admin API changes

Version 2024-04 of the REST Admin API introduces the following changes:

Anchor to Checkout deprecationCheckout deprecation

The Checkout resource is deprecated and will sunset on April 1, 2025. For more information, refer to Deprecation of Checkout APIs.

Anchor to Fulfillment request validationFulfillment request validation

Anchor to BreakingBreaking

We now validate that there are no duplicate fulfillment orders in requests to create a fulfillment.

You can no longer have multiples of the same fulfillment_order_id within the line_items_by_fulfillment_order parameter, for POST calls to the REST Admin API that create a fulfillment for one or many fulfillment orders.

Instead, you must combine any payload with the same fulfillment_order_id into one group.

Anchor to Fulfillment service opt-in deprecationFulfillment service opt-in deprecation

The fulfillmentOrdersOptIn property on the FulfillmentService resource, along with the related endpoints, is being deprecated as the migration to the Fulfillment Orders API has been completed. All properly functioning fulfillment services now have the fulfillmentOrdersOptIn property set to true.

In the 2024-04 API version, the fulfillmentOrdersOptIn property becomes nullable and defaults to true in the POST FulfillmentService endpoint. This field will be removed from the endpoint parameters in the next API version.

To prepare for the 2024-07 API version release, stop supplying the fulfillmentOrdersOptIn parameter when creating a new fulfillment service.

Anchor to Product model and components changesProduct model and components changes

We've introduced a new product model that include deprecating product-related resources in the REST Admin API.

Refer to the list of deprecated endpoints, and learn more about the new product model and working with GraphQL.

Anchor to Order risk deprecationOrder risk deprecation

The OrderRisk resource and associated endpoints are deprecated.

Use the new OrderRiskAssessment GraphQL Admin API object and related types instead. For example, to create assessments, use the new orderRiskAssessmentCreate mutation on the GraphQL Admin API.

We've also added the new ORDERS_RISK_ASSESSMENT_CHANGED webhook for the GraphQL Admin API, which is triggered when a new risk assessment is available on an order.

Anchor to Shipping lines on order editingShipping lines on order editing

Removed shipping lines continue to be returned in the payload of the Order resource. You can determine whether a shipping line has been removed by checking the value of the new attribute is_removed.

For detailed information, refer to the changelog.

Anchor to Shopify Function APIs changesShopify Function APIs changes

Version 2024-04 of the Shopify Function APIs introduces the following changes:

Anchor to Cart transform API set line propertiesCart transform API set line properties

We've added the ability to set line properties using cart transform operations.

The attributes field has been added to the MergeOperation and ExpandedItem objects, which enable you to add CartLine attributes to the parent line and component line, respectively.

Anchor to Fulfillment request validationFulfillment request validation

Anchor to BreakingBreaking

You can no longer have multiples of the same fulfillment_order_id within the GraphQL Admin API's fulfillmentCreateV2 mutation.

Instead, you must combine any payload with the same fulfillment_order_id into one group.

Anchor to Sunset product duplicate async mutationSunset product duplicate async mutation

Anchor to BreakingBreaking

We've removed the productDuplicateAsync mutation, which has been deprecated since version 2023-07, from the GraphQL Admin API.

Use the productDuplicateAsyncV2 mutation instead.

Anchor to Storefront API changesStorefront API changes

Version 2024-04 of the Storefront API introduces the following changes:

Anchor to Address validation in cartAddress validation in cart

The following error codes have been added to the CartUserError object, to validate addresses:

• ADDRESS_FIELD_CONTAINS_EMOJIS
• ADDRESS_FIELD_CONTAINS_HTML_TAGS
• ADDRESS_FIELD_CONTAINS_URL
• ADDRESS_FIELD_DOES_NOT_MATCH_EXPECTED_PATTERN
• ADDRESS_FIELD_IS_REQUIRED
• ADDRESS_FIELD_IS_TOO_LONG
• INVALID_ZIP_CODE_FOR_PROVINCE
• INVALID_ZIP_CODE_FOR_COUNTRY
• ZIP_CODE_NOT_SUPPORTED
• PROVINCE_NOT_FOUND
• UNSPECIFIED_ADDRESS_ERROR

For error code descriptions, consult the reference for the code field on CartUserError

The deliveryAddressValidationStrategy field has been added to the DeliveryAddressInput input object, to define the available validation strategies for delivery addresses. The following enum values are added:

• COUNTRY_CODE_ONLY (default): Only the country code is validated
• STRICT: All fields in the address are validated according to Shopify's checkout rules. If the address fails validation, then the cart won't be updated.

Anchor to Checkout deprecationsCheckout deprecations

The following Checkout mutations, queries, and types are deprecated and will sunset on April 1, 2025:

For more information, refer to Deprecation of Checkout APIs.

Anchor to Delivery group typesDelivery group types

The groupType field has been added to the CartDeliveryGroup objects. The field accepts the following enum values:

• ONE_TIME_PURCHASE: The delivery group only contains merchandise that's either a one-time purchase or the first delivery of subscription merchandise.

• SUBSCRIPTION: The delivery group only contains subscription merchandise.

  Use the groupType field to determine whether a delivery group represents a single delivery or a recurring delivery.

Anchor to Metafields model 3D reference typeMetafields model 3D reference type

The MODEL_3D enum value on the mediaContentType field has been added to the Model3d object.