Developer changelog

You’ll now be able to trigger a webhook test payload to a specified destination directly from the CLI. Previously, developers needed to create a dev store and manually click around with an app installed in order to test their app logic. This manual process added significant time and friction to the development loop. With this new feature, it’ll be easy to test your subscriptions for each topic, so you can see what the payload will look like before your app is in production.

We’re also reducing the number of emails sent each time a webhook delivery fails. Previously, there was one email sent per attempt - which could quickly add up and become ineffective for monitoring. Now only one email will be sent for each one per consecutive string of failed attempts, over a two-day period, in order to keep your inbox clean and actionable.

To learn more about testing webhooks, check out the Shopify CLI command reference. If you have any questions about these changes, contact Partner Support with any questions.

The Voice and tone section of the App Design Guidelines has been shortened, with a new link to the complete Polaris documentation for voice and tone.

As of GraphQL Admin API version 2023-01, you can use webhooks with subscription billing cycles API.

We introduced subscription_billing_cycle_edits_create, subscription_billing_cycle_delete and subscription_billing_cycle_edits_update to WebhookSubscriptionTopic.

We also added some new error codes to SubscriptionBillingAttemptUserError and SubscriptionBillingCycleUserError.

Learn more about the Subscription Billing Cycles API on Shopify.dev.

The Localization API now supports online store media as a localizable resource. Metafield file references and "image" type theme sections can now be translated and localized to different markets using the translationsRegister mutation.

Note: media localization is currently only supported for theme sections & metafield file references. Product media localization is not yet supported.

The following properties on the REST and GraphQL Admin API's Order resource, including webhooks, are deprecated:

• gateway
• payment_details
• processing_method

The gateway and payment_details properties are available on the corresponding Transaction resources.

The processing_method property is no longer available due to orders supporting multiple transactions with various processing methods, the field contained incorrect data. The values it provided can be inferred from various sources: - free. This is accessible through the order totals. - checkout can be determined by the presence of checkout_id on an order. - express, direct, offsite, and manual can be inferred through the OrderTransaction gateway and payment_details properties.

These deprecated properties will be removed from unstable in January 2023. The change will be made official in the 2023-04 Admin API version.

Starting today, Shopify Functions are available to Shopify Plus brands who are not leveraging a checkout.liquid customization. This means that Plus merchants can start building their own product or order discount Functions and deploy them with a custom app.

Please note that the rollout to eligible Plus shops will take a couple of weeks to complete. Plus brands that leverage a checkout.liquid customization are not eligible to use Functions at this point in time.

Learn more about Shopify Functions here.

On December 6, we released new designs that make it easier for developers to showcase the value of their apps and for merchants to discover the right apps for their businesses, including:

• Optimized app listing
• Personalized home page
• Educational category pages
• New story pages

We will continue to build in public, with new features rolling out over the upcoming weeks.

As of the Admin API 2023-01 release candidate, Due on Fulfillment is now a Payment Terms type available to all 3rd party apps.

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. The newly added FULFILLMENT type value can be found on the PaymentTermsType ENUM object.

Accelerated checkout buttons will now always appear in checkout even if customers have previously seen them in cart. This change will gradually roll out to eligible shops over the next two weeks.

To learn more, refer to accelerated checkout buttons.

This spring, we added app highlights to app store listings to help merchants find high quality apps and make better informed decisions. These highlights show tested indicators of merchant success, including its impact to storefront performance, how it works with other Shopify features, and integration with Admin.

Starting December 1, we’re providing visibility into how to achieve these highlights within the Distribution section of the Partner Dashboard. Initial data shows that app highlights are a major factor for merchant exploration and installation.

Merchants based in Kuwait can now add governorates to their shipping zones.

As a result, merchants in this region can give their customers the opportunity to provide more accurate address information at checkout as well as set up more specific shipping zones for the governorates that they add.

As of 2023-01, the authorV2 field is being removed from the Storefront API. It was previously used to reference nullable author scenarios. As a result, the following changes are being made:

• authorV2 will now be deprecated.
• author will be used instead, and will now be a nullable field.

These changes will help improve consistency of the API and avoid confusion when using these fields.

The 'Speed Tested' app highlight in the app store has been adjusted as of November 17th to better reflect your app's current performance, as well as impact on checkout experience.

We continue to measure how apps affect store performance using Google Lighthouse, but we now focus on your app's affect from recent installations, as opposed to all historical installations. This change gives merchants more accurate info about which apps perform quickly on their stores. As developers improve their app's performance, those improvements will be reflected more quickly in the app highlights.

For a shipping app to be eligible to receive the 'Speed Tested' app highlight, we will now consider its response time and error rate for shipping rate requests. Because there is some variability in performance between checkouts, we will only feature apps with a sufficient number of installs and requests in order to ensure a stable measurement.

