---
title: '2025-04: Release notes'
description: >-
  Includes merchandising and returns updates, expanded extension capabilities,
  draft order access changes, and Customer Account API updates.
source_url:
  html: 'https://shopify.dev/release-notes/2025-04'
  md: 'https://shopify.dev/release-notes/2025-04.md'
api_version: 2025-04
metadata:
  description: >-
    Includes merchandising and returns updates, expanded extension capabilities,
    draft order access changes, and Customer Account API updates.
---

# 2025-04: Release notes

The 2025-04 release focuses on merchandising, returns, extension capabilities, GraphQL Admin API changes, and Customer Account API changes.

Several changes in this version require code updates, especially around draft order access, products and collections, and Customer Account API changes. Review and adjust affected integrations before adopting 2025-04.

2025-04 is no longer supported. Requests for this version fall forward to the oldest accessible stable version:

***

## Graph​QL Admin API

GraphQL Admin API updates include catalogs, customers, online store data, orders, payments, markets, fulfillment, and deprecation changes.

### Apps

Apps updates add finance KYC access.

Update:

Shopify-approved finance apps can retrieve shop finance `KYC` details with `FinanceKycInformation` on behalf of an approved `StaffMember`, and subscribe to `FINANCE_APP_STAFF_MEMBER_DELETE`, `FINANCE_APP_STAFF_MEMBER_GRANT`, `FINANCE_APP_STAFF_MEMBER_REVOKE`, `FINANCE_APP_STAFF_MEMBER_UPDATE`, and `FINANCE_KYC_INFORMATION_UPDATE` webhooks.

