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

# Issuing and Managing Cards

> Create a card, wait for it to activate, then freeze, close, rename, and limit it

<Warning>
  **Cards is available in sandbox only while we finish development.** Dakota enables Cards per
  account. The Cards endpoints are in the [API reference](/api-reference/introduction), marked
  **Sandbox only**. Endpoints, fields, and flows can still change before release.
</Warning>

## Before you issue

| Requirement | Where it comes from |
| - | - |
| The customer's Cards capability is `available` | [Activating customers](/documentation/cards/activation) |
| The cardholder is `active` | [Cardholders](/documentation/cards/cardholders) |
| The wallet is an EVM wallet owned by the customer, with an `active` card enablement | [Wallet enablement](/documentation/cards/wallet-enablement) |

## Create a card

```json theme={null}
POST /customers/{customer_id}/cards
X-Idempotency-Key: 0f5f2b46-1f2e-4c39-9a0c-2ba1a2a5b0d1

{
  "cardholder_id": "31TgvufZK3gDXBcA3BnSeLWiSn7",
  "wallet_id": "2tQRvK9pRzM4nVbW8sHqL5jXmYt",
  "spend_limit": { "interval": "monthly", "amount": 250000 },
  "nickname": "Ads card",
  "external_id": "eng-team-travel-01"
}
```

The response is the card, with `status: "pending"`. `last4` can be `null` until the card is issued; it arrives on a later `card.updated`. Full request and response: [Create a card](/api-reference/cards/create-a-card).

* `spend_limit.amount` is in minor units: `250000` is \$2,500.00. See [Spend limits](#spend-limits).
* `nickname` is an optional display label, up to 64 characters.
* `external_id` is your own reconciliation key. It is not unique.
* `last4` is the only part of the card number the API ever returns. To show the full card, see [Secure card data](/documentation/cards/secure-card-data).

| Refusal | Cause |
| - | - |
| `403 cardholder-not-active` | The cardholder is not `active` yet. The error reports its status. |
| `403 wallet-not-card-enabled` | The wallet has no `active` card enablement. |
| `400 invalid-request` | The wallet is not an EVM wallet. |
| `400 limit-reached` | The cardholder has the maximum number of active cards. Close cards that are no longer used. |
| `409 cardholder-reenroll-required` | The cardholder was enrolled before the card program's current requirements applied, so it cannot hold a new card. Close its cards, delete it, and create it again. |

**Wait for `card.updated` with `status: "active"`.** Until then the card cannot be spent or revealed. Treat `pending` in your UI as "being issued", not as an error.

## Card status

```mermaid theme={null}
flowchart LR
    P["pending"] --> A["active"]
    A -->|freeze| F["frozen"]
    F -->|unfreeze| A
    A -->|close| C(["closed"])
    F -->|close| C
```

| Status | Purchases |
| - | - |
| `pending` | Declined. The card is still being issued. |
| `active` | Approved, within the available balance and the spend limit. |
| `frozen` | Declined, until the card is unfrozen. |
| `closed` | Declined, permanently. Issue a new card instead. |

## Freeze, unfreeze, or close

[`PATCH /cards/{card_id}`](/api-reference/cards/update-a-card) with the new `status`:

```json theme={null}
PATCH /cards/{card_id}
X-Idempotency-Key: 4c2e7a91-5b3d-4f8e-a6c1-9d0b2e4f6a8c

{ "status": "frozen" }
```

Send `"active"` to unfreeze and `"closed"` to close. Closing is permanent, so freeze when in doubt. A change applies to the next authorization: it does not release a hold or cancel a purchase that was already approved.

A card can be frozen by more than you. `freeze_sources` lists everything holding the card frozen. `manual` is a freeze applied through this API, and it is the only one you can lift. Treat any other value, including one you do not recognize, as a freeze you cannot lift.

Freezing and closing are refused only for a closed card, or when the customer's Cards capability is unavailable. Unfreezing can also be refused for these reasons:

| Refusal | Cause |
| - | - |
| `403 card-freeze-held` | A source in `freeze_sources` other than `manual` holds the card. The error names it. |
| `403 card-not-activated` | The card is not activated yet. Retry after `card.updated` reports it `active`. |
| `403 cardholder-suspended` | The cardholder is suspended. Only Dakota can lift a suspension. |
| `403 card-closed` | The card is closed. Closed cards cannot be changed. |

## Rename

```json theme={null}
PATCH /cards/{card_id}

{ "nickname": "Travel card" }
```

A nickname can be replaced, but not removed once set. Nicknames do not have to be unique.

## Spend limits

A card has at most one spend limit: an `interval` and an `amount` in minor units. A card created without `spend_limit` has no per-card limit: it can spend up to the wallet's available balance. Set a limit at creation, and replace it with [`PUT /cards/{card_id}/spend_limit`](/api-reference/cards/replace-a-cards-spend-limit):

```json theme={null}
PUT /cards/{card_id}/spend_limit
X-Idempotency-Key: 8f1d3b5e-7a9c-4e2f-b4d6-1c3e5a7b9d0f

{ "interval": "weekly", "amount": 50000 }
```

* `interval` is `per_transaction`, `daily`, `weekly`, `monthly`, `yearly`, or `lifetime`.
* `per_transaction` caps each purchase. A purchase exactly at the limit is allowed.
* `daily`, `weekly`, `monthly`, and `yearly` are calendar windows that reset at midnight US Eastern Time: every day, every Monday, on the 1st of each month, and on January 1. They count authorized and settled spend in the current window, not a rolling period.
* `lifetime` caps everything the card ever spends.
* The new limit applies from the next purchase. Lowering it below what was already spent in the current window claws nothing back.
* A limit cannot be removed, only replaced.
* A limit is not a balance. A card with a \$5,000 monthly limit on a wallet holding \$200 can spend \$200.
* If Dakota sets a program-wide cap for your account, the lower of the two wins.
* You can change the limit of a frozen card, but not of a closed one.

## Read cards

* [`GET /customers/{customer_id}/cards`](/api-reference/cards/list-cards), filtered by `cardholder_id`, `status`, or `external_id`. Cursor-paginated.
* [`GET /cards/{card_id}`](/api-reference/cards/get-a-card). The response also embeds the cardholder and the wallet.