2023-01 release notes

What's new in 2023-01

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

Highlights from the GraphQL Admin API changes:

• Asynchronous queries in the Segmentation API
• Delivery settings support for more locations
• Duplicate and delete Product asynchronously
• Fulfillment API updates
• Inventory States API
• Metafields available on Company and CompanyLocation
• Metaobjects API
• ShopifyQL API
• New Webhook topics added and updated

Highlights from the GraphQL Storefront API changes:

• Metaobjects API
• StoreAvailability can now be searched based on proximity

Highlights from the REST Admin API changes:

• B2B Order Import
• New credit card fields added to Transaction

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 CheckoutProfiles sort order has changedCheckoutProfiles sort order has changed

The new EditedAt field has been added to the CheckoutProfile object. CheckoutProfiles are now sorted by the EditedAt field instead of updatedAt.

Anchor to The lineItem field on FulfillmentOrderLineItem has been deprecatedThe lineItem field on FulfillmentOrderLineItem has been deprecated

The lineItem field on FulfillmentOrderLineItem has been deprecated. The order line item associated with a FulfillmentOrderLineItem shouldn't be used to determine what to fulfill. Use the FulfillmentOrderLineItem and FulfillmentOrder objects instead.

Anchor to Removal of error code from LocationDeactivateUserErrorCodeRemoval of error code from LocationDeactivateUserErrorCode

The error coded INVALID has been removed from LocationDeactivateUserErrorCode.

Anchor to Shop billing address uses a new ShopAddress typeShop billing address uses a new ShopAddress type

The billingAddress field on Shop uses a new ShopAddress type instead of MailingAddress. Since Shop.billingAddress never returns non-null first or last names, these fields have been marked as deprecated on the new ShopAddress type. You should stop requesting those fields as they will be removed in a later version.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

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

Anchor to Access controls for app metafieldsAccess controls for app metafields

You can optionally specify an access setting when you create or update metafield definitions via the API. This new setting will allow you to control who else can access the metafields under your definition via the Admin API.

Note that this setting can only be set when the definition is in your own reserved namespace.

Possible settings you can use are PRIVATE (no one else can access the metafields), MERCHANT_READ (the merchant has read-only access to the metafields via the admin UI), and MERCHANT_READ_WRITE (the merchant can view and edit the metafields via the admin UI).

Learn more about access controls in our documentation.

Anchor to Asynchronous queries in the Segmentation API ,[object Object]Asynchronous queries in the Segmentation API

Starting in this verion, some queries could be processed and returned asynchronously based on complexity and the amount of shop data. Most queries will continue to be evaluated synchronously. This breaking change allows you to build the best possible user experience as we introduce more complex filters in Segmentation. Asynchronous queries should revolve within 5 seconds but some queries might take up to 1-2 minutes or even longer.

To get up to date, make sure you are handling responses returning an error code because the query must be processed asynchronously. You can follow our migration guide.

Learn more about building for asynchronous queries in our developer documentation or visit our API forum for questions.

Anchor to Automated collections with metafield conditionsAutomated collections with metafield conditions

Automated collections now support metafield conditions. These are controlled by enabling the respective metafield definition on your settings page.

Anchor to New EditedAt field for CheckoutProfileNew EditedAt field for CheckoutProfile

Anchor to BreakingBreaking

The new EditedAt field has been added to the CheckoutProfile object. CheckoutProfiles are now sorted by the EditedAt field instead of updatedAt.

Anchor to Due on Fulfillment is now a PaymentTermsTypeDue on Fulfillment is now a PaymentTermsType

A new value of FULFILLMENT is now available on the PaymentTermsType enum. With this change, apps can create and update orders and draft orders with payment terms whose due date will be set upon fulfillment of the order.

Anchor to Duplicate and delete Product asynchronouslyDuplicate and delete Product asynchronously

New mutations, productDuplicateAsync and productDeleteAsync, have been added to allow you to asynchronously duplicate and delete products that have a high number of variants that are stocked at several locations. The existing mutations productDuplicate and productDelete may time out for these larger products.

New mutations:

• productDuplicateAsync
• productDeleteAsync

Anchor to The lineItem field on FulfillmentOrderLineItem has been deprecatedThe lineItem field on FulfillmentOrderLineItem has been deprecated

Anchor to BreakingBreaking

