2022-04 release notes

The 2022-04 version of Shopify's APIs includes new ways to search and filter customers using customer segments, organize products on storefronts, and manage fulfillment and shipping for specific delivery expectations.

The 2022-04 version of Shopify's APIs also includes new ways to manage app subscription discounts, and provides new Storefront API functionality that enables you to retrieve information about delivery methods.

What's new in 2022-04

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

GraphQL Admin API changes:

• Read and modify a new API_PERMISSION metafield owner type.

• Categorize apps using the AppPublicCategory enum from the publicCategory field that was added to the App object.

• Give limited-time discounts on app charges using subscription discounts.

• Issue prorated credits for the unused portion of an app subscription by using the appSubscriptionCancel mutation.

• Search and filter a shop's customers using customer segments.

• Retrieve, add, and update the details about a customer's consent to receive marketing material by email using the emailMarketingConsent field on the CustomerInput input object.

• Embed and retrieve the origin of videos that are hosted outside of Shopify by using the embedUrl field from the ExternalVideo object.

• Retrieve the range of time that a delivery is expected to be completed by using the maxDeliveryDateTime and minDeliveryDateTime fields that were added to the DeliveryMethod object.

• Retrieve the latest date and time that items in a fulfillment order need to be fulfilled by using the fulfillBy field on the FulfillmentOrder object.

• Create, update, and delete markets and their settings by using the Market object.

• Retrieve product taxonomy nodes using the productTaxonomyNodes connection.

• Retrieve attributes of different media types by using the originalFileSize field on the GenericFile, MediaImage, and Video objects, or by using the duration field on a Video object.

• Apps installed on Shopify Plus can retrieve information about store staff member Shopify accounts using the StaffMember object.

• Identify the sales channel that an order came from by using the ChannelInformation object.

• Add custom attributes to subscriptions by using the SubscriptionDraft and SubscriptionContract objects.

• Calculate fulfillment intervals regardless of whether the attempt to create billing for a subscription was successful by using the originTime field that was added to the SubscriptionBillingAttempt object and the SubscriptionBillingAttemptInput input object.

  GraphQL Storefront API changes:

• Query a group of delivery options that are available for the line items in a cart, based on the specified shipping address, by using the deliveryGroups connection on the Cart object.

• Retrieve SEO information associated with a collection by using the seo field on the Collection object.

• Embed and retrieve the origin of videos that are hosted outside of Shopify by using the originURL and embedUrl fields on the ExternalVideo object.

• Support multiple languages on storefronts by using the Language object.

• Replicate a merchant's online store navigation menu on custom storefronts by using the menu query.

• Query Shopify-hosted videos and generic files that are referenced by a metafield in a shop by using the MetafieldReference union.

• Query the ID of a shop by using the id field in the Shop object.

  GraphQL Payments Apps API changes:

• Mark a payment as pending by using the paymentSessionPending mutation.

  REST Admin API changes

• Customer saved searches are deprecated. Use the GraphQL customer Segment object instead.

• Retrieve the range of time that a delivery is expected to be completed, and the latest date and time when all items in a fulfillment order need to be fulfilled, by using the FulfillmentOrder resource.

• Retrieve, add, and update information about a customer's consent to receive email marketing by using the email_marketing_consent field on the Customer resource.

• Identify the sales channel that an order came from by using the Checkout and Order resources.

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 Non-encoded object IDs in the GraphQL Storefront APINon-encoded object IDs in the GraphQL Storefront API

Most object types in Shopify's GraphQL APIs have an id field. The id field represents the globally-unique identifier for an individual record. Currently, Shopify serves Base64-encoded object IDs from the supported stable versions of the GraphQL Storefront API.

As of January 3, 2022, Shopify began serving non-encoded object IDs from the unstable version of the GraphQL Storefront API. The 2022-04 release is the first stable version that doesn't serve Base64-encoded object IDs.

If you're caching, persisting to a database, or parsing IDs, then you need to migrate your app.

Anchor to Saved searches elements removed from the GraphQL Admin APISaved searches elements removed from the GraphQL Admin API

