2023-04 release notes

What's new in 2023-04

The following features were added in version 2023-04 of Shopify's APIs.

Highlights from the GraphQL Admin API changes:

• Metafield values can now be set for Locations

• Move and Hold mutations for FulfillmentOrders now accept specific line items

• Subscription contracts can now be created in a single operation

• Customer profiles can now be combined using the Merge API

• Functions APIs are now available for delivery and payment customizations

• Catalog APIs are now available

• Webhooks for B2B Customers have been added

• Metafield definition validations can now be updated

  Highlights from the GraphQL Storefront API changes:

• Metafields on Locations can now be queried

• Targeted product recommendations can now be generated

• Catalog APIs are now available

• A buyer's wallet preference can now be passed to the Cart

• Customer address IDs can now be used as input for delivery address preferences

  Highlights from the GraphQL Payments Apps API changes:

• The status field in the Payments Apps API has been removed.

• The previously deprecated status field has been removed from session-related objects.

  Highlights from the REST Admin API changes:

• Move and Hold operations for FulfillmentOrders now accept specific line items

• Additional filtering has been added to FulfillmentOrders

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 Metaobjects can now be TranslatableMetaobjects can now be Translatable

Metaobjects can now be enabled with the Translatable capability.

Anchor to Changed access scope for publishing and unpublishing to current channel objectsChanged access scope for publishing and unpublishing to current channel objects

Calling the publishableUnpublishToCurrentChannel and publishablePublishToCurrentChannel mutations now requires the writepublications access scope, instead of the writeproductslistings access scope, which has been deprecated.

Anchor to The ,[object Object], access scope has been deprecatedThe writeproductslistings access scope has been deprecated

The writeproductslistings access scope has been deprecated. Use writepublications instead.

Anchor to The ,[object Object], field on ,[object Object], has been removedThe contextRule field on PriceList has been removed

The contextRule field on PriceList has been removed. Existing apps should migrate to Catalogs. Check out our migration guide for more information.

Anchor to The ShopifyQL parse error codes have been updatedThe ShopifyQL parse error codes have been updated

The 'ParseErrorCode' values have been updated. Refer to the following list of codes for more details:

Anchor to [object Object], codes have been updatedFulfillmentOrderLineItemsPreparedForPickupUserErrorCode codes have been updated

The FulfillmentOrderLineItemsPreparedForPickupUserErrorCode object has the following changes:

• The FULFILLMENT_ORDER_CHANGED error code has been removed
• The UNABLE_TO_PREPARE_QUANTITY error code has been added

Anchor to [object Object], has been replacedPublishedTranslation has been replaced

The PublishedTranslation object has been replaced by Translation. All existing connections to PublishedTranslation now point to Translation. All existing fields on PublishedTranslation exist on Translation, except for the marketId field. Instead, Translation is linked directly to Market through the market field.

Anchor to Introducing ,[object Object]Introducing BaseCartLine

We have introduced BaseCartLine as an interface to CartLine. CartLineConnection has been updated to BaseCartLineConnection.

Anchor to The ,[object Object], field in the Payments Apps API has been removedThe status field in the Payments Apps API has been removed

The previously deprecated status field has been removed in favour of the state field on the following Payments Apps API objects:

• PaymentSession
• RefundSession
• CaptureSession
• VoidSession

Anchor to New error codes in ,[object Object], enumNew error codes in CartErrorCodes enum

Two new error codes, INVALID_DELIVERY_GROUP and INVALID_DELIVERY_OPTION, have been added to the CartErrorCode enum.

Anchor to [object Object], in the REST API will now return the total unsettled set amountTransaction in the REST API will now return the total unsettled set amount

Requests for Transaction will now return total_unsettled_set. This represents the remaining amount to be captured on the transaction. total_unsettled_set is returned in both shop and presentment money objects with currency.

Anchor to Access to the Asset API is no longer available to public appsAccess to the Asset API is no longer available to public apps