With the latest addition of theme support to Shopify CLI 3.x, Shopify CLI 2.x has been scheduled to sunset on May 31, 2023. Learn more about how to migrate over to Shopify CLI 3.x here.

Note that app and extension creation will sunset a month earlier on April 28, 2023.

You can now use Line Item Shopify Scripts with the Storefront API Cart to create discounts that are applied to a cart and reflected in the API response.

The App Design Guidelines have been updated to improve clarity on high quality app experiences.

In the app navigation section, it is now mandatory to use App Bridge’s Navigation Menu to integrate with the Shopify admin navigation experience if your app has different sections.

The existing requirement in the responsive grid section that apps must have responsive layouts for all device sizes has been moved to a callout card to make it more noticeable.

The wording of one callout card in the single-column layout section has been updated to make it clear that tables should only use the full width page if they have enough columns to require the extra space. Otherwise, they should use normal width pages.

Starting November 1, 2022, you can self-categorize your app once using the app submission form in the Partner Dashboard. Categories can be chosen by selecting up to two tags from our updated app categories that best describe the main function of your app. You can later appeal to change your app’s categorization if its capabilities change.

Learn more on Shopify.dev.

Merchants can create selling plan specific shipping rates (for subscriptions) and have those names from those rates surface in checkout.

We've added new functionality to replace the default subscription rate names (ie. "subscription shipping", "subscription pickup", "subscription local") to now expose the merchant defined rate names during checkout, admin order and in the email notification. If merchants do not create selling plan specific shipping rates then the general rate name will be surfaced in checkout.

Shopify Functions are available for developers to start customizing the backend logic of discounts. All non Shopify Plus merchants are able to install your apps today. Shopify Functions are not yet available to Shopify Plus merchants. We will provide an update when Functions become generally available to Plus brands.

Discount the entire cart with order discounts applying a fixed amount of percentage off.

Discount specific products with product discounts applying a fixed amount or percentage off.

Learn more about Shopify Functions on Shopify.dev

Support for themes has been added to Shopify CLI 3.20. In addition to migrating over theme commands, Shopify CLI 3.20 now includes the ability to integrate Shopify CLI into your CI/CD pipeline to perform actions like pushing, pulling and publishing a theme. Most theme commands on Shopify CLI 3.20 will continue to work the same with the exception of a few differences outlined here. More information on using Shopify CLI in a CI/CD pipeline can be found here.

We've implemented an automatic GIF to animated WebP conversion process in our image processing pipeline, which improves performance by reducing delivered bytes by up to 50%.

For more information, please visit Shopify Help Center .

In the API version 2022-10, we included the expanded support of new delivery options for Subscriptions: Local Delivery and Pickup.

As of API version 2023-01, we are deprecating the old shippingOptions field of SubscriptionDraft in favor of the new deliveryOptions field which supports Local Delivery and Pickup.

Learn more about deliveryOptions on Shopify.dev - SubscriptionDraft.

We've added the video setting. You can use the video setting to surface videos uploaded to the Files Page in your theme.

As of 2023-01 a unique ID is sent by Shopify to payment providers when a customer pays at checkout. Use this ID to match order information between Shopify and your payment provider. An order can have more than one Payment ID. It only includes successful or pending payments. It does not include captures and refunds.

Steps: 1. From your Shopify admin, go to Orders. 2. Search using the custom term payment_id: and the payment ID value. For example payment_id:xxx. 3. Alternatively, you can search using the payment_id directly, without any explicit filters. 4. Click the order.

We’ve added a new productCategory field to the Product object. The product category specifies a category in the Shopify Product Taxonomy.

We’re deprecating several fields: - The standardizedProductType field is deprecated in favor of productCategory. - The customProductType field is deprecated in favor of productType.

Previously, the product category data was not powering any platform features. Now, the product category will be used to determine the rate at which a product is taxed in the US. In the future, it will apply to how products are taxed in other regions/markets.

For more information, refer to the Product object or learn more about Product Tax Codes here

The Shopify cookies policy has been updated.

Breaking change

In addition to the policy update, we've added the following three required cookies to the Cookies Necessary for the Functioning of the Store cookie list:

• identity-state
• identity-state-<<token>>
• identity_customer_account_number

These cookies are required to use the new customer account log-in, which some merchants have already enabled. Without them, customers won't be able to log into the store. All cookies management applications, including GDPR-related apps, must update their application as soon as possible and not block these cookies.

Please be noted:

• The difference between - and _. The two identity state cookies names are:

identity-state and identity-state-<<token>>

NOT

identity_state and identity_state_<<token>>

• The token in the real name of identity-state-<<token>> is a random string, like identity-state-fsdf25fxg34se69d. The name does not contain < or >. It means, your app should not block cookies whose name is similar to identity-state-fsdf25fxg34se69d . This also applies to checkout_session_token_<<token>>. Your app should not block cookies whose name is similar to checkout_session_token_fsdf25fxg34se69d .

