---
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-04T15:04:14-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 Admin GraphQL API. These new error codes provide more granularity and consistency, making payment errors easier to diagnose. They’re currently available in the unstable API version that you can discover [here](https://shopify.dev/docs/api/admin-graphql/unstable/enums/SubscriptionBillingAttemptErrorCode).

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

* In the `unstable` version, you’ll start seeing new error codes appear, along with fewer `AUTHENTICATION_ERROR` and `PAYMENT_METHOD_DECLINED` errors.
* If you’re on `2026-01` or earlier versions, you may 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 (`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.

Please note that from **January 28, 2026, to February 4, 2026**, there was a temporary issue with error mapping, which may have caused a surge in `TRANSIENT_ERROR`. This has now been fixed.

### Error code mapping

* If you are on `unstable` version, you will see the new error code.

* If you are on `2026-01` or earlier versions, you will 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` |