| Release date | Date version is no longer supported |
|---|---|
| April 1, 2022 | July 5, 2023 |
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 enumNew type
HasMetafields interface was added to AppInstallation objectAs 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 objectpreviouslyInstalled field was added to App objectwebhookApiVersion field was added to App objectrequestedAccessScopes field was added to App objectavailableAccessScopes field was added to App objectdeveloperType field was added to App objectNew types
AppPublicCategory enum was addedAs 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 objectAs 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 mutationAs 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 objectsavedSearchesIds field was removed from PriceRuleCustomerSelectionInput input objectRemoved types
DiscountCustomerSavedSearches object was removedDiscountCustomerSavedSearchesInput input object was removedNew mutations
SegmentCreate mutation was addedSegmentDelete mutation was addedSegmentUpdate mutation was addedNew types
SegmentAssociationFilterValue object was addedSegmentAssociationFilter object was addedSegmentAttributeStatistics object was addedSegmentBooleanFilter object was addedCustomerEmailAddress object was addedCustomerPhoneNumber object was addedSegmentDateFilter object was addedDiscountCustomerSegmentsInput object was addedDiscountCustomerSegments object was addedDiscountCustomerSegments type was added to DiscountCustomerSelection unionSegmentEnumFilterValue object was addedSegmentEnumFilter object was addedSegmentEventFilterValue object was addedSegmentEventFilter object was addedSegmentFloatFilter object was addedSegmentIntegerFilter object was addedSegmentFilter interface was addedCustomerSegmentMember object was addedSegmentMigration object was addedSegmentValue object was addedSegment object was addedSegmentMembership object was addedSegmentMembershipResponse object was addedSegmentStatistics object was addedSegmentStringFilterValue object was addedSegmentStringFilter object was addedNew values
BOTH_CUSTOMER_AND_SEGMENT_PREREQUISITES_SELECTED value was added to PriceRuleErrorCode enumBOTH_SAVED_SEARCH_AND_SEGMENT_PREREQUISITES_SELECTED value was added to PriceRuleErrorCode enumCUSTOMER_SEGMENT_EXCEEDED_MAX value was added to PriceRuleErrorCode enumCUSTOMER_SEGMENT_INVALID value was added to PriceRuleErrorCode enumCUSTOMER_SEGMENT_PREREQUISITE_DUPLICATE value was added to PriceRuleErrorCode enumCREATED_AT value was added to CustomerSortKeys enumNew fields
customerSegments field was added to DiscountCustomerSelectionInput input objectcustomerSegmentMembership field was added to QueryRoot objectsegmentCount field was added to QueryRoot objectsegmentIds field was added to PriceRuleCustomerSelectionInput input objectsegment field was added to QueryRoot objectsegments field was added to PriceRuleCustomerSelection objectunsubscribeUrl field was added to Customer objectNew connections
CustomerSegmentMemberConnection connection was added to CustomerSegmentMember objectsegmentFilterSuggestions connection was added to QueryRoot objectsegmentFilters connection was added to QueryRoot objectcustomerSegmentMembers connection was added to QueryRoot objectsegmentMigrations connection was added to QueryRoot objectsegmentValueSuggestions connection was added to QueryRoot objectsegments connection was added to QueryRoot objectAs 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 PriceListContextRuleInputAs 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.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 objectacceptsMarketingUpdatedAt field is deprecated on Customerobject and CustomerInput input objectmarketingOptInLevel field is deprecated on Customerobject and CustomerInput input objectNew types
CustomerEmailMarketingConsentState object was addedCustomerEmailMarketingConsentInput input object was addedCustomerEmailMarketingConsentUpdateInput input object was addedCustomerEmailAddressMarketingState enum was addedCustomerEmailMarketingConsentUpdateUserErrorCode enum was addedCustomerEmailMarketingState enum was addedCustomerEmailMarketingConsentUpdatePayload payload was addedNew mutation
customerEmailMarketingConsentUpdate mutation was addedNew fields
emailMarketingConsent field was added to Customer objectemailMarketingConsent field was added to CustomerInput input object, for customerCreate and customerUpdate mutationsAs 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.
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
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 objectminDeliveryDateTime field was added to DeliveryMethod objectAs 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 objectAs 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 objectbaseCurrency field was added to MarketCurrencySettings objectcode field was added to MarketRegionCountry objectcurrencySettings field was added to Market objectdefaultLocale field was added to MarketWebPresence objectdomain field was added to MarketWebPresence objectenabled field was added to Market objectlocalCurrencies field was added to MarketCurrencySettings objectlocale field was added to MarketWebPresenceRootUrl objectid field was added to Market objectid field was added to MarketRegionCountry objectid field was added to MarketWebPresence objectmarket field was added to MarketWebPresence objectmarket field was added to PriceListContextRule objectmarketId field was added to PriceListContextRuleInput input objectmarketWebPresence field was added to Domain objectname field was added to MarketRegionCountry objectpricelist field was added to Market objectprimary field was added to Market objectrootUrls field was added to MarketWebPresence objectsubfolderSuffix field was added to MarketWebPresence objecturl field was added to MarketWebPresenceRootUrl objectwebPresence field was added to Market objectNew connections
regions connection was added to Market objectNew mutations
marketCreate mutation was addedmarketDelete mutation was addedmarketCurrencySettingsUpdate mutation was addedmarketRegionDelete mutation was addedmarketRegionCreate mutation was addedmarketRegionsCreate mutation was addedmarketUpdate mutation was addedmarketWebPresenceCreate mutation was addedmarketWebPresenceDelete mutation was addedmarketWebPresenceUpdate mutation was addedNew error codes
CURRENCY_MARKET_MISMATCH error code was added to PriceListUserError user errorMARKET_CURRENCY_MISMATCH error code was added to PriceListUserError user errorCONTEXT_RULE_LIMIT_ONE_OPTION error code was added to PriceListUserError user errorCONTEXT_RULE_MARKET_NOT_FOUND error code was added to PriceListUserError user errorCONTEXT_RULE_MARKET_TAKEN error code was added to PriceListUserError user errorCURRENCY_NOT_SUPPORTED error code was added to PriceListUserError user errorPRICE_LIST_NOT_ALLOWED_FOR_PRIMARY_MARKET error code was added to PriceListUserError user errorNew types
CurrencySettings object was added to Market objectCurrencySettingsUpdateInput input object was added to Market objectMarket object was addedMarketCurrencySettingsUserError user error was addedMarketCreateInput input object was addedMarketRegionCountry object was addedMarketUserError user error was addedMarketWebPresenceRootUrl object was addedRegionCreateInput input object was added to Market objectWebPresence object was added to Market objectWebPresenceCreateInput input object was added to Market objectWebPresenceUpdateInput input object was added to Market objectAs 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 objectstartCursor field was added to PageInfo objectendCursor field was added to PageInfo objectTo 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
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 enumAs 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 objectYou 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 QueryRootAs 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 unionFile interface type was added to Video objectNew fields
previewImageSource field was added to FileUpdateInput input objectoriginalFileSize field was added to GenericFile objectoriginalFileSize field was added to MediaImage objectoriginalFileSize field was added to Video objectduration field was added to Video objectNew values
VIDEO value was added to FileContentType enumNew error codes
NON_IMAGE_MEDIA_PER_SHOP_LIMIT_EXCEEDED error code was added to FilesUserErrorYou can now use the GraphQL Admin API to request data about store staff member Shopify accounts.
New object
StaffMember object was addedAs 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 mutationAs 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
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
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 enumAs 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 addedCartDeliveryOption object was addeddeliveryGroups connection was added to Cart objectDeliveryMethodType enum was addedAs 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 objectAs 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
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 enumAs 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 objectstartCursor field was added to PageInfo objectendCursor field was added to PageInfo objectAs 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 addedNew fields
availableLanguages field was added to Country objectavailableLanguages field was added to Localization objectlanguage field was added to Localization objectNew argument
language argument was added to InContext directiveAs 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 addedMenuItem object was addedMenuItemType enum was addedNew field
menu field was added to QueryRoot objectMost 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.
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 addedGenericFile type was added to MetafieldReference unionVideo type was added to MetafieldReference unionAs 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 objectAs 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 objectstatus field was removed from RefundSession objectstatus field was removed from CaptureSession objectstatus field was removed from VoidSession objectNew fields
state field was added to PaymentSession objectstate field was added to RefundSession objectstate field was added to CaptureSession objectstate field was added to VoidSession objectAs 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 addedPaymentSessionPendingUserError object was addedPENDING value was added to PaymentSessionStatusCode enumNew arguments
pendingExpiresAt argument was added to paymentSessionPending mutationreason argument was added to paymentSessionPending mutationAs 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 resourcecreate endpoint was removed from CustomerSavedSearch resourcedestroy endpoint was removed from CustomerSavedSearch resourceindex endpoint was removed from CustomerSavedSearch resourcesearch endpoint was removed from CustomerSavedSearch resourceshow endpoint was removed from CustomerSavedSearch resourceupdate endpoint was removed from CustomerSavedSearch resourceRemoved properties
prerequisite_saved_search_ids property was removed from PriceRule resourceNew properties
customer_segment_prerequisite_ids property was added to PriceRule resourceAs of API version 2022-04, you can use the REST Admin API to query the following information:
New properties
delivery_method.max_delivery_date_time property was added to FulfillmentOrder resourcedelivery_method.min_delivery_date_time property was added to FulfillmentOrder resourcefulfill_by property was added to FulfillmentOrder resourceAs 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 resourceaccepts_marketing_updated_at property is deprecated on Customer resourcemarketing_opt_in_level property is deprecated on Customer resourceNew property
email_marketing_consent property was added to Customer resourceAs 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