Tighten or freeze an agent card

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "FROZEN",
  "maxSpendPerTransaction": 5000,
  "maxSpendPerDay": 20000,
  "maxTransactionsPerDay": 10,
  "allowedMccs": [
    "5411"
  ],
  "blockedMccs": [
    "5813"
  ]
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    status: 'FROZEN',
    maxSpendPerTransaction: 5000,
    maxSpendPerDay: 20000,
    maxTransactionsPerDay: 10,
    allowedMccs: ['5411'],
    blockedMccs: ['5813']
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"status\": \"FROZEN\",\n  \"maxSpendPerTransaction\": 5000,\n  \"maxSpendPerDay\": 20000,\n  \"maxTransactionsPerDay\": 10,\n  \"allowedMccs\": [\n    \"5411\"\n  ],\n  \"blockedMccs\": [\n    \"5813\"\n  ]\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId}")
  .patch(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "card": {
    "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "status": "PENDING_KYC",
    "form": "VIRTUAL",
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "maxSpendPerTransaction": 5000,
    "maxSpendPerDay": 25000,
    "maxTransactionsPerDay": 20,
    "createdAt": "2026-05-08T14:10:00Z",
    "updatedAt": "2026-05-08T14:11:00Z",
    "platformCardId": "card-emp-001",
    "statusReason": "DELEGATION_REQUIRED",
    "brand": "VISA",
    "pinStatus": "OK",
    "pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "cardCapabilities": {
      "supportsSpendLimits": true,
      "supportsSpendLimitsAtIssuance": true,
      "supportsTransactionCountLimit": true,
      "supports3dSecurePassword": false,
      "supportsPanReveal": true,
      "supportsDigitalWalletTokenization": true
    },
    "allowedMccs": [
      "5411"
    ],
    "blockedMccs": [
      "7995"
    ],
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "defaultMccBlocksLifted": false,
    "currency": "USD",
    "processorRef": "card_b81c2a4f",
    "issuerRef": "lead_card_7a1b9c3d"
  },
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentCardKind": "STANDARD",
  "effectiveBlockedMccs": [
    "7995",
    "6051"
  ],
  "spendLimit": {
    "amount": 2300,
    "duration": "TRANSACTION"
  },
  "reservedAmount": 2300,
  "expiresAt": "2026-10-10T15:30:00Z"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

PATCH

agents

cards

{cardId}

Tighten or freeze an agent card

curl --request PATCH \
  --url https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "status": "FROZEN",
  "maxSpendPerTransaction": 5000,
  "maxSpendPerDay": 20000,
  "maxTransactionsPerDay": 10,
  "allowedMccs": [
    "5411"
  ],
  "blockedMccs": [
    "5813"
  ]
}
'

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    status: 'FROZEN',
    maxSpendPerTransaction: 5000,
    maxSpendPerDay: 20000,
    maxTransactionsPerDay: 10,
    allowedMccs: ['5411'],
    blockedMccs: ['5813']
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"status\": \"FROZEN\",\n  \"maxSpendPerTransaction\": 5000,\n  \"maxSpendPerDay\": 20000,\n  \"maxTransactionsPerDay\": 10,\n  \"allowedMccs\": [\n    \"5411\"\n  ],\n  \"blockedMccs\": [\n    \"5813\"\n  ]\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId}")
  .patch(body)
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "card": {
    "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "status": "PENDING_KYC",
    "form": "VIRTUAL",
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "maxSpendPerTransaction": 5000,
    "maxSpendPerDay": 25000,
    "maxTransactionsPerDay": 20,
    "createdAt": "2026-05-08T14:10:00Z",
    "updatedAt": "2026-05-08T14:11:00Z",
    "platformCardId": "card-emp-001",
    "statusReason": "DELEGATION_REQUIRED",
    "brand": "VISA",
    "pinStatus": "OK",
    "pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "cardCapabilities": {
      "supportsSpendLimits": true,
      "supportsSpendLimitsAtIssuance": true,
      "supportsTransactionCountLimit": true,
      "supports3dSecurePassword": false,
      "supportsPanReveal": true,
      "supportsDigitalWalletTokenization": true
    },
    "allowedMccs": [
      "5411"
    ],
    "blockedMccs": [
      "7995"
    ],
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "defaultMccBlocksLifted": false,
    "currency": "USD",
    "processorRef": "card_b81c2a4f",
    "issuerRef": "lead_card_7a1b9c3d"
  },
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentCardKind": "STANDARD",
  "effectiveBlockedMccs": [
    "7995",
    "6051"
  ],
  "spendLimit": {
    "amount": 2300,
    "duration": "TRANSACTION"
  },
  "reservedAmount": 2300,
  "expiresAt": "2026-10-10T15:30:00Z"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

