Shopify Introduces SubscriptionBillingAttemptState Field to GraphQL Admin API

Shopify has added the SubscriptionBillingAttemptState field to the GraphQL Admin API, effective April 2026. This new field consolidates billing attempt state information using a discriminated union pattern, replacing multiple nullable fields that previously handled subscription billing states.

What Changed

The SubscriptionBillingAttemptState field provides a structured approach to accessing billing attempt data. Instead of querying several loosely-typed nullable fields, developers can now use a single discriminated union that clearly defines the state of each billing attempt. This change affects how subscription apps query and handle billing attempt information through the GraphQL Admin API.

Impact on Subscription App Development

Developers building subscription apps will need to update their GraphQL queries to use the new field structure. The discriminated union pattern offers stronger typing, which reduces the need for null checks and conditional logic when processing billing attempt states. This makes the API more self-documenting, as the available states and their associated data are explicitly defined in the schema.

Migration Considerations

Apps currently using the deprecated nullable fields will continue to function, but developers should plan to migrate to SubscriptionBillingAttemptState before the deprecation deadline. The new structure requires updating query patterns and potentially refactoring state-handling logic to work with the union type. Testing billing workflows across different attempt states will be necessary to ensure the migration handles all scenarios correctly.

Read the full announcement →