You can no longer use the following mutations on the customerSavedSearches query in the GraphQL Admin API:

• SavedSearchCreate

• SavedSearchDelete

• SavedSearchUpdate

  Use the following mutations instead:

• SegmentCreate

• SegmentDelete

• SegmentUpdate

Anchor to Saved searches elements removed from the REST Admin APISaved searches elements removed from the REST Admin API

The following endpoints were removed from the CustomerSavedSearch resource in the REST Admin API:

• search

• count

• create

• destroy

• index

• show

• update

  Use the following endpoints instead:

• Instead of search, use customerSegmentMembers

• Instead of count, use segmentCount

• Instead of create, use segmentCreate

• Instead of destroy, use segmentDelete

• Instead of show, use segment

• Instead of update, use segmentUpdate

Anchor to Saved search discount elements removed from the GraphQL Admin APISaved search discount elements removed from the GraphQL Admin API

The following types were removed from the GraphQL Admin API:

• DiscountCustomerSavedSearches object

• DiscountCustomerSavedSearchesInput input object

  Use the following elements instead:

• DiscountCustomerSegments object

• DiscountCustomerSegmentsInput input object

Anchor to Saved search fields and properties removed from price rule elements in the GraphQL Admin APISaved search fields and properties removed from price rule elements in the GraphQL Admin API

The following fields were removed from the GraphQL Admin API:

• savedSearches field from the PriceRuleCustomerSelection object

• savedSearchesIds field from the PriceRuleCustomerSelectionInput input object

  Use the following fields instead:

• segments field from the PriceRuleCustomerSelection object

• segmentIds field from the PriceRuleCustomerSelectionInput input object

Anchor to Saved search property removed from PriceRule element in the GraphQL Admin APISaved search property removed from PriceRule element in the GraphQL Admin API

The prerequisite_saved_search_ids property from the PriceRule resource in the REST Admin API is deprecated. Use the customer_segment_prerequisite_ids from the PriceRule resource instead.

Anchor to Deprecated ,[object Object], field in the GraphQL Admin APIDeprecated countries field in the GraphQL Admin API

As of API version 2022-04, the countries field on the PriceListContextRuleInput input object is deprecated. Use the marketId field instead.

Anchor to Deprecated fields on the ,[object Object], object in the GraphQL Admin APIDeprecated fields on the Customer object in the GraphQL Admin API

As of API version 2022-04, the following fields on the Customer object are deprecated:

• The totalSpent and totalSpentV2 fields were removed. Use the amountSpent field instead.
• The ordersCount field was removed. Use the numberOfOrders field instead.
• The hasNote field was removed. The note field is still in use.
• The hasTimelineComment field was removed. Use the events connection and a query argument containing verb:comment, or look for a CommentEvent in the __typename of events.

Anchor to Deprecated ,[object Object], field in the GraphQL Payment Apps APIDeprecated status field in the GraphQL Payment Apps API

As of API version 2022-04, the status field on the PaymentSession, RefundSession, CaptureSession, and VoidSession objects is deprecated. Use the state field instead.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

Below are all the changes currently introduced in the 2022-04 version of the GraphQL Admin API.

Anchor to API permission owner type for metafields,[object Object]API permission owner type for metafields

As of API version 2022-04, a new API_PERMISSION owner type is available for metafields. A metafield with this permission type is only readable and writable by the app that owns the metafield.

New value

• API_PERMISSION value was added to MetafieldOwnerType enum

  New type

• HasMetafields interface was added to AppInstallation object

Anchor to App fields and public category,[object Object]App fields and public category

As of API version 2022-04, the App object includes several new fields, including the publicCategory field. The publicCategory field introduces the AppPublicCategory enum, which represents the public-facing category for an app.

New fields

• publicCategory field was added to App object

• previouslyInstalled field was added to App object

• webhookApiVersion field was added to App object

• requestedAccessScopes field was added to App object

• availableAccessScopes field was added to App object

• developerType field was added to App object

  New types

• AppPublicCategory enum was added

Anchor to App subscription billing discounts,[object Object]App subscription billing discounts

