---
title: >-
  Subscriptions APIs: new payment error code and error classification - 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/new-payment-error-codes-added-to-subscriptions-apis
  md: >-
    https://shopify.dev/changelog/posts/new-payment-error-codes-added-to-subscriptions-apis.md
metadata:
  effectiveApiVersion: 2026-04
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: Update
    handle: update
  indicatesActionRequired: false
  createdAt: '2026-02-02T14:00:59-05:00'
  postedAt: '2026-02-04T15:10:00-05:00'
  updatedAt: '2026-02-05T13:35:07-05:00'
  effectiveAt: '2026-02-03T12:00:00-05:00'
---

February 4, 2026

# Subscriptions APIs: new payment error code and error classification

DateFebruary 4, 2026

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

FlagsUpdate

SurfacesAPI

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

We’ve added new payment error codes for subscription billing attempts in the GraphQL Admin API. These new error codes provide more granularity and consistency, making payment errors easier to diagnose. They’re [currently available](https://shopify.dev/docs/api/admin-graphql/unstable/enums/SubscriptionBillingAttemptErrorCode) in the `unstable` API version, will be released in version `2026-04`.

We’re also updating our error-code mapping to be more explicit:

* In the `unstable` version, you’ll start seeing new error codes display, along with fewer `AUTHENTICATION_ERROR` and `PAYMENT_METHOD_DECLINED` errors.
* If you’re on version `2026-01` or earlier, you might still notice a shift in error volumes across existing error codes. We improved our mapping so that some errors previously categorized as generic decline errors, such as `PAYMENT_METHOD_DECLINED`, are now mapped more explicitly to existing error codes. For example, we can map more cases to `INSUFFICIENT_FUNDS` instead of generic declines.

## Known issue resolved

From January 28, 2026, to February 4, 2026, there was a temporary issue with error mapping, which might have caused a surge in `TRANSIENT_ERROR`. This has been fixed.

## Error code mapping

* If you're on version `unstable` or `2026-04`, you'll see the new error code.

* If you're on `2026-01` or earlier versions, you'll see the currently mapped code.

  | New error code | Currently mapped error code |
  | - | - |
  | `AMOUNT_TOO_LARGE` | `UNEXPECTED_ERROR` |
  | `MERCHANT_ACCOUNT_ERROR` | `UNEXPECTED_ERROR` |
  | `AUTHENTICATION_FAILED` | `AUTHENTICATION_ERROR` |
  | `AUTHENTICATION_REQUIRED` | `AUTHENTICATION_ERROR` |
  | `CALL_ISSUER` | `PAYMENT_METHOD_DECLINED` |
  | `CARD_DECLINED` | `PAYMENT_METHOD_DECLINED` |
  | `CONFIRMATION_REJECTED` | `PAYMENT_METHOD_DECLINED` |
  | `DO_NOT_HONOR` | `PAYMENT_METHOD_DECLINED` |
  | `MERCHANT_RULE` | `PAYMENT_METHOD_DECLINED` |
  | `OFF_SESSION_REJECTED` | `PAYMENT_METHOD_DECLINED` |
  | `RETRY_DECLINED` | `PAYMENT_METHOD_DECLINED` |
  | `TRANSACTION_LIMIT_EXCEEDED` | `PAYMENT_METHOD_DECLINED` |
  | `INCORRECT_ZIP` | `INVALID_PAYMENT_METHOD` |
  | `INVALID_CURRENCY` | `INVALID_PAYMENT_METHOD` |
  | `INVALID_NUMBER` | `INVALID_PAYMENT_METHOD` |
  | `INVALID_PAYMENT_ERROR` | `INVALID_PAYMENT_METHOD` |
  | `PAYMENT_METHOD_UNSUPPORTED` | `INVALID_PAYMENT_METHOD` |
  | `INCORRECT_ADDRESS` | `INVALID_PAYMENT_METHOD` |
  | `INCORRECT_NUMBER` | `CARD_NUMBER_INCORRECT` |
  | `EXPIRED_CARD` | `EXPIRED_PAYMENT_METHOD` |
  | `INVALID_EXPIRY_DATE` | `EXPIRED_PAYMENT_METHOD` |
  | `EXPIRED_BUYER_ACTION` | `EXPIRED_PAYMENT_METHOD` |
  | `PROCESSING_ERROR` | `UNEXPECTED_ERROR` |
  | `PAYMENT_PROVIDER_ERROR` | `UNEXPECTED_ERROR` |
  | `GENERIC_ERROR` | `TRANSIENT_ERROR` |
  | `CANCELLED_PAYMENT` | `BUYER_CANCELED_PAYMENT_METHOD` |
  | `INVALID_PURCHASE_TYPE` | `PURCHASE_TYPE_NOT_SUPPORTED` |