The lineItem field on FulfillmentOrderLineItem has been deprecated. The order line item associated with a FulfillmentOrderLineItem shouldn't be used to determine what to fulfill. Use the FulfillmentOrderLineItem and FulfillmentOrder objects instead.

Anchor to Fulfillment Events can be createdFulfillment Events can be created

FulfillmentEvents can now be created through the API using the fulfillmentEventCreate mutation. This was previously only possible through the REST Admin API.

New mutations:

• fulfillmentEventCreate

Anchor to FulfillmentOrderLineItems can be marked as being ready for pickupFulfillmentOrderLineItems can be marked as being ready for pickup

Using the new fulfillmentOrderLineItemsPreparedForPickup mutation, line items associated with a FulfillmentOrder can be marked as being ready for pickup by the customer.

New mutations:

• fulfillmentOrderLineItemsPreparedForPickup

Anchor to Fulfillment orders can now be accessed from QueryRootFulfillment orders can now be accessed from QueryRoot

You can now access fulfillment orders from QueryRoot.fulfillmentOrders in addition to the existing Shop.fulfillmentOrders connection, which is now deprecated. To learn more, take a look at our documentation on fulfillment orders

Anchor to Changes to the ,[object Object], mutationChanges to the metafieldsSet mutation

The metafieldsSet mutation has been updated so that the MetafieldsSetInput.type field can be omitted only when the metafield already has corresponding Metafield definitions.

Additionally, the mutation is now atomic and will not persist changes if any errors are encountered.

Anchor to Orders can be sorted by destinationOrders can be sorted by destination

The orders query can now be sorted by destination. Using this sort key will return Orders by country, then by zone (e.g. state, province, etc.) and finally by city.

Anchor to Inventory States APIInventory States API

New mutations have been added that allow the editing for inventory quantities at a specific location, as well as quantities reserved and on hold. New queries are also available to retrieve quantities for every state as well.

For more information, check out the documentation on Inventory States.

New queries:

• inventoryLevel
• inventoryItem

New mutations:

• inventorySetOnHandQuantities
• inventoryAdjustQuantities
• inventoryMoveQuantities

Anchor to Metafields are now available on Company and CompanyLocationMetafields are now available on Company and CompanyLocation

Metafields can now be added to Company and CompanyLocation as part of B2B. Addtionally, a subset of mutations are now available for use asynchronous usage via BulkOperation.

Anchor to Querying on Metafields has been simplifiedQuerying on Metafields has been simplified

When querying on Metafield, you can now optionally supply the key argument in the format of namespace.key. You will also be able to optionally supply the keys argument to the metafields connection as a list of strings in the same format. The key returned will also be in the format of namespace.key.

Anchor to Removal of SMS Templates as a translatable resource ,[object Object]Removal of SMS Templates as a translatable resource

SMS_Templates has been removed from the TranslatableResourceType enum. The corresponding mutations and queries will no longer accept SMS Template IDs:

• translationsRemove
• translationsRegister
• translatableResource
• translatableResourcesByIds

Anchor to Delivery settings support for more locationsDelivery settings support for more locations

We've introduced a few changes that will improve managing delivery settings for merchants with a high number of locations:

• A new and more efficient way of managing locations associated with groups within a delivery profile. Instead of using the locations field, which always requires the full list of locations to have in a location group, you can now use the locationsToAdd and locationsToRemove fields to specify exactly the locations you want to adjust from a group.

• A new argument locationGroupId has been added to profileLocationGroups field. You can use this to query a specific location group and fetch its paginated locations more efficiently.

• A new unassignedLocationsPaginated field has been added to DeliveryProfile. You can use this field to query locations that are not assigned to a delivery profile in a more efficient way.

• A new locationsCount field has been added to the DeliveryLocationGroup object.

• The Local Pickup API is now stable view the locationLocalPickupEnable and locationLocalPickupDisable mutations.

Anchor to DraftOrder and Order fields added to PaymentTerms objectDraftOrder and Order fields added to PaymentTerms object

When querying for a PaymentTerms object, you now have access to both the associated DraftOrder or Order.

Anchor to Fulfillment Service Creation will now throw errors without opt-in enabled ,[object Object]Fulfillment Service Creation will now throw errors without opt-in enabled

When trying to create a Fulfillment Service using the fulfillmentServiceCreate mutation, and error will be returned if the fulfillment_orders_opt_in field is not set to true in the parameters.