We've also added two cookies to the Reporting and Analytics cookie list:

• customer_auth_provider
• customer_auth_session_created_at

These cookies are used to provide additional data for Shopify analytics.

Requests made to Storefront API from SSL provisioned domains that are registered in the domains list on the Admin Panel will now return a two new headers:

Access-Control-Allow-Credentials: true Access-Control-Allow-Origin: ${origin_domain}

With that mechanism in place, Storefront API securely shares resources such as cookies with the browser, allowing for cart events originated from API Clients other than Online Store to be accounted for in the conversion metrics out of the box, as long as the origin request complies with CORS policy.

As of GraphQL Admin API version 2022-10, you can query for a CheckoutProfile, or mulitple CheckoutProfiles, providing insights about existing checkout profiles on your shop.

Learn more about Checkout Profiles on Shopify.dev.

As of GraphQL Admin API version 2022-10, you can use Web Pixel Extensions to connect your marketing and analytics pixels to a merchant's online store for collecting customer events.

Learn more about Web Pixels on Shopify.dev.

Checkout extensibility capabilities are available for developers to start building apps for checkout customizations. We’re gradually rolling out checkout extensibility to Shopify Plus merchants so they can install and use your apps in production. Merchants will be able to discover apps with checkout UI extensions via the checkout editor.

Add new functionality with checkout UI extensions in various places in checkout and Shop Pay. Use these extensions to add in unique elements like product offers, custom fields, custom banners and more that are adaptable to various flows, creating a unified experience for buyers wherever they choose to checkout.

Track events using the new web pixel extension, to provide customer events that merchants can subscribe to. Apps will be able to hook into the events in the Pixels API, including checkout, to allow merchants access privacy-compliant customer behavior analytics.

Merchants are now able to use the new checkout branding API to customize the styling, to truly make checkout feel like their own, adapting the visual appearance such as the logo, font, and colors. Checkout UI extensions will inherit the brand settings from this API, so your app automatically reflects a brand’s style.

To learn more about building apps for checkout, please review our developer documentation.

We have added the selected_delivery_option as part of the CartDeliveryGroup as well as the handle field as part of the CartDeliveryOption in the cart.

The selected_delivery_option field represents the selected delivery option in a delivery group. The handle field represents a unique identifier for the delivery option.

A default CartDeliveryOption is saved as the selected_delivery_option in each CartDeliveryGroup available.

We also added the cartSelectedDeliveryOptionsUpdate mutation, allowing you to update the selected_delivery_options of each of your delivery groups.

As of GraphQL Admin API version 2022-10, we are releasing a new mutation inventoryBulkToggleActivation.

This new mutation will allow you to bulk activate or deactivate a single inventory item at many locations, with a maximum of 250 locations at a time.

Instead of having to call inventoryActivate or inventoryDeactivate for each location, you can now do that in bulk for a single inventory item.

Learn more about the inventoryBulkToggleActivation mutation on Shopify.dev.

The Fulfillment API was deprecated in the Shopify 2022-07 release. However the cancel endpoint was missed and this change rectifies that mistake.

Apps will have until the 2023-04 release to migrate away from the deprecated API and use Fulfillment Orders instead. To help you seamlessly migrate, we’ve crafted a migration guide that walks you through the process of moving to Fulfillment Orders. To learn more, visit the migration guide on Shopify.dev.

As of 2022-10, Location resources support metafields. Use metafields APIs to store additional information in metafield values, like store hours, and then reference them in Liquid.

To learn more about metafields, refer to the metafields documentation. To use location metafields in Liquid, refer to the store_availability Liquid reference.

As of GraphQL Admin API and REST Admin API version 2022-10, information on application acting as the Merchant of Record for the order would be available through the Order object. This information would only be populated with supported applications.

New merchantOfRecordApp field in GraphQL Admin API returns OrderApp object and merchant_of_record_app_id field in REST Admin API returns the id of the application .

Learn more about the Order object on Shopify.dev.

As of Admin API version 2022-10, a new field transactional_sms_disabled has been added to the Shop object in the GraphQL and REST Admin APIs.

The field is also present on the "shop/update" webhook, which now will trigger when the transactional_sms_disabled state of a shop changes.

As of GraphQL Admin API version 2022-10, you can use the new manualHoldsFulfillmentOrders connection to fetch all the manually held fulfillment orders for a shop. Fulfillment orders can also be filtered based on order filters like - * order_risk_level - The fraud risk level of the order. * order_financial_status - The financial status of the order * shipping_address_coordinates_validated - Whether the shipping address was geolocated and it is a valid address.

You can now use the Storefront API to attach shipping address preferences to the carts of non-logged-in customers and the fetch cart delivery groups.