As of API version 2022-04, you can use the GraphQL Admin API to offer limited-time discounts on recurring app charges using the Billing API. You can define either a percentage or a fixed amount discount, which is applied to a designated number of billing intervals. For example, you can apply a 20% discount to six billing cycles.

Learn more about app billing discounts.

New types

• AppRecurringPricing object was added

• AppRecurringPricingInput input object was added

• AppSubscriptionDiscount object was added

• AppSubscriptionDiscountAmount object was added

• AppSubscriptionDiscountInput input object was added

• AppSubscriptionDiscountPercentage object was added

• AppSubscriptionDiscountValueInput input object was added

• AppSubscriptionDiscountValue union was added

  New fields

• discount_value field was added to InvoiceCharge object

Anchor to App subscription prorate,[object Object]App subscription prorate

As of API version 2022-04, you can issue prorated credits for the unused portion of an app subscription when using the appSubscriptionCancel mutation.

New argument

• prorate argument was added to appSubscriptionCancel mutation

Anchor to Customer segmentationCustomer segmentation

Anchor to BreakingBreaking

As of API version 2022-04, you can use the GraphQL Admin API to search and filter customers using customer segments.

For details about the breaking changes that were introduced in this API version, refer to Breaking changes.

Removed fields

• savedSearches field was removed from PriceRuleCustomerSelection object

• savedSearchesIds field was removed from PriceRuleCustomerSelectionInput input object

  Removed types

• DiscountCustomerSavedSearches object was removed

• DiscountCustomerSavedSearchesInput input object was removed

  New mutations

• SegmentCreate mutation was added

• SegmentDelete mutation was added

• SegmentUpdate mutation was added

  New types

• SegmentAssociationFilterValue object was added

• SegmentAssociationFilter object was added

• SegmentAttributeStatistics object was added

• SegmentBooleanFilter object was added

• CustomerEmailAddress object was added

• CustomerPhoneNumber object was added

• SegmentDateFilter object was added

• DiscountCustomerSegmentsInput object was added

• DiscountCustomerSegments object was added

• DiscountCustomerSegments type was added to DiscountCustomerSelection union

• SegmentEnumFilterValue object was added

• SegmentEnumFilter object was added

• SegmentEventFilterValue object was added

• SegmentEventFilter object was added

• SegmentFloatFilter object was added

• SegmentIntegerFilter object was added

• SegmentFilter interface was added

• CustomerSegmentMember object was added

• SegmentMigration object was added

• SegmentValue object was added

• Segment object was added

• SegmentMembership object was added

• SegmentMembershipResponse object was added

• SegmentStatistics object was added

• SegmentStringFilterValue object was added

• SegmentStringFilter object was added

  New values

• BOTH_CUSTOMER_AND_SEGMENT_PREREQUISITES_SELECTED value was added to PriceRuleErrorCode enum

• BOTH_SAVED_SEARCH_AND_SEGMENT_PREREQUISITES_SELECTED value was added to PriceRuleErrorCode enum

• CUSTOMER_SEGMENT_EXCEEDED_MAX value was added to PriceRuleErrorCode enum

• CUSTOMER_SEGMENT_INVALID value was added to PriceRuleErrorCode enum

• CUSTOMER_SEGMENT_PREREQUISITE_DUPLICATE value was added to PriceRuleErrorCode enum

• CREATED_AT value was added to CustomerSortKeys enum

  New fields

• customerSegments field was added to DiscountCustomerSelectionInput input object

• customerSegmentMembership field was added to QueryRoot object

• segmentCount field was added to QueryRoot object

• segmentIds field was added to PriceRuleCustomerSelectionInput input object

• segment field was added to QueryRoot object

• segments field was added to PriceRuleCustomerSelection object

• unsubscribeUrl field was added to Customer object

  New connections

• CustomerSegmentMemberConnection connection was added to CustomerSegmentMember object

• segmentFilterSuggestions connection was added to QueryRoot object

• segmentFilters connection was added to QueryRoot object

• customerSegmentMembers connection was added to QueryRoot object

• segmentMigrations connection was added to QueryRoot object