When requesting the Asset API, access to create, update and delete assets is no longer accessible for public apps. Refer to this guide for more details on the change, exemptions and how to migrate your apps.

Anchor to Payment properties on the ,[object Object], resource have been removedPayment properties on the Order resource have been removed

The following properties have been removed from the Order resource:

• gateway
• payment_details
• processing_method

Anchor to GraphQL Admin API changesGraphQL Admin API changes

The following are all the changes currently introduced in the 2023-04 version of the GraphQL Admin API.

Anchor to The inventoryItemId field has been added to FulfillmentOrderLineItemThe inventoryItemId field has been added to FulfillmentOrderLineItem

The inventoryItemId field can now be accessed from the FulfillmentOrderLineItem resource.

Anchor to Functions APIs have been added in developer preview for delivery and payment customizationsFunctions APIs have been added in developer preview for delivery and payment customizations

The Functions APIs for delivery customizations and payment customizations are now available in a developer preview.

With these new APIs, you can hide, reorder, or rename payment and delivery options to help merchants increase conversions and stand out from the competition.

Learn more about building with delivery and payment Functions in our dev docs:

• Delivery customization
• Payment customization

Anchor to Metafield values can now be set for LocationsMetafield values can now be set for Locations

Metafield values can now be set for Locations via the locationAdd and locationEdit mutations.

Anchor to Metaobjects can now be translatedMetaobjects can now be translated

Anchor to BreakingBreaking

Metaobjects can now be enabled with the Translatable capability. When enabled, all Metaobjects belonging to the definition are eligible for translations through the Translations API as well as the Translate and Adapt app.

Anchor to Access Scope has changed for publishing and unpublishing to current channelAccess Scope has changed for publishing and unpublishing to current channel

Anchor to BreakingBreaking

Calling the publishableUnpublishToCurrentChannel and publishablePublishToCurrentChannel mutations now requires the writepublications access scope, instead of the writeproductslistings access scope, which has been deprecated.

Anchor to Check if a Shop is verified by Shopify tiersCheck if a Shop is verified by Shopify tiers

The MerchantApprovedSignals object, which is a field on the Shop object, has a new verifiedByShopifyTier field that determines what tier of pre-approval a merchant is in, if available.

Anchor to Move and Hold mutations for FulfillmentOrders now accept specific line itemsMove and Hold mutations for FulfillmentOrders now accept specific line items

The fulfillmentOrderMove and fulfillmentOrderHold mutations have a new and optional fulfillment_order_line_items parameter that enables you to specify the line items you wish to hold or move.

Anchor to Orders can be filtered by return statusOrders can be filtered by return status

The return_status filter is available on the orders connection. This status corresponds to the return status that merchants see in the Orders page in the Shopify admin.

For more information on Order status, check out the help center.

Anchor to Create subscription contracts in a single operationCreate subscription contracts in a single operation

You can now create subcription contracts in a single operation with the new subscriptionContractAtomicCreate mutation. You can also replace a product, or update the price of a product in a subscription contract using the subscriptonContractProductUpdate mutation.

Anchor to The contextRule field on PriceList has been removedThe contextRule field on PriceList has been removed

Anchor to BreakingBreaking

The contextRule field on PriceList has been removed and deprecated in previous versions of the API. Existing apps should migrate to Catalogs. Check out our migration guide for more information.

Anchor to ShopifyQL parse error codes have been updatedShopifyQL parse error codes have been updated

Anchor to BreakingBreaking

The ParseErrorCode values have been updated according to the following list:

Added

• INVALID_DATE_RANGE

• EXCESS_BACKFILL_DIMENSIONS

• BACKFILL_DATE_RANGE_NOT_FOUND

• COMPARE_TO_MISSING_PERIOD

• EXCESS_DIMENSIONS

• SYNTAX_FAILED_PREDICATE

  Removed

• VISUALIZE_TYPE_NOT_FOUND

• FUNCTION_MODIFIER_INVALID

