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

# Create card

> Issue a virtual debit card with custom spending limits.

Issues a virtual debit card on a bank account, with the spending limits you specify. The card's `authorization_controls.usage.category` must be `multi_use`, and at least one limit is required.

Every limit matching a payment is checked and the most restrictive one applies, so a payment is declined once it exceeds the per-transaction cap, or once the day's spend would pass the daily cap, even while the weekly and monthly caps still have room.

Card payments will be rejected when there's insufficient balance on the bank account regardless of the limits you set.

## Headers

<ParamField header="Idempotency-Key" type="string" required>
  A key that prevents issuing a duplicate card if the same request is retried.
  Reusing a key returns the originally created card instead of issuing a second
  one. See [Idempotency](/api-reference/idempotency).
</ParamField>

## Request body

<ParamField body="bank_account_id" type="string" required>
  The bank account this card draws from.
</ParamField>

<ParamField body="nickname" type="string" required>
  A human-readable label for this card. Between 1 and 50 characters.
</ParamField>

<ParamField body="authorization_controls" type="object" required>
  Controls that restrict how this card can be used.

  <Expandable title="Authorization controls fields">
    <ParamField body="usage" type="object" required>
      How many times this card can be used, and the controls for that usage.

      <Expandable title="Usage fields">
        <ParamField body="category" type="enum" required>
          Whether the card is for a single use or multiple uses.

          <Expandable title="Available options">
            <ResponseField name="multi_use" type="string">
              The card can be used for multiple authorizations. The only
              category issuable today.
            </ResponseField>
          </Expandable>
        </ParamField>

        <ParamField body="multi_use" type="object" required>
          Controls for multi-use cards. Required if and only if `category` is
          `multi_use`.

          <Expandable title="Multi-use fields">
            <ParamField body="spending_limits" type="object[]" required>
              The spending limits to enforce on this card. Must contain at least
              one limit and at most one limit per interval. Where several limits
              apply to a transaction, the most restrictive one wins.

              <Expandable title="Limit object">
                <ParamField body="interval" type="enum" required>
                  The window this limit is enforced over.

                  <Expandable title="Available options">
                    <ResponseField name="all_time" type="string">
                      Applies over the lifetime of the card.
                    </ResponseField>

                    <ResponseField name="per_transaction" type="string">
                      Applies to each individual transaction.
                    </ResponseField>

                    <ResponseField name="per_day" type="string">
                      Resets nightly at midnight UTC.
                    </ResponseField>

                    <ResponseField name="per_week" type="string">
                      Resets weekly on Mondays at midnight UTC.
                    </ResponseField>

                    <ResponseField name="per_month" type="string">
                      Resets on the first of the month at midnight UTC.
                    </ResponseField>
                  </Expandable>
                </ParamField>

                <ParamField body="amount" type="integer" required>
                  The cap on settled spend in this window, in cents. Must be
                  positive, and at least as large as the cap on every narrower
                  interval — a wider window capped below a narrower one can
                  never be reached, so it is rejected.
                </ParamField>
              </Expandable>
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

Returns the created card object.

<ResponseField name="id" type="string">
  Unique identifier for the card, prefixed with `card_`.
</ResponseField>

<ResponseField name="created_at" type="string">
  [ISO 8601](/api-reference/timestamps) timestamp of when the card was created.
</ResponseField>

<ResponseField name="entity_id" type="string">
  The ID of the entity that owns this card.
</ResponseField>

<ResponseField name="bank_account_id" type="string">
  The bank account this card draws from.
</ResponseField>

<ResponseField name="nickname" type="string | null">
  The human-readable label for this card.
</ResponseField>

<ResponseField name="last_4" type="string">
  The last 4 digits of the card number.
</ResponseField>