• segmentValueSuggestions connection was added to QueryRoot object

• segments connection was added to QueryRoot object

Anchor to Deprecated countries fieldDeprecated countries field

Anchor to BreakingBreaking

As of API version 2022-04, the countries field on the PriceListContextRuleInput input object is deprecated. Use the marketId field instead.

Removed fields

• countries field was removed from PriceListContextRuleInput

Anchor to Deprecated fields on CustomerDeprecated fields on Customer

Anchor to BreakingBreaking

As of API version 2022-04, several fields are removed from the Customer object.

Removed fields

• totalSpent and totalSpentV2 fields were removed. Use the amountSpent field instead.
• ordersCount field was removed. Use the amountSpent field instead.
• hasNote field was removed. The note field is still in use.
• hasTimelineComment field was removed. Use the events connection and a query argument containing verb:comment, or look for a CommentEvent in the __typename of events.

Anchor to Email marketing consent,[object Object]Email marketing consent

As of API version 2022-04 you can use the GraphQL Admin API to retrieve, add, and update the details about a customer's consent to receive marketing material by email using channel-specific fields. You can also subscribe to the CUSTOMERS_MARKETING_CONSENT_UPDATE webhook topic to get notified when a customer updates their marketing consent.

The acceptsMarketing, acceptsMarketingUpdatedAt, and marketingOptInLevel fields on the Customer object and CustomerInput input object are deprecated. Use the emailMarketingConsent field on the CustomerInput input object instead.

Deprecated fields

• acceptsMarketing field is deprecated on Customerobject and CustomerInput input object

• acceptsMarketingUpdatedAt field is deprecated on Customerobject and CustomerInput input object

• marketingOptInLevel field is deprecated on Customerobject and CustomerInput input object

  New types

• CustomerEmailMarketingConsentState object was added

• CustomerEmailMarketingConsentInput input object was added

• CustomerEmailMarketingConsentUpdateInput input object was added

• CustomerEmailAddressMarketingState enum was added

• CustomerEmailMarketingConsentUpdateUserErrorCode enum was added

• CustomerEmailMarketingState enum was added

• CustomerEmailMarketingConsentUpdatePayload payload was added

  New mutation

• customerEmailMarketingConsentUpdate mutation was added

  New fields

• emailMarketingConsent field was added to Customer object

• emailMarketingConsent field was added to CustomerInput input object, for customerCreate and customerUpdate mutations

Anchor to Error codes for translation,[object Object]Error codes for translation

As of API version 2022-04, the INVALID_LOCALE_FOR_SHOP error code on the TranslationErrorCode enum is used to represent all errors related to the locale field on the Translation object. Previous versions use INVALID_CODE for the same errors.

Anchor to Externally-hosted videos,[object Object]Externally-hosted videos

As of API version 2022-04, you can use the GraphQL Admin API to query the origin and embed URLs of videos hosted outside of Shopify.

New fields

• originUrl field was added to ExternalVideo object

• embedUrl field was added to ExternalVideo object

Anchor to Fulfillment: Delivery time,[object Object]Fulfillment: Delivery time

As of API version 2022-04, you can use the GraphQL Admin API to query a range of time when a delivery is expected to be completed.

New fields

• maxDeliveryDateTime field was added to DeliveryMethod object
• minDeliveryDateTime field was added to DeliveryMethod object

Anchor to Fulfillment: Fulfillment time,[object Object]Fulfillment: Fulfillment time

As of API version 2022-04, you can use the GraphQL Admin API to query the latest date and time when all items in a fulfillment order need to be fulfilled.

New fields

• fulfillBy field was added to FulfillmentOrder object

Anchor to Markets ,[object Object]Markets

As of API version 2022-04, you can use the GraphQL Admin API to create, update, and delete markets and their settings. A market is a group of one or more regions that you want to target for international sales.

New fields

• alternateLocales field was added to MarketWebPresence object

• baseCurrency field was added to MarketCurrencySettings object

• code field was added to MarketRegionCountry object

• currencySettings field was added to Market object

• defaultLocale field was added to MarketWebPresence object