• VISUALIZE_BY_OR_OVER_NOT_FOUND

• VISUALIZE_CONTAINS_BY_AND_OVER

• BINARY_EXPRESSION_INCOMPATIBLE_TYPES

• VISUALIZE_EXCESS_PROJECTIONS_ALPHA

• EXCESS_GROUP_BY_ALL

• GROUP_BY_ALL_DATE_RANGE_NOT_FOUND

• COMPARE_TO_WITHOUT_DURING

• GROUP_BY_EXCESS_PROJECTIONS

Anchor to Combine customer profiles with the Merge APICombine customer profiles with the Merge API

Use the new Customer Merge API to combine two separate Customer records. You can use the new queries and mutations below to preview a merge, initiate a merge, and check the status of an ongoing merge.

New queries

• customerMergePreview

• customerMergeJobStatus

  New mutations

• customerMerge

  Additionally, you can check whether a customer can be merged with another customer using the new Customer.mergeable field. This field is also available on the CustomerSegmentMember API

Anchor to Create app charges using the merchant's billing currencyCreate app charges using the merchant's billing currency

The Billing API now enables you to create app charges using currencies that match the merchant's local billing currency.

Anchor to Functions APIs are now available for delivery and payment customizationsFunctions APIs are now available for delivery and payment customizations

The Functions APIs for delivery customizations and payment customizations are now available in a developer preview. With these new APIs, you can hide, reorder, or rename payment and delivery options to help merchants increase conversions and stand out from the competition.

Anchor to Catalog APIs are now availableCatalog APIs are now available

You can use the new Catalogs API to create a set of rules that determine the available products and their prices in different customer contexts. The Catalogs API lets you link Shopify Markets and B2B primitives to Publications and PriceLists to customize product offerings for different audiences. The same APIs also allow you to manage product publishing for sales channels.

Previously, app charges could only be created using USD and were converted to the merchant's local currency using the exchange rate at the time the invoice is issued. By creating app charges in the merchant's billing currency, app developers can enable merchants to better budget their app spend without being exposed to currency exchange rate fluctuations.

You can use the shopBillingPreferences query to retrieve the merchant's local billing currency, then pass in the currency value as input to the existing GraphQL Billing APIs.

Anchor to Web Pixels can now be queried without specifying an IDWeb Pixels can now be queried without specifying an ID

You can now query the web pixels installed on an online store without specifying the ID using the webPixel query. Learn more about web pixels.

Anchor to Idempotent creation of AppUsageRecordIdempotent creation of AppUsageRecord

The appUsageRecordCreate now supports an optional parameter idempotencyKey, which ensures the merchant will not be charged twice. When idempotencyKey is provided, the mutation will return the same response as any previous appUsageRecordCreate mutation calls with an identical idempotencyKey value for the intended shop and requesting app, rather than creating a new record and charging the merchant again.

This means that an idempotencyKey could be reused by an app to create AppUsageRecords on different shops to charge the merchant. Different apps can also use the same idempotencyKey on the same shop and still charge the shop. However, we recommend a UUID instead.

The appUsageRecordCreate mutation behaves like past API versions when the idempotencyKey value is not provided and creates a new record on every call.

Anchor to SVG files are now returned as a MediaImageSVG files are now returned as a MediaImage

SVG files are now treated as MediaImages by the Admin API. This makes it easier to use SVGs in your online storefront.

Anchor to The productVariantsBulkUpdate mutation now returns data along with errorsThe productVariantsBulkUpdate mutation now returns data along with errors

The productVariantsBulkUpdate mutation will now return Product and ProductVariant data even when errors are present. Previously, the mutation would always return null for the Product and ProductVariant data.

Anchor to PublishedTranslation has been replaced by TranslationPublishedTranslation has been replaced by Translation

Anchor to BreakingBreaking

The PublishedTranslation object has been replaced by Translation. All existing connections to PublishedTranslation now point to Translation. All existing fields on PublishedTranslation exist on Translation, except for the marketId field. Instead, Translation is linked directly to Market through the market field.

