Tighten or freeze an agent card

Tighten a card’s merchant categories, or freeze it. An agent can never loosen a card or unfreeze it; the platform does that with PATCH /cards/{id}. Requires the MANAGE_CARDS permission.

PATCH /agents/me/cards/{cardId}

Tighten or freeze an agent card

cURL

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",
  "allowedMccs": [
    "5411"
  ],
  "blockedMccs": [
    "5813"
  ]
}
'

200

{
  "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",
    "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": {
      "supportsVelocityLimits": true,
      "supports3dSecurePassword": false,
      "supportsPanReveal": true,
      "supportsDigitalWalletTokenization": true
    },
    "maxNetworkRiskScore": 700,
    "allowedMccs": [
      "5411"
    ],
    "blockedMccs": [
      "7995"
    ],
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "defaultMccBlocksLifted": false,
    "lockedMerchant": {
      "descriptor": "BLUE BOTTLE COFFEE SF",
      "mcc": "5814",
      "city": "San Francisco",
      "state": "CA",
      "country": "US"
    },
    "currency": "USD",
    "processorRef": "card_b81c2a4f",
    "issuerRef": "lead_card_7a1b9c3d"
  },
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "agentCardKind": "STANDARD",
  "effectiveBlockedMccs": [
    "7995",
    "6051"
  ],
  "actingFor": "member_8f2c1a",
  "purchase": {
    "amount": 4999,
    "spendLimit": 5749,
    "currency": "USD",
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "increaseCardId": "Card:019542f5-b3e7-1d02-0000-000000000011",
    "previousAmount": 4999,
    "previousSpendLimit": 5749,
    "description": "Running shoes from example-store.com",
    "recurring": false,
    "expiresAt": "2026-10-26T15:30:00Z"
  }
}

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 freeze the card or tighten merchant categories: 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}. The platform manages card velocity limits through /card-velocity-limits.

status · enum<string>

Freeze the card. New authorizations are declined.

Available options: FROZEN

Example:

"FROZEN"

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

200

application/json

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 issued for the agent, by the platform with POST /cards or by the agent with POST /agents/me/cards. The customer holds the card details and its spend comes from the customer's account; that spend counts against the agent's policy limits as the agent's sends do. The agent can read the card, tighten its merchant categories, and freeze it.
PURCHASE	A single-use virtual card the agent issued for one online purchase with POST /agents/me/cards. It is funded from the customer's Embedded Wallet, its spend counts against the agent's policy limits, and it closes after its first approved authorization or when it expires unused. A recurring purchase card (purchase.recurring) is instead locked to the first merchant that charges it, may be charged there again up to its monthly limit, and stays open until it is closed. The agent reads its number, expiry and CVV through POST /agents/me/cards/{cardId}/reveal.

Available options: STANDARD, PURCHASE

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

actingFor · string

The platform's reference for the person the card was issued for: the issuing agent's actingFor when the card was issued. Absent when the agent had none.

Example:

"member_8f2c1a"

purchase · object

The purchase the card was issued for. Present for PURCHASE cards.

Show child attributes