• domain field was added to MarketWebPresence object

• enabled field was added to Market object

• localCurrencies field was added to MarketCurrencySettings object

• locale field was added to MarketWebPresenceRootUrl object

• id field was added to Market object

• id field was added to MarketRegionCountry object

• id field was added to MarketWebPresence object

• market field was added to MarketWebPresence object

• market field was added to PriceListContextRule object

• marketId field was added to PriceListContextRuleInput input object

• marketWebPresence field was added to Domain object

• name field was added to MarketRegionCountry object

• pricelist field was added to Market object

• primary field was added to Market object

• rootUrls field was added to MarketWebPresence object

• subfolderSuffix field was added to MarketWebPresence object

• url field was added to MarketWebPresenceRootUrl object

• webPresence field was added to Market object

  New connections

• regions connection was added to Market object

  New mutations

• marketCreate mutation was added

• marketDelete mutation was added

• marketCurrencySettingsUpdate mutation was added

• marketRegionDelete mutation was added

• marketRegionCreate mutation was added

• marketRegionsCreate mutation was added

• marketUpdate mutation was added

• marketWebPresenceCreate mutation was added

• marketWebPresenceDelete mutation was added

• marketWebPresenceUpdate mutation was added

  New error codes

• CURRENCY_MARKET_MISMATCH error code was added to PriceListUserError user error

• MARKET_CURRENCY_MISMATCH error code was added to PriceListUserError user error

• CONTEXT_RULE_LIMIT_ONE_OPTION error code was added to PriceListUserError user error

• CONTEXT_RULE_MARKET_NOT_FOUND error code was added to PriceListUserError user error

• CONTEXT_RULE_MARKET_TAKEN error code was added to PriceListUserError user error

• CURRENCY_NOT_SUPPORTED error code was added to PriceListUserError user error

• PRICE_LIST_NOT_ALLOWED_FOR_PRIMARY_MARKET error code was added to PriceListUserError user error

  New types

• CurrencySettings object was added to Market object

• CurrencySettingsUpdateInput input object was added to Market object

• Market object was added

• MarketCurrencySettingsUserError user error was added

• MarketCreateInput input object was added

• MarketRegionCountry object was added

• MarketUserError user error was added

• MarketWebPresenceRootUrl object was added

• RegionCreateInput input object was added to Market object

• WebPresence object was added to Market object

• WebPresenceCreateInput input object was added to Market object

• WebPresenceUpdateInput input object was added to Market object

Anchor to Improvements to GraphQL connections,[object Object]Improvements to GraphQL connections

As of API version 2022-04, we've added a nodes field on the Connection object. When you only query node on edges, you can simplify the query. We've also added the startCursor and endCursor fields on the PageInfo object, which allows you to simplify the shape of return data for pagination.

For more information, refer to Paginating results with GraphQL.

New fields

• nodes field was added to Connection object
• startCursor field was added to PageInfo object
• endCursor field was added to PageInfo object

Anchor to Metafield definition visibility ,[object Object]Metafield definition visibility

To allow custom storefronts to display your metafields, you can now use the GraphQL Admin API to toggle Storefront API access to metafield definitions. Metafield definitions enable you to define additional validation constraints for metafields and edit metafield values in context. By default, values for metafields aren't accessible to custom storefronts.

Example use cases for accessing the Storefront API might include merchants who sell their Shopify products through a non-Shopify website, a video game, or another custom shopping experience.

New fields

visibleToStorefrontApi field was added to the following GraphQL Admin API resources:

• MetafieldDefinition object

• StandardMetafieldDefinitionTemplate object

• MetafieldDefinitionInput input object

• MetafieldDefinitionUpdateInput input object

• StandardMetafieldDefinitionEnable mutation

  Learn more about metafield definitions.

Anchor to Metafield definition error codes ,[object Object]Metafield definition error codes

As of API version 2022-04, we've added an error code that returns when a metafield definition is created with invalid characters in the key or namespace fields. The namespace and key fields can contain only alphanumeric characters, hyphens, and underscores.

New error code

