---
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/new-payment-error-codes-added-to-subscriptions-apis
  md: >-
    https://shopify.dev/changelog/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

Tags:

* Admin GraphQL API
* 2026-04

# Subscriptions APIs: new payment error code and error classification

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` |