> ## Documentation Index
> Fetch the complete documentation index at: https://direct-api.reap.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Cards

> Virtual cards belong to team members and carry a funding plan, a budget and spending limits. Every status and creation outcome explained.

A card belongs to one team member and draws on your card account. The API
creates virtual cards; physical cards created in the dashboard (see [How do I issue a Virtual or Physical card to a Team Member?](https://support.reap.global/hc/en-us/articles/13938938714767-How-do-I-issue-a-Virtual-or-Physical-card-to-a-Team-Member) in the Help Center) still appear
in [List cards](/api-reference/cards/list-cards.md) and
[Retrieve a card](/api-reference/cards/retrieve-a-card.md).

## `type`

| Value | Meaning |
| - | - |
| `virtual` | A card that exists only as card details. The only type the API can create. |
| `physical` | A plastic card. Read-only through the API. |

## `planType` (funding plan)

| Value | Meaning |
| - | - |
| `subscription` | The default. The card draws on your business's **shared credit pool**. `spendCap` is only a spending limit (the most this card can pay), not dedicated funds, and the credit stays available to everything else on the account. The usual choice for team members' everyday cards. |
| `topUp` | The card gets its **own balance** in `spendCap`, for example USD 500. The funds are isolated to that card; no other card or budget on the account can touch them. The card declines once the balance is spent, until you add more. Good for one-off or tightly controlled spend. |
| `physical` | Physical card plans. Read-only; can't be created through the API. |

## `status`

| Value | Meaning | Can freeze? |
| - | - | - |
| `pending` | Created, still being set up | Yes |
| `active` | Ready to use | Yes |
| `frozen` | Paused by you or an admin; can be unfrozen | n/a (already frozen) |
| `inactive` | Not usable for another reason, such as a restricted or blocked card | Yes |
| `expiring` | A physical card within 90 days of its expiry date | Yes |
| `expired` | Past its expiry date | No (`409 CARD_STATE_CONFLICT`) |
| `terminated` | Permanently closed | No (`409 CARD_STATE_CONFLICT`) |

Only a `frozen` card can be unfrozen; any other state returns
`409 CARD_STATE_CONFLICT`.

## Creation outcomes

[Create card](/api-reference/cards/create-card.md) returns one of three:

* **`201` with `status: "active"`**: the card is ready.
* **`201` with `status: "pending"`**: created, still being set up. Poll the
  `Location` response header until it's `active`.
* **`202` with `status: "pendingApproval"`**: your business uses Approvals.
  See [Approvals](/concepts/approvals.md).

## Freeze vs terminate

**Freeze** is reversible and needs a `reason`: `lost`, `damaged`,
`suspectedFraud`, `noLongerNeeded` or `other` (`other` requires a `note`).
`lost` and `damaged` only apply to physical cards. On a virtual card they
fail with `422 FREEZE_REASON_NOT_APPLICABLE`. **Terminate** is permanent.

## Title and lookup

`title` is the card's nickname, searchable with `GET /cards?title=`. Start
titles with your own reference, for example `CMP-0001`, so you can find the
cards you created later.

## Limits

* Card creation is limited per business, sharing its limit with the
  dashboard (`429 CARD_LIMIT_EXCEEDED`). If you expect to create a significant number
  of cards, reach out to your account manager first.
* Creating a card requires funds on your card account
  (`422 CARD_CREATION_REQUIRES_DEPOSIT`). See [How to add
  funds to your Reap Account](https://support.reap.global/hc/en-us/articles/16170706183567-How-to-add-funds-to-your-Reap-Account) in the Help Center.
* Card currency and spend control currency must match: `USD` or `HKD`
  (`422 CURRENCY_MISMATCH`).

## Related endpoints

* [Create card](/api-reference/cards/create-card.md) ·
  [List cards](/api-reference/cards/list-cards.md) ·
  [Retrieve a card](/api-reference/cards/retrieve-a-card.md)
* [Edit card details](/api-reference/cards/edit-card-details.md) ·
  [Freeze card](/api-reference/cards/freeze-card.md) ·
  [Unfreeze card](/api-reference/cards/unfreeze-card.md) ·
  [Terminate card](/api-reference/cards/terminate-card.md)


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