• INVALID_CHARACTER error code was added to MetafieldDefinitionCreateUserErrorCode enum

Anchor to Metafield element index ,[object Object]Metafield element index

As of API version 2022-04, you can use the GraphQL Admin API to include the element index in metafield error messages when an array element fails validation.

New fields

• elementIndex field was added to MetafieldsSetUserError object

Anchor to Product taxonomy ,[object Object]Product taxonomy

You can now query the GraphQL Admin API to retrieve the nodes of a product taxonomy. This includes all of the standard and custom product types associated with a product.

New connection

• productTaxonomyNodes connection was added to QueryRoot

Anchor to Rich media enhancements ,[object Object]Rich media enhancements

As of API version 2022-04, you can use the GraphQL Admin API to query Shopify-hosted videos that are referenced by a metafield in a merchant's store. You can also query specific attributes of media types, such as the original file size of a generic file (for example, a .pdf or json file), media image, or video.

New types

• Video type was added to MetafieldReference union

• File interface type was added to Video object

  New fields

• previewImageSource field was added to FileUpdateInput input object

• originalFileSize field was added to GenericFile object

• originalFileSize field was added to MediaImage object

• originalFileSize field was added to Video object

• duration field was added to Video object

  New values

• VIDEO value was added to FileContentType enum

  New error codes

• NON_IMAGE_MEDIA_PER_SHOP_LIMIT_EXCEEDED error code was added to FilesUserError

Anchor to Staff member data,[object Object]Staff member data

You can now use the GraphQL Admin API to request data about store staff member Shopify accounts.

New object

• StaffMember object was added

Anchor to Sales channel attribution,[object Object]Sales channel attribution

As of API version 2022-04, you can use the GraphQL Admin API to identify the sales channel that an order came from. For example, you can now identify whether orders made through the Facebook channel app came from Facebook Marketplace, Instagram, or Messenger. Similarly, for orders made through connector apps, you can identify whether orders are attributable to specific sales channels rather than to the connector app.

For an order to be correctly attributed to a channel, you need to register the channels that your app manages. After your request has been processed, refer to the list of your registered channels in the Partner Dashboard, on the app's Marketplace extension. From there, set the specified handle as the source_name in your request.

New objects

• AvailableChannelDefinitionsByChannel object was added

• ChannelDefinition object was added

• ChannelInformation object was added

  New fields

• channelInformation field was added to Order object

• registeredSourceUrl field added to Order object

• sourceIdentifier field was added to Order object

• sourceName field was added to DraftOrderInput Input objecf

• channelDefinitionsforInstalledChannels field was added to Shop object

  New argument

• sourceName argument was added to DraftOrderComplete mutation

Anchor to Subscriptions: Custom attributes,[object Object]Subscriptions: Custom attributes

As of API version 2022-04, you can add custom attributes to a subscription draft or subscription contract. Custom attributes are copied to new orders that are generated from a subscription contract.

New fields

• customAttributes field was added to SubscriptionDraft object

• customAttributes field was added to SubscriptionDraftInput input object

• customAttributes field was added to SubscriptionContract object

Anchor to Subscriptions: Fulfillment intervals,[object Object]Subscriptions: Fulfillment intervals

When you create a subscription billing attempt, you can now calculate fulfillment intervals regardless of whether the attempt was successfully completed. This option prevents fulfillment from being pushed to the next anchor date when billing happens after the current anchor date.

New fields

• originTime field was added to SubscriptionBillingAttempt object

• originTime field was added to SubscriptionBillingAttemptInput object

Anchor to Subscriptions: Payment methods,[object Object]Subscriptions: Payment methods

As of API version 2022-04, the CustomerPaymentMethodRevocationReason enum includes a new value: MERGED. This value is assigned when a customer replaces a payment method with another existing payment method, leaving the revoked payment method with no associated subscription contracts. The associated subscription contracts are migrated to the other payment method.

New value

• MERGED value was added to CustomerPaymentMethodRevocationReason enum

Anchor to GraphQL Storefront API changesGraphQL Storefront API changes