Anchor to FulfillmentOrderLineItemsPreparedForPickupUserErrorCode codes have been updatedFulfillmentOrderLineItemsPreparedForPickupUserErrorCode codes have been updated

Anchor to BreakingBreaking

The FulfillmentOrderLineItemsPreparedForPickupUserErrorCode object has the following changes:

• The FULFILLMENT_ORDER_CHANGED error code has been removed
• The UNABLE_TO_PREPARE_QUANTITY error code has been added

Anchor to Webhooks for B2B Customers have been addedWebhooks for B2B Customers have been added

The following webhook notifications for changes to the major entities within the B2B Customers product have been added:

• companies/create
• companies/update
• companies/delete
• company_locations/create
• company_locations/update
• company_locations/delete
• company_contacts/create
• company_contacts/update
• company_contacts/delete

Anchor to Destroy delegate access tokensDestroy delegate access tokens

You can use the delegateAccessTokenDestroy mutation to delete the delegate tokens created by the API client. For app architectures that use delegate tokens from multiple subsystems, this makes it easy to remove those delegate tokens that are unused or leaked for better application security.

Anchor to Additional fees fields for OrdersAdditional fees fields for Orders

The Order object has the following new fields that represent additional fees. Additional fees are extra costs associated with an international package that are neither duties nor taxes.

• additionalFees
• currentTotalAdditionalFeesSet
• originalTotalAdditionalFeesSet

Anchor to Update validations of a metafield definitionUpdate validations of a metafield definition

You can now use the new validations field on MetafieldDefinitionInput to change the validations for a Metafield definition. You can also query the validationJob field on MetafieldDefinitionUpdatePayload to get the details of the running validation job.

Anchor to Server Pixels are now available to select partnersServer Pixels are now available to select partners

Select partners can use Server Pixels to consume customer events on the server-side. These new mutations are available to those partners:

• serverPixelCreate
• eventBridgeServerPixelUpdate
• pubSubServerPixelUpdate
• serverPixelDelete

Anchor to You can compare columns in ShopifyqlResponseYou can compare columns in ShopifyqlResponse

You can now use the COMPARE TO keyword on comparison columns in ShopifyqlResponse to indicate the columns to be compared. Learn more about the COMPARE TO keyword in our ShopifyQL Documentation

Anchor to Added source_location field to FulfillmentOrdersMove webhook payloadAdded source_location field to FulfillmentOrdersMove webhook payload

The FulfillmentOrdersMove webhook payload is extended source_location field.

The assignedLocation of the original_fulfillment_order may be changed by the move operation. Therefore, if you need to determine the originally assigned location, then you should refer to the source_location field.

Anchor to Partial updates for bulk product variantsPartial updates for bulk product variants

The productVariantsBulkUpdate mutation has a new allowPartialUpdates parameter. By default, the mutation won't update any variant if any variant is invalid. However, when this field is set to true, the mutation will modify valid products variants, even if there are invalid ones.

Anchor to GraphQL Storefront API changesGraphQL Storefront API changes

Anchor to Metafields on Locations can now be queriedMetafields on Locations can now be queried

Metafields belonging to a Location can now be queried using the Location query object.

Anchor to Generate targeted product recommendationsGenerate targeted product recommendations

The productRecommendations query has a new optional intent argument of the type ProductRecommendationIntent. By default, the value for this argument is RELATED.

Anchor to A buyer's wallet preference can be passed to the CartA buyer's wallet preference can be passed to the Cart

The new wallet_preferences field on the CartBuyerIdentity object allows you to pass a buyer's wallet preference and be redirected to the accelerated checkout flow. Accepted value: shop_pay.

Anchor to Introducing BaseCartLineIntroducing BaseCartLine

Anchor to BreakingBreaking

We have introduced BaseCartLine as an interface to CartLine. CartLineConnection has been updated to BaseCartLineConnection.

