---
title: >-
  Subscriptions APIs: Introduce SubscriptionBillingAttemptState - Shopify
  developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/posts/subscriptions-apis-introduce-subscriptionbillingattemptstate
  md: >-
    https://shopify.dev/changelog/posts/subscriptions-apis-introduce-subscriptionbillingattemptstate.md
metadata:
  effectiveApiVersion: 2026-04
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: New
    handle: new
  indicatesActionRequired: false
  createdAt: '2026-02-17T13:41:02-05:00'
  postedAt: '2026-02-23T12:00:00-05:00'
  updatedAt: '2026-02-18T07:08:28-05:00'
  effectiveAt: '2026-02-23T12:00:00-05:00'
---

February 23, 2026

# Subscriptions APIs: Introduce SubscriptionBillingAttemptState

DateFebruary 23, 2026

Version[2026-04](https://shopify.dev/changelog?api_version=2026-04)

FlagsNew

SurfacesAPI

Affected APIs[Admin GraphQL API](https://shopify.dev/changelog?api_type=admin-graphql)

As of April 2026, you now have access to the `SubscriptionBillingAttemptState` field in the GraphQL Admin API. This new field replaces several loosely-typed nullable fields with a discriminated union pattern, enhancing the API's ergonomics and self-documentation.

| Deprecated Field | New Equivalent | Notes |
| - | - | - |
| errorCode | FailedState.error.code | Error codes now categorized into Payment, Inventory, General, and Unexpected errors |
| errorMessage | FailedState.error.message | Explicit messages now only on UnexpectedError; other types use typed codes |
| nextActionUrl | ActionRequiredState.action.nextActionUrl | Now also includes status (OFF\_SESSION\_REJECTED / ON\_SESSION\_CHALLENGED) |
| order | SuccessState.order | Same Order type, scoped to success state |
| processingError | FailedState.error | Replaced by typed SubscriptionBillingAttemptError union |
| ready | PendingState.processing | Instead of a boolean, check whether state is PendingState |

Find details about the `SubscriptionBillingAttemptState` schema [in the documentation](https://shopify.dev/docs/api/admin-graphql/2026-04/unions/SubscriptionBillingAttemptState).