Below are all the changes currently introduced in the 2022-04 version of the GraphQL Storefront API.

Anchor to Cart ,[object Object]Cart

As of API version 2022-04, you can use the GraphQL Storefront API to query a group of delivery options that are available for the line items in a cart, based on the specified shipping address.

Delivery groups are only available for logged-in customers that have a full default address.

Refer the cartCreate and customerCreate mutations to learn more about how to create a cart for a logged-in customer.

New types

• CartDeliveryGroup object was added
• CartDeliveryOption object was added
• deliveryGroups connection was added to Cart object
• DeliveryMethodType enum was added

Anchor to Collections ,[object Object]Collections

As of API version 2022-04, you can use the Storefront API to query SEO information associated with a collection.

New field

• seo field was added to Collection object

Anchor to Externally-hosted videos,[object Object]Externally-hosted videos

As of API version 2022-04, you can use the GraphQL Storefront API to query the origin and embed URLs of videos hosted outside of Shopify.

New field

• originUrl field was added to ExternalVideo object

• embedUrl field was added to ExternalVideo object

Anchor to Filtering data ,[object Object]Filtering data

As of API version 2022-04, the Storefront API includes a BOOLEAN value on the FilterType enum. The BOOLEAN value is assigned when a filter is based off of a boolean metafield type.

New value

• BOOLEAN value was added to FilterType enum

Anchor to Improvements to GraphQL connections,[object Object]Improvements to GraphQL connections

As of API version 2022-04, we've added a nodes field on the Connection object. When you only query node on edges, you can simplify the query. We've also added the startCursor and endCursor fields on the PageInfo object, which allows you to simplify the shape of return data for pagination.

For more information, refer to Paginating results with GraphQL.

New fields

• nodes field was added to Connection object
• startCursor field was added to PageInfo object
• endCursor field was added to PageInfo object

Anchor to Languages ,[object Object]Languages

As of API version 2022-04, you can use the inContext directive to contextualize any query in one of the shop's available languages. You can configure the languages available for each country context within the shop’s Markets settings. You can access a list of available languages using the Localization object.

For more information, refer to Support multiple languages on storefronts.

New type

• Language object was added

  New fields

• availableLanguages field was added to Country object

• availableLanguages field was added to Localization object

• language field was added to Localization object

  New argument

• language argument was added to InContext directive

Anchor to Navigation menu ,[object Object]Navigation menu

As of API version 2022-04, you can use the Storefront API to query a navigation menu by its handle. The menu field returns a Menu object, and can be used to replicate a merchant's online store navigation menu on custom storefronts.

New types

• Menu object was added

• MenuItem object was added

• MenuItemType enum was added

  New field

• menu field was added to QueryRoot object

Anchor to Non-encoded object IDsNon-encoded object IDs

Anchor to BreakingBreaking

Most object types in Shopify's GraphQL APIs have an id field. The id field represents the globally-unique identifier for an individual record. Currently, Shopify serves Base64-encoded object IDs from the supported stable versions of the GraphQL Storefront API.

As of January 3, 2022, Shopify began serving non-encoded object IDs from the unstable version of the GraphQL Storefront API. The 2022-04 release is the first stable version that doesn't serve Base64-encoded object IDs.

If you're caching, persisting to a database, or parsing IDs, then you need to migrate your app.

Anchor to Rich media enhancements ,[object Object]Rich media enhancements

As of API version 2022-04, you can use the GraphQL Storefront API to query Shopify-hosted videos and generic files (for example, .pdf and .json files) that are referenced by a metafield in a merchant's store.

New types

• GenericFile was added
• GenericFile type was added to MetafieldReference union
• Video type was added to MetafieldReference union

Anchor to Shop ID ,[object Object]Shop ID

As of API version 2022-04, you can use the GraphQL Storefront API to query the ID of a shop.

New field

• id field was added to Shop object

Anchor to GraphQL Payments Apps API changesGraphQL Payments Apps API changes

Below are all the changes currently introduced in the 2022-04 version of the GraphQL Payments Apps API.

Anchor to Deprecated status fieldDeprecated status field

Anchor to BreakingBreaking