ThedeliveryAddressPreferences field has been added to the Storefront API's CartBuyerIdentity and CartBuyerIdentityInput objects, for this purpose.

Refer to our documentation on cartCreate and cartBuyerIdentityUpdate to learn more about how to create a cart or update a cart's buyer identity to send delivery address preferences.

You can now access a references connection on a metafield in the GraphQL Admin and Storefront APIs.

Use the references connection to resolve metafield values of a list reference type to their underlying resource. This new connection is paginated and works similarly to the existing reference field, which is used for single references.

This new endpoint is available in unstable, and will be part of the 2022-10 release.

For more information, refer to the Admin API and Storefront API documentation.

Retrieving a list of locations is now paginated by default. If you are a consumer of this API and have more than 50 locations configured for your store, you might be affected. For more details on how pagination works, see here.

The REST Admin API now disallows requests to either create or update order risks without specifying an order ID.

Previously, the REST Admin API allowed you to create OrderRisk models using order_id: null. This could have been used to create checkout order risks that exist prior to creating the order and block checkout. External apps do not use this feature.

This change is not breaking.

As of Admin API version 2022-10, a new field marketing_sms_consent_enabled_at_checkout has been added to the Shop object in the REST Admin APIs.

The field is also present on the "shop/update" webhook, which now will trigger when the marketing_sms_consent_enabled_at_checkout state of a shop changes.

As of GraphQL Admin API version 2022-10, you will get access to new fields and mutations for draft orders.

In particular, you will now be able to: - Duplicate drafts - Creating drafts from orders - Execute bulk operations such as add/remove tags and deleting drafts - Create drafts with inventory reservations - Access previously hidden fields, such as metafields, on drafts and line items

Learn more about DraftOrderCreate.

As of GraphQL Admin API version 2022-10, you can use the purchasing entity input field to create and update B2B draft orders.

This will attach company, location and contact to the draft order.

The field can also be used to create and update a traditional D2C draft order, requiring only a customer ID.

Learn more about PurchasingEntityInput.

As of GraphQL Admin API version 2022-10, we are adding queries, objects, and mutations to introspect and manage B2B primitives notably Companies, Company Locations, and Company Contacts with associated Roles. Learn more about B2B on Shopify.dev.

As of GraphQL Admin API version 2022-10, we are adding mutations so you can manage your locations using GraphQL. This will allow you to add, edit, deactivate, re-activate and delete locations.

Learn more about Locations on Shopify.dev.

As of GraphQL Admin API version 2022-10, you can now use marketingActivityCreateExternal and marketingActivityUpdateExternal mutations to create and manage marketing activities, without the need to implement a marketing activity app extension.

These endpoints will allow our app partners to more easily link their marketing efforts, and accompanying tracking information to Shopify so our merchants can have a more complete picture of their marketing performance.

As of GraphQL Admin API version 2022-10, we've introduced Subscription Billing Cycles to the existing Subscriptions Contract APIs so that you can make changes to an upcoming order without affecting the base subscription contract.

This includes: * The ability to skip a future order. * The ability to make changes to the line items of an upcoming order, including any additions, quantity changes, or removals. * The ability to combine the orders of one or more subscriptions contracts in order to save on shipping costs.

Please note that with the introduction of Subscriptions Billing Cycles API, SubscriptionBillingAttemptCreate will create a billing attempt for the billing cycle at the origin_time if specified. Otherwise, it will be created for the current billing cycle by default.

Alternatively, you can also use BillingCycleSelector to select the billing cycle you wish to create billing attempt for.

Learn more about the API on Shopify.dev.

As of the 2022-10 release, APIs will redact customer personal data by default and you will be able to request access to protected customer data and protected customer fields through your Partner Dashboard. You will need approval to access protected customer data on any store that isn't a development store.

Apps that require protected customer data (data that relates directly to a customer or prospective customer) must implement our data protection requirements, including informing merchants of your app’s data use and purpose, applying customer consent decisions, opt-out requests, and more.

Apps that require protected customer fields (individual configuration and approval) in addition to approval for protected customer data will need to abide by additional requirements, including encrypting your data back ups, keeping test and production data separate, and more.

For more information, please visit our developer documentation.

As of GraphQL Admin API version 2022-10, we’ve added full support for markets and multi-currency on draft orders.

You will now be able to specify the market region that should apply to a draft order, inheriting your configured market settings such as pricing. The selected market region’s attributes will be available on their respective objects.

Additionally, we have built out full support for multi-currency in draft orders. You will now be able to query a new set of fields that expose all monetary values relevant to a draft order in multi-currency. As part of these changes, you will now be able to use all draft order payment completion flows in multi-currency.

Learn more about these fields on DraftOrder, DraftOrderLineItem, DraftOrderAppliedDiscount, DraftOrderInput, CalculatedDraftOrder and CalculatedDraftOrderLineItem reference docs.