Similarly, when trying to update a Fulfillment Service using the fulfillmentServiceUpdate mutation, an error will be returned if the fulfillment service being updated has fulfillment_orders_opt_in set to false and the update request does not promote fulfillment_orders_opt_in to true.

Learn how to migrate to fulfillment orders how to fulfill fulfillment orders as a service app.

Anchor to Create fulfillment eventsCreate fulfillment events

You can now create FulfillmentEvents using the GraphQL Admin API using the fulfillmentEventCreate mutation. This was previously only possible using the REST Admin API.

New mutations:

• fulfillmentEventCreate

Anchor to Fulfillment order holds can be flagged with an external idFulfillment order holds can be flagged with an external id

The FulfillmentOrderHoldInput has a new field called externalId. This can be used to track states within your own application on why a fulfillment order has been placed on hold and when it needs to be released. To learn more about the fulfillment order API see the fulfillment order object documentation.

Anchor to Metaobjects APIMetaobjects API

We are introducing a new Admin API that allows the creation of custom data structures called Metaobjects. Similar to metafields, which enable custom fields to be associated with core resources within Shopify, Metaobjects provide a way to create and associate entirely new data models. The API includes:

• Defining objects with granular access control on how merchants and apps can interact with them.
• Creating entries of custom defined objects and making them publishable to storefronts.

Anchor to Removal of the error code when deactivating LocationRemoval of the error code when deactivating Location

Anchor to BreakingBreaking

We have removed the error code INVALID from LocationDeactivateUserErrorCode. This error code was never returned

• inventorySetOnHandQuantities
• inventoryAdjustQuantities
• inventoryMoveQuantities

Anchor to Release holds on multiple fulfillment ordersRelease holds on multiple fulfillment orders

You can now use the fulfillmentOrdersReleaseHolds mutation to release holds on multiple fulfillment orders in a single request. This will allow developers to reduce the number of individual requests used to complete bulk fulfillment actions with their apps.

New mutations:

• fulfillmentOrdersReleaseHolds

Anchor to Reengagement AutomationsReengagement Automations

You can now integrate marketing automation flow actions inside of our reengagement marketing automation workflows. These actions include:

• Abandoned checkout
• Abandoned cart
• Abandoned product browse

To learn more about reengagement automations, check out or blog post.

Anchor to Selling Plan Group Limit IncreaseSelling Plan Group Limit Increase

The limit on the number of associated Selling plans for Selling Plan Groups has been increased from 20 to 31. We recommend paginating all queries on a Selling Plan Group's Selling Plans, rather than relying on this fixed limit.

Learn more about Selling Plan Groups by referring to the purchase options documentation.

Anchor to Send payment reminders via emailSend payment reminders via email

You can use the new paymentReminderSend mutation to send payment reminder emails to customers.

New mutations:

• paymentReminderSend

Anchor to Mutation to change Shipping Packages has been updatedMutation to change Shipping Packages has been updated

The shippingPackageUpdate mutation has been updated so that shippingPackage is a required argument. shippingPackage is a set of attributes that describes a shipping package, including: weight, dimensions, name, default and type.

Anchor to ShopifyQL API is now availableShopifyQL API is now available

The ShopifyQL API is now available to query analytical data from merchant stores to create reporting apps that provide business insights for merchants.

New queries:

• shopifyqlQuery

Anchor to Shop Policy supports Contact InformationShop Policy supports Contact Information

The ShopPolicyType has been updated to include a new value of CONTACT_INFORMATION. This policy is intended to allow users to add regulatory information, including a Value-Added Tax (VAT) and trade number.

Anchor to Shop Resource FeedbackShop Resource Feedback

The new mutation shopResourceFeedbackCreate allows clients to create resource feedback to let a merchant know what steps are needed to ensure it is set up correctly.

New mutations:

• shopResourceFeedbackCreate

Anchor to Shop billing address uses a new ShopAddress typeShop billing address uses a new ShopAddress type

Anchor to BreakingBreaking

The billingAddress field on Shop uses a new ShopAddress type instead of MailingAddress. Since Shop.billingAddress never returns non-null first or last names, these fields have been marked as deprecated on the new ShopAddress type. You should stop requesting those fields as they will be removed in a later version.