Bearer token authentication for agent-scoped endpoints. The token is the accessToken returned when redeeming a device code via POST /agents/device-codes/redeem. Agent credentials are user-scoped: all requests are automatically bound to the agent's associated customer and subject to the agent's policy.

Path Parameters

cardId

string

required

Unique identifier of the card

Body

application/json

Update request for PATCH /agents/me/cards/{cardId}. At least one field must be supplied. An agent may only tighten a card: a limit may be set or lowered but not raised or removed, blockedMccs must contain every code in the card's effectiveBlockedMccs, and allowedMccs may only lose codes once set. The only status an agent may set is FROZEN; unfreezing and loosening happen on the platform through PATCH /cards/{id}. A purchase card's spending limits are fixed at issuance: supplying maxSpendPerTransaction, maxSpendPerDay or maxTransactionsPerDay for one is a 400, while its merchant categories and status follow the rules above.

status

enum<string>

Freeze the card. New authorizations are declined.

Available options:

FROZEN

Example:

"FROZEN"

maxSpendPerTransaction

integer<int64>

A per-transaction limit at or below the current one, in the smallest unit of the card's currency.

Required range: 1 <= x <= 9007199254740991

Example:

5000

maxSpendPerDay

integer<int64>

A UTC-calendar-day spend cap at or below the current one.

Required range: 1 <= x <= 9007199254740991

Example:

20000

maxTransactionsPerDay

integer<int32>

A UTC-calendar-day transaction cap at or below the current one.

Required range: 1 <= x <= 2147483647

Example:

10

allowedMccs

string[]

Merchant category codes the card may spend at. Once set, a replacement must be a subset of the current list.

Minimum array length: 1

Pattern: ^[0-9]{4}$

Example:

["5411"]

blockedMccs

string[]

Merchant category codes the card declines. A replacement must contain every code in the card's effectiveBlockedMccs, so an agent can never lift a block, Grid's default agent blocks included.

Pattern: ^[0-9]{4}$

Example:

["5813"]

Response

Card updated

A card that belongs to the authenticated agent: the card itself and how the agent may use it.

card

object

required

Show child attributes

agentId

string

required

The agent the card belongs to.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000042"

agentCardKind

enum<string>

required

How an agent card is used and funded.

Kind	Description
`STANDARD`	A card the customer issued for the agent on the platform. The customer holds the card details and its spend is the customer's own; the agent can read it, tighten its limits, and freeze it.
`SINGLE_USE`	A purchase card the agent issued for one purchase. Its spend is reserved against the agent's policy at issuance and the card closes after its first authorization.
`MERCHANT_LOCKED`	A purchase card the agent issued for repeated purchases at one merchant, such as a subscription, capped by a monthly limit. Each authorization is checked against the agent's policy.

Available options:

STANDARD,

SINGLE_USE,

MERCHANT_LOCKED

effectiveBlockedMccs

string[]

required

Every merchant category code the card declines: blockedMccs plus the categories Grid blocks for agent cards, unless the platform lifted those defaults on a STANDARD card (defaultMccBlocksLifted). A purchase card's defaults cannot be lifted.

Pattern: ^[0-9]{4}$

Example:

["7995", "6051"]

spendLimit

object

The issuer-enforced cap. Present for purchase cards.

Show child attributes

reservedAmount

integer<int64>

Amount of the agent's spending limits currently held for this card, in the smallest unit of the card's currency. Present for purchase cards.

Required range: x >= 0

Example:

2300

expiresAt

string<date-time>

When Grid closes the card if it is still open. An unused SINGLE_USE card closes at this time and releases its reservation.

Example:

"2026-10-10T15:30:00Z"

Using the API

API documentation

Tighten or freeze an agent card

Authorizations

Path Parameters

Body

Response