[Apr 1, 2025](https://shopify.dev/changelog/new-finance-kyc-information-field-available-for-shopify-approved-finance-apps)

### Store properties

Store property updates add privacy settings management.

Update:

The GraphQL Admin API now supports managing shop privacy settings with `PrivacySettings`, including status and enablement for cookie banners, data sale opt-out pages, and privacy policy automation, plus regional controls for cookie consent and data sale opt-outs.

[Apr 1, 2025](https://shopify.dev/changelog/expanded-control-of-privacy-settings-using-the-graphql-admin-api)

### Billing

Billing updates add app subscription plan handles and subscription contract sorting.

Update:

The `subscriptionContracts` query now supports sorting results by the `created_at`, `updated_at`, and `status` filters in the GraphQL Admin API and Customer Account API. Use these filters to organize contracts by creation time, update time, or current status.

[Jan 25, 2025](https://shopify.dev/changelog/subscription-contracts-filters)

Update:

Managed pricing app subscription plans now expose persistent handles for querying plan data consistently after plan IDs change. Use `AppRecurringPricing.planHandle` in the GraphQL Admin API and `plan_handle` in the `app_subscriptions/update` webhook payload.

[Apr 1, 2025](https://shopify.dev/changelog/new-planhandle-field-managed-pricing)

### Cart

Deprecated Checkout APIs shut down on April 1, 2025.

Action required:

The deprecated Checkout APIs, including Storefront Checkout Mutations and REST Checkout Endpoints, shut down on April 1, 2025. Update impacted apps to the Storefront Cart API; mobile apps can also adopt Checkout Sheet Kit.

[Mar 2, 2025](https://shopify.dev/changelog/checkout-apis-will-be-shut-down-april-1-2025)

### Customers

Customer updates add payment method revocation reasons, default email data, RFM groups, address mutations, and marketing consent source locations.

Update:

`CustomerPaymentMethodRevocationReason` includes new values for additional revocation cases: `CUSTOMER_REDACTED`, `TOO_MANY_CONSECUTIVE_FAILURES`, and `CVV_ATTEMPTS_LIMIT_EXCEEDED`.

[Apr 1, 2025](https://shopify.dev/changelog/add-new-customerpaymentmethodrevocationreasons)

Update:

The `Customer` object now includes `defaultEmailAddress`, which lets apps query a customer’s email address and marketing state.

[Apr 1, 2025](https://shopify.dev/changelog/adding-defaultemailaddress-field-to-customer)

Update:

The GraphQL Admin API now exposes a customer’s RFM (Recency, Frequency, Monetary) group through `Customer.statistics.rfmGroup`. Use `rfmGroup` to view customer engagement and purchasing patterns for segmentation and targeted marketing workflows.

[Apr 1, 2025](https://shopify.dev/changelog/customer-rfm-group-now-available-in-graphql-admin-api)

Update:

The GraphQL Admin API adds `customerAddressCreate`, `customerAddressUpdate`, and `customerAddressDelete` mutations for managing customer addresses. Use the `setAsDefault` argument on create and update mutations to set an address as the customer’s default.

[Feb 26, 2025](https://shopify.dev/changelog/new-customer-address-capabilities-in-the-admin-api)

Update:

Now exposes the retail location where a customer’s marketing consent state was last updated, when applicable, through `CustomerEmailMarketingConsentState.sourceLocation` and `CustomerSmsMarketingConsentState.sourceLocation`.

[Feb 5, 2025](https://shopify.dev/changelog/track-the-retail-locations-where-your-customers-update-their-marketing-consent)

### Discounts and marketing

Discount search adds filters for end, creation, and update times.

Update:

`discountNodes` query now supports `ends_at`, `created_at`, and `updated_at` filters, so apps can find discounts by ending, creation, or last-updated time ranges.

[Feb 17, 2025](https://shopify.dev/changelog/new-endsat-createdat-and-updatedat-query-filter-parameters-for-searching-discounts)

### Graph​QL types

GraphQL type updates add a subscription billing attempt error code and remove redundant `RELEVANCE` sort options.

Update:

The `SubscriptionBillingAttemptErrorCode` enum now includes `NON_TEST_ORDER_LIMIT_REACHED`, returned when a subscription billing attempt reaches the order limit for the payment processor. Use a test payment gateway to place another order.

[Feb 15, 2025](https://shopify.dev/changelog/nontestorderlimitreached-error-for-subscriptions-billing-attempts)

Update:

`RELEVANCE` is no longer included by default in connection sort options where it only duplicated basic `ID` sorting; cases where `RELEVANCE` provides unique capabilities and handles regular traffic are unchanged.

[Feb 1, 2025](https://shopify.dev/changelog/removing-unnecessary-relevance-sort-options)

### Metafields

Custom identifiers can now look up more resource types.

Update:

Use custom identifiers to look up additional resource types with `collectionByIdentifier`, `locationByIdentifier`, `orderByIdentifier`, and `productVariantByIdentifier`. Custom IDs are defined with the new `id` metafield type, where unique values are required and enabled by default.

[Mar 22, 2025](https://shopify.dev/changelog/custom-ids-more-lookups)

### Online store

Online store updates add content filters, theme file metadata, theme roles, and article author data.

Update:

`articles`, `pages`, and `comments` queries have full filter parity with the REST Admin API. Filter `articles` by `blog_id`, `handle`, and `published_at`; `pages` by `published_status`, `published_at`, and `id`; and `comments` by `created_at`, `updated_at`, and `published_at`.

[Apr 1, 2025](https://shopify.dev/changelog/new-filter-options-added-to-pages-articles-and-comments)

Update:

`themeFilesUpsert` now returns theme file metadata in the GraphQL Admin API response body for successful mutations. Use `OnlineStoreThemeFileOperationResult` to verify file updates without making additional fetch requests.

[Apr 1, 2025](https://shopify.dev/changelog/new-theme-file-metadata-fields-added-to-onlinestorethemefileoperationresult-object)

Update:

The `themeCreate` mutation now accepts an optional `role` argument to set the role for a newly created theme. Only `UNPUBLISHED` and `DEVELOPMENT` are permitted for new themes.

[Jan 23, 2025](https://shopify.dev/changelog/optional-role-argument-for-theme-create-mutation)

Update:

The `articleAuthors` query lets apps fetch a store’s list of article authors through the GraphQL Admin API.

[Apr 1, 2025](https://shopify.dev/changelog/new-articleauthors-query-in-the-graphql-admin-api)

### Orders

Order updates deprecate `CalculatedOrder` for committed edits and add partial payment recording.

Action required:

Update apps that use `CalculatedOrder` for committed order edits: use `Order` to access the current state after edits are committed, and `Order.agreements` to query past changes. `CalculatedOrder.committed` is also deprecated; uncommitted order edits are unchanged.

[Dec 12, 2024](https://shopify.dev/changelog/deprecation-notice-calculatedorder-for-committed-order-edits)

Update:

Use the new `orderCreateManualPayment` mutation to record partial payments on orders. Multiple separate payments can be recorded, up to the total amount owing on the order.

[Jan 31, 2025](https://shopify.dev/changelog/record-partial-payments-on-orders)

### Products and collections

Products and collections updates add catalog changes, product and customer upserts, gift card limits, order line item weights, fulfillment rejection reasons, product sync IDs, harmonized system code validation, and clearer deprecation headers.

Markets integrations also need updates for backup regions, nullable currency settings, web presences, and contextual pricing.

Action required:

Unused `PriceListErrorCode` values that are not returned by the API are hidden. Remove any references to `CATALOG_ASSIGNMENT_NOT_ALLOWED`, `CATALOG_CANNOT_CHANGE_CONTEXT_TYPE`, `APP_CATALOG_PRICE_LIST_ASSIGNMENT`, and `CONTEXT_RULE_MARKET_LOCKED`.

[Mar 17, 2025](https://shopify.dev/changelog/deprecating-pricelistusererrorcode-values)

Action required:

Catalog APIs now support multiple markets on one catalog, so `MarketCatalog.markets` no longer guarantees a single entry. To keep existing region-only behavior, update `markets` queries to pass `type: REGION`.

[Jan 29, 2025](https://shopify.dev/changelog/new-catalog-apis)

Action required:

Update Markets integrations to use `backupRegionUpdate` with `BackupRegionUpdateInput`, handle nullable `Market.currencySettings`, and replace deprecated `MarketWebPresence.market` with `MarketWebPresence.markets`.

[Jan 3, 2025](https://shopify.dev/changelog/new-markets-apis)

Update:

The `combinedListingUpdate` mutation returns the new `option_name_contains_invalid_characters` error when an option name includes invalid character sequences, such as `/`, providing clearer feedback for invalid input.

[Apr 1, 2025](https://shopify.dev/changelog/combined-listings-update-mutation-enhancements)

Update:

`FulfillmentOrderRejectionReason` includes new rejection reasons for international shipping setup, incorrect product info, invalid contact information or `SKUs`, merchant blocks, missing customs info, oversized orders, missing package preferences, and declined payments.

[Apr 1, 2025](https://shopify.dev/changelog/new-enum-values-for-fulfillmentorderrejectionreason)

Update:

`productSet` and `customerSet` now support idempotent upserts by `identifier`, updating an existing record when matched or creating one otherwise. Supported identifiers are `handle`, `id`, and `customId` for `productSet`, and `phone`, `email`, and `customId` for `customerSet`.

[Apr 1, 2025](https://shopify.dev/changelog/productset-and-customerset-mutations-now-support-upserts)

Update:

Use the `giftCardConfiguration` query to retrieve maximum gift card values, with separate limits available for purchased gift cards and issued gift cards.

[Apr 1, 2025](https://shopify.dev/changelog/view-gift-card-maximum-values)

Update:

The `X-Shopify-API-Deprecated-Reason` HTTP header now returns the specific detected GraphQL deprecations, such as `Shop.products` or `Shop.productVariants`, instead of a generic deprecation practices URL.

[Feb 24, 2025](https://shopify.dev/changelog/graphql-return-actual-deprecation-reasons)

Update:

Product Variant mutations now validate country-specific harmonized system codes against existing codes on the `InventoryItem`.

[Feb 14, 2025](https://shopify.dev/changelog/updated-country-harmonized-system-code-validations-on-product-variant-mutations)

Update:

The GraphQL Admin API now includes the `id` return field in `ProductFullSyncPayload`, so apps can track product full sync payloads directly.

[Jan 15, 2025](https://shopify.dev/changelog/expose-the-id-field-in-productfullsyncpayload-object)

Update:

The `orderCreate` mutation now supports the optional `OrderCreateLineItemInput.weight` field using `WeightInput` to set line item weights. For variant-backed items, specified weights override variant defaults; custom items default to `0` when no weight is provided.

[Jan 15, 2025](https://shopify.dev/changelog/line-item-weight-input-for-ordercreate-mutation)

### Retail

Exchange queries can now include mirrored exchanges.

Update:

The Retail `ExchangeV2` query now supports the `include_mirrored_exchanges` filter to include or exclude exchanges mirrored from the Shopify admin.

[Mar 17, 2025](https://shopify.dev/changelog/new-includemirroredexchanges-query-filter-parameter)

### Shipping and fulfillment

Fulfillment service mutations add `requiresShippingMethod`.

Update:

Mutations `fulfillmentServiceCreate` and `fulfillmentServiceUpdate` now support the `requiresShippingMethod` field, aligning fulfillment service configuration with the REST Admin API equivalents.

[Jan 1, 2025](https://shopify.dev/changelog/add-new-requiresshippingmethod-field-to-fulfillmentservicecreate-and-fulfillmentserviceupdate-mutations)

### Shopify Payments

Shopify Payments updates add card brand values, balance transaction amounts, and merged payout statuses.

Update:

`OrderTransactions.paymentMethods` includes two new enum values, `CARTES_BANCAIRES` and `BANCONTACT`. Order transactions paid with these methods return the corresponding values in GraphQL Admin API responses.

[Jan 10, 2025](https://shopify.dev/changelog/new-card-brands-for-ordertransactionspaymentmethods)

Action required:

Shopify Payments payout statuses `In Transit` and `Scheduled` are now merged into `Scheduled` in dashboards and API responses. If your workflows or integrations use `In Transit`, update them to recognize `Scheduled` instead.

[Jan 29, 2025](https://shopify.dev/changelog/payout-statuses-in-transit-and-scheduled-have-been-merged)

Update:

Balance transaction adjustment orders now expose fee and net amount data for reconciliation. Use `fees` and `net` under `ShopifyPaymentsBalanceTransaction.adjustmentsOrders` in the GraphQL Admin API, or `fee` and `net` under `adjustment_order_transactions` on the REST Admin API `Transactions` resource.

[Apr 1, 2025](https://shopify.dev/changelog/new-fees-and-net-fields-for-balance-transactions)

***

## Customer Account API

Customer Account API updates include store credit metadata, reserved namespace protections, order fulfillment status, and contextual translations.

### Store credit

Store credit transactions add event and origin metadata.

Update:

Store credit transactions in the Customer Account API now include `event` and `origin` fields to identify what triggered a transaction and its source, including references to an originating `OrderTransaction` when applicable. `OrderTransaction` also now exposes `order`.

[Feb 7, 2025](https://shopify.dev/changelog/new-event-and-origin-fields-for-store-credit-transactions)

### Merchandising

Metafield namespaces and metaobject types add reserved-prefix protections.

Update:

New metafield namespaces and metaobject types can’t include `--`, including values such as `foo--` or `foo--bar`. Existing metafield and metaobject definitions continue to work, reserving the format for platform-defined identifiers like `shopify--{standard}` and `app--{your-app-id}`.

[Feb 19, 2025](https://shopify.dev/changelog/reserved-prefix-protection-for-metafields-and-metaobjects)

### Orders

Customer Account API adds order fulfillment status.

Update:

Adds `fulfillmentStatus` to the `Order` object, representing the order’s aggregated fulfillment status for display purposes.

[Apr 1, 2025](https://shopify.dev/changelog/new-field-fulfillmentstatus-added-to-the-order-type-of-the-customer-account-api)

### Store properties

Customer Account API adds contextual translations.

Update:

Supports the `@inContext` directive with a `language` argument to return translated values when the requested language is active for the given country. Unsupported language or country requests using `@inContext` fall back to the default language.

[Apr 1, 2025](https://shopify.dev/changelog/exposed-incontext-directive-with-the-customer-account-api)

***

## Events & webhooks

Webhooks add checkout and accounts configuration tracking.

### Order

Update:

The `checkout_and_accounts_configurations/update` webhook fires when merchants update draft or published checkout and accounts configurations. Apps can monitor `typ_osp_pages_enabled` in the payload to detect **Thank you** and **Order status** page upgrades without polling APIs.

[Apr 1, 2025](https://shopify.dev/changelog/new-webhook-to-track-updates-to-checkout-and-accounts-configuration)

***

## Payments Apps API

Payments Apps API adds card-not-present processing details.

Update:

Payments apps can now provide card-not-present processing details on `PaymentSessionPaymentDetails` using `cardNotPresent`, including `avsResultCode` for `AVS` responses and `cvvResultCode` for `CVV` verification results.

[Mar 31, 2025](https://shopify.dev/changelog/expose-payment-detail-fields-for-payments-apps)

***

## Polaris

Polaris updates include app-owned metafields, checkout attribute removal, and POS target support.

### Access

Checkout and customer account UI extensions add app-owned metafield access.

Update:

Checkout and customer account UI extensions can now read app-owned metafields through the `appMetafield` API. Request these metafields in `shopify.extension.toml` using the `$app` namespace format; writing to them isn’t supported.

[Mar 7, 2025](https://shopify.dev/changelog/support-added-for-app-owned-metafields-in-checkout-ui-extension-api)

### Checkout

Checkout UI extensions add cart and checkout attribute removal.

Update:

Checkout UI extensions can now remove cart and checkout attributes by using `AttributeRemoveChange`. Pass the attribute key you want to remove when applying an attribute change during checkout.

[Apr 1, 2025](https://shopify.dev/changelog/checkout-ui-extensions-attributes-api-now-supports-removing-cart-and-checkout-attributes)

### POS

POS UI extensions add developer-preview targets, receipt footer components, and QR codes.

Action required:

POS UI extensions built on [unsupported versions](https://shopify.dev/changelog/end-of-compatibility-for-old-pos-ui-extensions-versions), or the April 2024 POS UI extension version stop functioning in POS `9.31`. Update affected apps to the latest POS UI extension version.

[Mar 7, 2025](https://shopify.dev/changelog/end-of-compatibility-for-old-pos-ui-extensions-versions)

Update:

POS UI extensions add developer-preview targets for transaction complete, cart updates, cash tracking session start and complete, and receipt footer rendering. Receipt footer extensions must use `POSReceiptBlock` as the parent component, and `QRCode` is now available.

[Mar 28, 2025](https://shopify.dev/changelog/pos-ui-extensions-2025-04-update)

***