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"
  ]
}

{
  "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"
  ]
}

{
  "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}.

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. You can only send this when the card's cardCapabilities.supportsSpendLimits is true.

Required range: 1 <= x <= 9007199254740991

Example:

5000

maxSpendPerDay

integer<int64>

A UTC-calendar-day spend cap at or below the current one. You can only send this when the card's cardCapabilities.supportsSpendLimits is true.

Required range: 1 <= x <= 9007199254740991

Example:

20000

maxTransactionsPerDay

integer<int32>

A UTC-calendar-day transaction cap at or below the current one. You can only send this when the card's cardCapabilities.supportsTransactionCountLimit is true.

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 platform issued for the agent with `POST /cards`. 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.

Available options:

STANDARD

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 (defaultMccBlocksLifted).

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

Example:

["7995", "6051"]

Using the API

API documentation

Tighten or freeze an agent card

Authorizations

Path Parameters

Body

Response