As of API version 2022-04, the status field on the PaymentSession, RefundSession, CaptureSession, and VoidSession objects is deprecated. Use the state field instead.

Removed fields

• status field was removed from PaymentSession object

• status field was removed from RefundSession object

• status field was removed from CaptureSession object

• status field was removed from VoidSession object

  New fields

• state field was added to PaymentSession object

• state field was added to RefundSession object

• state field was added to CaptureSession object

• state field was added to VoidSession object

Anchor to Pending payments ,[object Object]Pending payments

As of API version 2022-04, you can use the GraphQL Payments Apps API to mark an offsite payment as pending. You can mark a payment as pending if the payment can't be completed within a reasonable amount of time. This means that customers won't need to wait for slow transactions to finish before their order is completed.

New types

• paymentSessionPending mutation was added

• PaymentSessionPendingUserError object was added

• PENDING value was added to PaymentSessionStatusCode enum

  New arguments

• pendingExpiresAt argument was added to paymentSessionPending mutation

• reason argument was added to paymentSessionPending mutation

Anchor to REST Admin API changesREST Admin API changes

Below are all the changes currently introduced in the 2022-04 version of the REST Admin API.

Anchor to Customer segmentationCustomer segmentation

Anchor to BreakingBreaking

As of API version 2022-04, you can use the REST Admin API to search for customers using filters.

For details about the breaking changes that were introduced in this API version, refer to Breaking changes.

Removed endpoints

• count endpoint was removed from CustomerSavedSearch resource

• create endpoint was removed from CustomerSavedSearch resource

• destroy endpoint was removed from CustomerSavedSearch resource

• index endpoint was removed from CustomerSavedSearch resource

• search endpoint was removed from CustomerSavedSearch resource

• show endpoint was removed from CustomerSavedSearch resource

• update endpoint was removed from CustomerSavedSearch resource

  Removed properties

• prerequisite_saved_search_ids property was removed from PriceRule resource

  New properties

• customer_segment_prerequisite_ids property was added to PriceRule resource

Anchor to Delivery and fulfillment time,[object Object]Delivery and fulfillment time

As of API version 2022-04, you can use the REST Admin API to query the following information:

• A range of time when a delivery is expected to be completed

• The latest date and time when all items in a fulfillment order need to be fulfilled

  New properties

• delivery_method.max_delivery_date_time property was added to FulfillmentOrder resource

• delivery_method.min_delivery_date_time property was added to FulfillmentOrder resource

• fulfill_by property was added to FulfillmentOrder resource

Anchor to Email marketing consent,[object Object]Email marketing consent

As of API version 2022-04, you can use the REST Admin API to retrieve, add, and update the details about a customer's consent to receive marketing material by email using channel-specific fields. You can also subscribe to the customers_marketing_consent/update webhook topic to get notified when a customer updates their marketing consent.

The accepts_marketing, accepts_marketing_updated_at, and marketing_opt_in_level properties on the Customer resource are deprecated. Use the email_marketing_consent property instead.

Deprecated properties

• accepts_marketing property is deprecated on Customer resource

• accepts_marketing_updated_at property is deprecated on Customer resource

• marketing_opt_in_level property is deprecated on Customer resource

  New property

• email_marketing_consent property was added to Customer resource

Anchor to Sales channel attribution,[object Object]Sales channel attribution

As of API version 2022-04, you can use the REST Admin API Checkout and Order resources to identify the sales channel that an order came from. For example, you can identify whether orders made through the Facebook channel app came from Facebook Marketplace, Instagram, or Messenger. Similarly, for orders made through connector apps, you can identify whether orders are attributable to specific sales channels rather than to the connector app.

For an order to be correctly attributed to a channel, you need to register the channels that your app manages. After your request has been processed, refer to the list of your registered channels in the Partner Dashboard, on the app's Marketplace extension. From there, set the specified handle as the source_name in your request.

New properties

• source_identifier was added to Checkout resource

• source_identifier was added to Order resource

• source_name was added to Checkout resource

• source_url was added to Checkout resource

• source_url was added to Order resource