2024-04 release notes

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.

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.

• 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.

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.

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:

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

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

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

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.AdjustQuantities or Mutation.MoveQuantities.

Learn more about how to use the new fields.

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.

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.

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

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.

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.

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.

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:

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.

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.

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.

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.

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.

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

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.

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.

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

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

The Checkout resource is deprecated and will be sunset on April 1, 2025.

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.

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.

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.

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.

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.

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.

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.

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

Use the productDuplicateAsyncV2 mutation instead.

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.

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

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.

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