2023-01 release notes

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.

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.

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

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

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.

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

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.

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

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

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

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.

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.

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

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.

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.

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

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.

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

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.

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

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.

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.

We have removed the error code INVALID from LocationDeactivateUserErrorCode. This error code was never returned - inventorySetOnHandQuantities - inventoryAdjustQuantities - inventoryMoveQuantities

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

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.

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.

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

New mutations:

• paymentReminderSend

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.

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

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.

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

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.

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.

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

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

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.

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

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.

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.

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.

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

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

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

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.

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.