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

# Issue and manage cards with the Meow API

> Step-by-step guide to issuing virtual cards, setting spend limits and merchant restrictions, freezing and revoking cards, and reviewing card transactions.

This guide explains how to issue and manage cards with the Meow API. It covers:

* Creating a virtual card with spend limits
* Restricting a card to specific merchants or categories
* Freezing, updating, and revoking a card
* Reviewing transactions and spend

## Prerequisites

* A Meow account with at least one enabled bank account
* API key permissions:
  * Reading cards and transactions: `cards:read`
  * Creating and modifying cards: `cards:write`
  * Sandbox simulations: `simulations:write`

## Authentication Overview

The headers you send depend on the type of API key:

* **Entity API keys** scope all requests to a single entity. No `x-entity-id` header is required.
* **Global API keys** can access multiple entities, and every request must include an `x-entity-id` header identifying the entity. Use `GET /v1/api-keys/accessible-entities` to discover which entities you can access.

## Card lifecycle

A card moves through a small number of states, reported as `status` on the card:

| Status      | Meaning                                                                   |
| ----------- | ------------------------------------------------------------------------- |
| `pending`   | The card is being issued. Card details are not available yet.             |
| `active`    | The card can authorize transactions.                                      |
| `suspended` | The card is frozen. Authorizations are declined, and you can unfreeze it. |
| `closed`    | The card is revoked. This is permanent.                                   |
| `failed`    | Issuing did not complete.                                                 |

## Create a card

`spending_controls` and `nickname` are required. Within `spending_controls`, only `per_transaction_limit` is required. All limits are in whole dollars.

```bash theme={null}
curl -X POST "https://api.meow.com/v1/cards" \
  -H "x-api-key: YOUR_ENTITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "Ads spend",
    "spending_controls": {
      "per_transaction_limit": 500,
      "monthly_limit": 5000
    }
  }'
```

```json theme={null}
{
  "payment_type": "card",
  "controls": {
    "spending_controls": {
      "per_transaction_limit": 500,
      "monthly_limit": 5000
    },
    "single_use": false
  },
  "metadata": {
    "card_id": "515024f9-6ad2-4ce5-bc2f-b0820bf9336b"
  }
}
```

Record the `card_id`. Every other card operation uses it.

### Spend limits

Each limit resets on its own schedule. Combine them to cap both a single purchase and a period of spend.

| Field                   | Resets                                              |
| ----------------------- | --------------------------------------------------- |
| `per_transaction_limit` | Not a running total. Applies to each authorization. |
| `daily_limit`           | Midnight UTC                                        |
| `weekly_limit`          | Sunday at midnight UTC                              |
| `monthly_limit`         | The 1st at midnight UTC                             |
| `yearly_limit`          | January 1st at midnight UTC                         |
| `all_time_limit`        | Never                                               |

<Note>
  Limits are a ceiling on the card, not a reservation of funds. The combined limits across your cards can exceed your account balance, and each authorization is checked against your available balance at the moment it happens. A card within its own limit is still declined if the account cannot cover the transaction.
</Note>

### Optional fields

* `single_use` — revoke the card automatically after its first authorization.
* `expires_at` — the card stops working at this time. It is not revoked automatically, so revoke it explicitly when you are done.
* `debit_account` — the account the card draws from, as a `cash_account_` id from [List Accounts](/api-reference/core-api/list-bank-accounts). Omit to use the default.
* `purpose` — a memo for your own records, recorded on the card's audit trail. It is never shown to the merchant.

## Restrict where a card can be used

### By merchant

Fetch merchant IDs first, then reference them in `spending_restriction`. Use `allow` to limit the card to those merchants, or `block` to bar them.

```bash theme={null}
curl -X GET "https://api.meow.com/v1/cards/merchants" \
  -H "x-api-key: YOUR_ENTITY_API_KEY"
```

```bash theme={null}
curl -X POST "https://api.meow.com/v1/cards" \
  -H "x-api-key: YOUR_ENTITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "Cloud hosting",
    "spending_controls": { "per_transaction_limit": 2000 },
    "spending_restriction": {
      "type": "allow",
      "merchants": ["9f2c1e84-5b7a-4d63-9c10-2e8f4a6b7d31"]
    }
  }'
```

With `type` set to `allow`, the card authorizes only at those merchants. With `block`, it is refused at them and allowed everywhere else.

