2025-04: Release notes

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.

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.

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.

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.

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.

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

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

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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

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.

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.

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.

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

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.

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

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

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.

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

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

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.

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.

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.

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.

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}.

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

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.

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.

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.

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.

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.

POS UI extensions built on unsupported 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.

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.