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

# Update card

> Freeze or unfreeze a card, or change its spending limits or merchant category restrictions.

Changes apply to every authorization from the moment the request succeeds, and the card keeps its number and history. If any part of the request is invalid, the whole request is rejected and the card stays as it was.

You can only update cards your platform issued: a card issued by the entity's staff in the Lemma app returns a `404`. A canceled card returns a `409`.

Send one update to a card at a time. Each update starts from the card's current controls, so two sent at once can overwrite each other.

## Headers

<ParamField header="Idempotency-Key" type="string" required>
  A key that prevents applying the same update twice if the request is retried.
  Reusing a key on the same card returns the card's current state instead of
  updating it again; reusing it on a different card returns a 422. See
  [Idempotency](/docs/api-reference/idempotency).
</ParamField>

## Path parameters

<ParamField path="card_id" type="string" required>
  The card's unique identifier.
</ParamField>

## Request body

Set `status`, `authorization_controls`, or both. A body with neither returns a
`400`.

<ParamField body="status" type="enum">
  Freezes or unfreezes the card. Omit it to keep the card's current status.
  `canceled` is not accepted; use [Cancel a card](/docs/api-reference/cancel-card)
  instead.

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

    <ResponseField name="disabled" type="string">
      Freezes the card: every new authorization is declined until it is set back
      to `active`.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="authorization_controls" type="object">
  The controls to change. Omit it to keep every control. When sent, it must set
  `usage`, `merchant_category_code`, or both, and the one you omit keeps its
  current value.

  <Expandable title="Authorization controls fields">
    <ParamField body="usage" type="object">
      How many times this card can be used, and the controls for that usage.
      Replaces the card's current usage and spending limits. Omit it to keep
      them.

      <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>

    <ParamField body="merchant_category_code" type="object | null">
      Restricts the card to, or bars it from, a list of merchant category codes
      (MCCs). Set exactly one of `allowed` or `blocked`: sending one clears the
      other. Omit it to keep the card's current restriction, or send `null` to
      remove it.

      <Expandable title="Merchant category code fields">
        <ParamField body="allowed" type="string[] | null">
          The only merchant category codes this card can be used at; every other
          code is declined. Each code is a 4-digit string such as `"8011"`.
          Ranges are not accepted, so list each code.
        </ParamField>

        <ParamField body="blocked" type="string[] | null">
          Merchant category codes this card is declined at. Lemma adds `7995`
          and `6051` to every block list, and an allow list cannot contain
          either code.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Response

Returns the updated card object.

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

<ResponseField name="created_at" type="string">
  [ISO 8601](/docs/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">
  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 200 theme={null}
  {
    "id": "card_Bx5nTm8hKw3p",
    "created_at": "2026-07-28T18:45:00Z",
    "entity_id": "entity_k7mXp2vR9nTf",
    "bank_account_id": "account_Qz8mVn2xTk6p",
    "nickname": "Acme ops card",
    "last_4": "4242",
    "status": "active",
    "authorization_controls": {
      "usage": {
        "category": "multi_use",
        "multi_use": {
          "spending_limits": [
            { "interval": "per_day", "amount": 300000, "merchant_category_codes": ["6010", "6011"] },
            { "interval": "per_transaction", "amount": 25000, "merchant_category_codes": null }
          ]
        }
      },
      "merchant_acceptor_identifier": null,
      "merchant_category_code": { "allowed": ["6300", "8011", "8021"], "blocked": null },
      "merchant_country": null
    }
  }
  ```

  ```json 400 theme={null}
  {
    "message": [
      "authorization_controls.merchant_category_code must set exactly one of allowed or blocked"
    ],
    "error": "Bad Request",
    "statusCode": 400
  }
  ```

  ```json 403 theme={null}
  {
    "message": "Insufficient permissions to update cards for this entity",
    "error": "Forbidden",
    "statusCode": 403
  }
  ```

  ```json 404 theme={null}
  {
    "message": "Card not found",
    "error": "Not Found",
    "statusCode": 404
  }
  ```

  ```json 409 theme={null}
  {
    "message": "Card is canceled",
    "error": "Conflict",
    "statusCode": 409
  }
  ```
</ResponseExample>


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