> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a Saved-Card Token's Status

> Check whether a saved-card token can still be charged, and when its card data will be erased.

`GET /token/{token}` tells you whether a token you stored can still be charged. Call it before a retry or a scheduled charge when you keep tokens on your side for a long time, or after you receive a `token.deleted` or `token.erased` [webhook](https://docs.therius.io/webhooks/events.md).

A token is in one of four states:

| `status` | Can it be charged? |
| - | - |
| `active` | Yes. |
| `deleted` | Yes, until its card data is erased on `erasesAt`. The shopper removed the card, a newer save of the same card replaced it, or Therius retired an expired or unused card. A charge on it returns the header `X-Therius-Token-Status: deleted`. |
| `erased` | No. The card data was permanently erased. Ask the shopper for a new card. |
| `expired` | No. The token's own expiration date has passed. |

`erasesAt` is empty while an active subscription or payout still uses the card (`heldBySubscription` is `true`). It moves later whenever the token is used again. After erasure `brand`, `last4`, `expiryMonth` and `expiryYear` stay, so past payments keep showing the card.

See [Token lifecycle](https://docs.therius.io/concepts/tokenization.md#token-lifecycle) for the retention rules and the error codes a charge returns.

```bash cURL theme={"dark"}
curl https://api.therius.io/v1/token/vt_4xK9mNpQ2rLsT7uV \
  -H "Authorization: Bearer prv_production_your_key_here"
```

```json 200 OK theme={"dark"}
{
  "token": "vt_4xK9mNpQ2rLsT7uV",
  "status": "deleted",
  "deletedAt": "2026-03-02T14:11:09Z",
  "deletedReason": "deleted",
  "erasedAt": null,
  "erasesAt": "2028-03-01T14:11:09Z",
  "heldBySubscription": false,
  "brand": "visa",
  "last4": "4242",
  "expiryMonth": "12",
  "expiryYear": "2030"
}
```


## OpenAPI

````yaml GET /token/{token}
openapi: 3.1.0
info:
  title: Therius API
  description: REST API for payments, subscriptions, and billing plans.
  version: 1.0.0
servers:
  - url: https://api.therius.io/v1
    description: Production
  - url: https://api-sandbox.therius.io/v1
    description: Sandbox
security:
  - bearerAuth: []
paths:
  /token/{token}:
    get:
      tags:
        - Tokens
      summary: Get a saved-card token's status
      description: >-
        Says whether a Therius token can still be charged. `active` tokens
        charge normally. A `deleted` token (the shopper removed the card, a
        newer save of the same card replaced it, or Therius retired an expired
        or unused card) still charges until its card data is erased on
        `erasesAt`. An `erased` or `expired` token can no longer be charged. The
        `token.deleted` and `token.erased` webhooks announce the changes.
      operationId: getTokenStatus
      parameters:
        - name: token
          in: path
          required: true
          description: The token returned when the card was stored (`vt_...`).
          schema:
            type: string
        - name: merchantCode
          in: query
          required: false
          description: Your merchant account identifier.
          schema:
            type: string
      responses:
        '200':
          description: Token status
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                  status:
                    type: string
                    enum:
                      - active
                      - deleted
                      - erased
                      - expired
                    description: >-
                      `active`, `deleted` (still charges until `erasesAt`),
                      `erased` (card data permanently erased; cannot be charged)
                      or `expired`.
                  deletedAt:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    description: When the card was deleted or retired.
                  deletedReason:
                    type:
                      - string
                      - 'null'
                    description: >-
                      `deleted` when the shopper or a support agent removed the
                      card or a newer save replaced it; `expired` or `unused`
                      when Therius retired it; `null` while the token is active.
                  erasedAt:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    description: When the card data was erased.
                  erasesAt:
                    type:
                      - string
                      - 'null'
                    format: date-time
                    description: >-
                      When the card data will be erased if the token is not used
                      again. `null` while a live subscription or payout still
                      uses the card. Using the token again moves this date.
                  heldBySubscription:
                    type: boolean
                    description: >-
                      `true` when a deleted card is kept because an active
                      subscription still renews on it.
                  brand:
                    type:
                      - string
                      - 'null'
                    description: Card brand. Kept after the card data is erased.
                  last4:
                    type:
                      - string
                      - 'null'
                    description: Last four digits. Kept after the card data is erased.
                  expiryMonth:
                    type:
                      - string
                      - 'null'
                  expiryYear:
                    type:
                      - string
                      - 'null'
        '404':
          description: >-
            No such token for this merchant account. The body is `{ "error":
            "...", "code": "token_not_found" }`.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your secret API key: `Bearer prv_production_xxx` (production) or `Bearer
        prv_sandbox_xxx` (sandbox).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.