2023-04 release notes

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

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

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

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.

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

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.

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.

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.

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.

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.

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

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

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

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.

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.

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.

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.

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

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.

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.

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

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

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.

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

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.

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

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

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.

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.

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

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

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.

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

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.

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

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

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

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.

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.

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.

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.

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.

The following properties have been removed from the Order resource:

• gateway
• payment_details
• processing_method

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

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.