<Warning>
  `merchants` takes the merchant `id` values from `GET /v1/cards/merchants`, which are UUIDs. Merchant names will not match. You can list between 1 and 100 merchants.
</Warning>

### By category

`allowed_categories` limits the card to a set of merchant categories, such as `Software`, `Meals`, or `Advertising`. Omit it to allow every category.

```bash theme={null}
curl -X POST "https://api.meow.com/v1/cards" \
  -H "x-api-key: YOUR_ENTITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "Team meals",
    "spending_controls": { "per_transaction_limit": 150, "weekly_limit": 1000 },
    "allowed_categories": ["Meals", "Restaurants"]
  }'
```

## Retrieve the card number

Card numbers are returned through a single-use reveal URL rather than by the endpoint you call. See the [Card Numbers guide](/guides/card-numbers) for the full flow.

## Update a card

`PATCH /v1/cards/{card_id}` changes one or more fields. Everything is optional, so send only what you want to change.

**Freeze a card** by setting `status` to `inactive`, and unfreeze it with `active`:

```bash theme={null}
curl -X PATCH "https://api.meow.com/v1/cards/{card_id}" \
  -H "x-api-key: YOUR_ENTITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "inactive" }'
```

**Change limits or restrictions.** `spending_controls` and `spending_restriction` are replaced, not merged, so send the complete object you want:

```bash theme={null}
curl -X PATCH "https://api.meow.com/v1/cards/{card_id}" \
  -H "x-api-key: YOUR_ENTITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "Ads spend (Q4)",
    "spending_controls": { "per_transaction_limit": 800, "monthly_limit": 12000 }
  }'
```

<Tip>
  Pass `null` to `spending_restriction` or `allowed_categories` to clear the restriction and allow any merchant or category.
</Tip>

## Revoke a card

Revoking is permanent. The card moves to `closed` and cannot authorize again.

```bash theme={null}
curl -X POST "https://api.meow.com/v1/cards/{card_id}/revoke" \
  -H "x-api-key: YOUR_ENTITY_API_KEY"
```

Freeze the card instead if you may want to use it again.

## Review cards and spend

**List cards**, with optional filters and pagination. Use the `nextOffset` from the response to page:

```bash theme={null}
curl -X GET "https://api.meow.com/v1/cards?limit=25" \
  -H "x-api-key: YOUR_ENTITY_API_KEY"
```

**List transactions** across cards:

```bash theme={null}
curl -X GET "https://api.meow.com/v1/cards/transactions?limit=25" \
  -H "x-api-key: YOUR_ENTITY_API_KEY"
```

Other read endpoints:

* [Get Card](/api-reference/core-api/get-card) — a single card's status, last four, and restrictions.
* [Get Card Limits](/api-reference/core-api/get-card-limits) — limits alongside spend against them.
* [Get Card Details](/api-reference/core-api/get-card-details) — billing address, debit account, and for physical cards a tracking URL.
* [Card Spending Insights](/api-reference/core-api/get-card-spending-insights) — spend grouped by merchant.

## Test in sandbox

Cards do not need a real merchant to exercise. In sandbox, simulate the authorization lifecycle with the `simulations:write` scope:

<Steps>
  <Step title="Authorize">
    `POST /v1/simulations/card_authorizations` creates a pending authorization against a card.
  </Step>

  <Step title="Capture">
    `POST /v1/simulations/card_authorizations/{authorization_id}/capture` settles it into a transaction.
  </Step>

  <Step title="Increment or reverse">
    `.../increment` raises the authorized amount. `.../reverse` releases it, as a merchant does when cancelling an order.
  </Step>

  <Step title="Refund">
    `POST /v1/simulations/card_transactions/{transaction_id}/refund` refunds a settled transaction.
  </Step>
</Steps>

This is the fastest way to confirm your limits, restrictions, and webhook handling behave the way you expect before going live.

## Next steps

<CardGroup cols={2}>
  <Card title="Card Numbers" icon="credit-card" href="/guides/card-numbers">
    Retrieve the full card number, CVC, and expiration.
  </Card>

  <Card title="Webhooks" icon="bell" href="/guides/webhooks">
    Receive card and transaction events as they happen.
  </Card>

  <Card title="Create Card" icon="plus" href="/api-reference/core-api/create-card">
    Full request and response reference.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key types, scopes, and the `x-entity-id` header.
  </Card>
</CardGroup>