Anchor to Payment ID has been added to OrderTransactionPayment ID has been added to OrderTransaction

A new paymentId field has been added to OrderTransaction. This unique ID is now sent to payment providers when a customer pays at checkout. This ID can be used to match order information between Shopify and payment providers. An Order can have more than one Payment ID. It only includes successful or pending payments. It does not include captures and refunds.

Anchor to Webhook topics added for LocationsWebhook topics added for Locations

Dedicated webhook topics have been introduced that will be sent out whenever a location is deactivated (locations/deactivate) or when a deactivated location is re-activated (locations/activate). Currently location deactivation and activation webhooks are lumped under the locations/update webhook topic.

Webhooks on the locations/update topic will also continue to be sent out for location activation/deactivation, in case any clients are already consuming these update notifications for this purpose. It is recommended that such clients switch over to consuming the dedicated locations/activate and locations/deactivate topics, as eventually lumping them together with locations/update webhooks will be deprecated in a future API version.

New webhooks:

• locations/deactivate
• locations/activate

Anchor to Webhook topics updated for fulfillment ordersWebhook topics updated for fulfillment orders

Webhooks related to Fulfillment Orders have been added and updated. For a full list of topics, refer to the documentation on Fulfillment Order Webooks.

Anchor to Webhooks added for returns appsWebhooks added for returns apps

Returns apps can now give merchants greater visibility into critical returns data across platforms, and help them manage orders more efficiently.

Returns apps can automate the return management process by taking actions on behalf of merchants. These actions can include the following:

• Creating and canceling returns
• Approving or declining return requests
• Managing reverse fulfillment orders and deliveries, including creating a reverse delivery with shipping information, and disposing or restocking items
• Issuing refunds
• Closing and reopening returns

We've also added new webhooks that your app can use to listen for events related to returns, refunds, reverse fulfillment orders, and reverse deliveries. Check out our documentation on returns apps for a full list.

Anchor to Webhook topic for when a payment schedule is dueWebhook topic for when a payment schedule is due

You can subscribe to the new PAYMENT_SCHEDULES_DUE webhook topic to be notified of when a PaymentSchedule.due_at date is reached.

Anchor to Webhooks added for subscription billing cyclesWebhooks added for subscription billing cycles

We have added webhooks for the subscription billing cycles API. The following are topics now available:

• subscription_billing_cycle_edits_create
• subscription_billing_cycle_delete
• subscription_billing_cycle_edits_update

We have also added new error codes to BillingAttemptUserErrorCode and SubscriptionBillingCycleUserError.

Anchor to GraphQL Storefront API changesGraphQL Storefront API changes

The following are all the changes currently introduced in the 2023-01 version of the GraphQL Storefront API:

Anchor to Metaobjects APIMetaobjects API

You can now access custom data structures called Metaobjects using the Storefront API. Similar to metafields, which enable custom fields to be associated with core resources in Shopify, metaobjects provide a way to associate entirely new data models. You can access entries of custom defined objects that were created through the Admin API and publish them to storefronts.

Anchor to New tag field has been added to the ProductFilter objectNew tag field has been added to the ProductFilter object

The ProductFilter object has a new tag field, which can be used for filtering if tags are enabled as a filter setting on the shop.

Anchor to StoreAvailability can now be searched based on proximityStoreAvailability can now be searched based on proximity

You can now use the near parameter to search StoreAvailability by proximity, via Storefront API. This parameter uses the GeoCoordinateInput.

Anchor to REST Admin API changesREST Admin API changes

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

Anchor to B2B Order ImportB2B Order Import

Merchants with B2B enabled on their stores can now Import Orders in a B2B context.

Anchor to New credit card fields added to TransactionNew credit card fields added to Transaction

New fields have been added to the payment_details property on Transaction.

New fields:

• credit_card_name: The holder of the credit card.
• credit_card_wallet: The wallet type where this credit card was retrieved from.
• credit_card_expiration_month: The month in which the credit card expires.
• credit_card_expiration_year: The year in which the credit card expires.

Anchor to Payment ID has been added to OrderTransactionPayment ID has been added to OrderTransaction

A new paymentId field has been added to Transaction. This unique ID is now sent to payment providers when a customer pays at checkout. This ID can be used to match order information between Shopify and payment providers. An Order can have more than one Payment ID. It only includes successful or pending payments. It does not include captures and refunds.