Anchor to Read 3D model configuration settings from the Storefront APIRead 3D model configuration settings from the Storefront API

When a 3D model is customized via the no code 3D viewer configuration the properties associated with lighting, zoom, camera angle and background color are available in the Storefront API. Learn more about this feature on Shopify Help.

Anchor to Focal Point setting for images is now availableFocal Point setting for images is now available

You can now access the Focal Point for an image. Focal Points can be set from the shop admin while editing image files.

Anchor to You can use the customer's address id as input for delivery address preferencesYou can use the customer's address id as input for delivery address preferences

You can now pass the Customer's address id as an input for CartBuyerIdentity.deliveryAddressPreferences when creating or updating carts for authenticated customers.

Anchor to GraphQL Payments Apps API changesGraphQL Payments Apps API changes

Anchor to The status field in the Payments Apps API has been removedThe status field in the Payments Apps API has been removed

Anchor to BreakingBreaking

The previously deprecated status field has been removed in favour of the state field on the following Payments Apps API objects:

• PaymentSession
• RefundSession
• CaptureSession
• VoidSession

Anchor to New CartErrorCodes have been addedNew CartErrorCodes have been added

Anchor to BreakingBreaking

Two new error codes, INVALID_DELIVERY_GROUP and INVALID_DELIVERY_OPTION, have been added to the CartErrorCode enum. This error code can be returned when the cartSelectedDeliveryOptionsUpdate mutation is called.

Anchor to REST Admin API changesREST Admin API changes

Anchor to Move and Hold operations for FulfillmentOrders now accept specific line itemsMove and Hold operations for FulfillmentOrders now accept specific line items

The fulfillmentOrderMove and fulfillmentOrderHold operations have a new and optional fulfillment_order_line_items parameter that allows you to specific the line itms you wish to hold or move.

Anchor to Transaction will now return the total unsettled set amountTransaction will now return the total unsettled set amount

Anchor to BreakingBreaking

Requests for Transaction will now return total_unsettled_set. This represents the remaining amount to be captured on the transaction. total_unsettled_set is returned in both shop and presentment money objects with currency.

If you are leveraging manual capture and the authorized amount from Transaction, then you should switch to referencing total_unsettled_set. The authorized amount can differ from the total amount to capture due to adjustments during order finalization such as tax adjustments.

Anchor to Additional filtering added to FulfillmentOrdersAdditional filtering added to FulfillmentOrders

You can now retrieve a subset of FulfillmentOrders that are assigned to the locations owned by the app performing the request, but haven't yet been requested for fulfillment.

The assignment_status query parameter in the AssignedFulfillmentOrder endpoint can now accept a value of fulfillment_unsubmitted for filtering in addition to the existing fulfillment_requested, fulfillment_accepted, and cancellation_requested filter values.

Anchor to Access to the Asset API is no longer available to public appsAccess to the Asset API is no longer available to public apps

Anchor to BreakingBreaking

When requesting the Asset API, access to create, update and delete assets is no longer accessible for public apps. Refer to this guide for more details on the change, exemptions, and how to migrate your apps.

Anchor to Payment properties on the Order resource have been removedPayment properties on the Order resource have been removed

Anchor to BreakingBreaking

The following properties have been removed from the Order resource:

• gateway
• payment_details
• processing_method

Anchor to Additional fees fields for OrdersAdditional fees fields for Orders

The Order object has the following new fields that represent additional fees. Additional fees are extra costs that are associated with international packages that are neither duties nor taxes.

• current_total_additional_fees_set
• original_total_additional_fees_set

Anchor to Added source_location field to FulfillmentOrdersMove webhook payloadAdded source_location field to FulfillmentOrdersMove webhook payload

The FulfillmentOrdersMove webhook payload is extended source_location field.

The assignedLocation of the original_fulfillment_order may be changed by the move operation. If you need to determine the originally assigned location, then you should refer to the source_location field instead.