<ResponseField name="status" type="enum">
  The card's status.

  <Expandable title="Available options">
    <ResponseField name="active" type="string">
      The card can be used for payments.
    </ResponseField>

    <ResponseField name="disabled" type="string">
      The card is temporarily disabled.
    </ResponseField>

    <ResponseField name="canceled" type="string">
      The card is permanently canceled.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="authorization_controls" type="object">
  Every control restricting how this card can be used, including the ones Lemma
  applies to every card it issues.

  <Expandable title="Authorization controls object">
    <ResponseField name="usage" type="object">
      How many times this card can be used, and its controls.

      <Expandable title="Usage object">
        <ResponseField name="category" type="enum">
          Whether the card is for a single use or multiple uses.

          <Expandable title="Available options">
            <ResponseField name="multi_use" type="string">
              The card can be used for multiple authorizations. The only
              category issuable today.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="multi_use" type="object">
          Controls for multi-use cards.

          <Expandable title="Multi-use object">
            <ResponseField name="spending_limits" type="object[]">
              Every spending limit enforced on this card, including the ones
              Lemma applies automatically.

              <Expandable title="Limit object">
                <ResponseField name="interval" type="enum">
                  The window this limit is enforced over.

                  <Expandable title="Available options">
                    <ResponseField name="all_time" type="string">
                      Applies over the lifetime of the card.
                    </ResponseField>

                    <ResponseField name="per_transaction" type="string">
                      Applies to each individual transaction.
                    </ResponseField>

                    <ResponseField name="per_day" type="string">
                      Resets nightly at midnight UTC.
                    </ResponseField>

                    <ResponseField name="per_week" type="string">
                      Resets weekly on Mondays at midnight UTC.
                    </ResponseField>

                    <ResponseField name="per_month" type="string">
                      Resets on the first of the month at midnight UTC.
                    </ResponseField>
                  </Expandable>
                </ResponseField>

                <ResponseField name="amount" type="integer">
                  Cap in cents.
                </ResponseField>

                <ResponseField name="merchant_category_codes" type="string[] | null">
                  Merchant category codes this limit applies to. `null` applies
                  to all merchants.
                </ResponseField>
              </Expandable>
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="merchant_acceptor_identifier" type="object | null">
      Restricts which Merchant Acceptor IDs this card may transact with. `null`
      when this dimension is unrestricted.

      <Expandable title="Merchant acceptor identifier object">
        <ResponseField name="allowed" type="string[] | null">
          The only Merchant Acceptor IDs this card may transact with. `null`
          when this dimension is not an allow list.
        </ResponseField>

        <ResponseField name="blocked" type="string[] | null">
          Merchant Acceptor IDs this card may never transact with. `null` when
          this dimension is not a block list.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="merchant_category_code" type="object | null">
      Restricts which merchant categories this card may transact with, including
      the categories Lemma blocks on every card it issues. `null` when this
      dimension is unrestricted.

      <Expandable title="Merchant category code object">
        <ResponseField name="allowed" type="string[] | null">
          The only merchant category codes this card may transact with. `null`
          when this dimension is not an allow list.
        </ResponseField>

        <ResponseField name="blocked" type="string[] | null">
          Merchant category codes this card may never transact with. `null` when
          this dimension is not a block list.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="merchant_country" type="object | null">
      Restricts which merchant countries this card may transact with, as [ISO
      3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) codes.
      `null` when this dimension is unrestricted.

      <Expandable title="Merchant country object">
        <ResponseField name="allowed" type="string[] | null">
          The only merchant countries this card may transact with. `null` when
          this dimension is not an allow list.
        </ResponseField>

        <ResponseField name="blocked" type="string[] | null">
          Merchant countries this card may never transact with. `null` when this
          dimension is not a block list.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "card_Bx5nTm8hKw3pVd7c",
    "created_at": "2026-07-28T18:45:00Z",
    "entity_id": "entity_k7mXp2vR9nTfBw4s",
    "bank_account_id": "account_maple_ridge_cigna_01",
    "nickname": "Acme ops card",
    "last_4": "4242",
    "status": "active",
    "authorization_controls": {
      "usage": {
        "category": "multi_use",
        "multi_use": {
          "spending_limits": [
            { "interval": "per_transaction", "amount": 25000, "merchant_category_codes": null },
            { "interval": "per_day", "amount": 100000, "merchant_category_codes": null },
            { "interval": "per_day", "amount": 300000, "merchant_category_codes": ["6010", "6011"] }
          ]
        }
      },
      "merchant_acceptor_identifier": null,
      "merchant_category_code": { "allowed": null, "blocked": ["7995", "6051"] },
      "merchant_country": null
    }
  }
  ```

  ```json 400 theme={null}
  {
    "statusCode": 400,
    "error": "Bad Request",
    "message": [
      "authorization_controls.usage.multi_use.spending_limits amounts must not decrease as the interval widens (per_transaction, per_day, per_week, per_month, all_time)"
    ]
  }
  ```
</ResponseExample>