2022-04 release notes

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

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

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

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

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

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

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.

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

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.

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 object
• minDeliveryDateTime field was added to DeliveryMethod object

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

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

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

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.

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

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

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

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

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

New object

• StaffMember object was added

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

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

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 enum

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

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

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

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

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

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

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

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.

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

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

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

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

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

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

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

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