LIlightsparkdev
Agent Operations

Tighten or freeze an agent card

Changed on

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}

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/agents/me/cards/{cardId}
  • Auth
    HTTP bearer

Request body

status'FROZEN'

Freeze the card. New authorizations are declined.

allowedMccsstring[]

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

blockedMccsstring[]

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.

Example request

{
  "status": "FROZEN",
  "allowedMccs": [
    "5411"
  ],
  "blockedMccs": [
    "5813"
  ]
}

Response

Card updated

agentIdstring required

The agent the card belongs to.

agentCardKind'STANDARD' | 'PURCHASE' required

How an agent card is used and funded.

KindDescription
STANDARDA 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.
PURCHASEA 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.
effectiveBlockedMccsstring[] required

Every merchant category code the card declines: blockedMccs plus the categories Grid blocks for agent cards, unless the platform lifted those defaults (defaultMccBlocksLifted).

Example response

{
  "card": {
    "id": "Card:019542f5-b3e7-1d02-0000-000000000010",
    "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
    "platformCardId": "card-emp-001",
    "pinStatus": "OK",
    "pinUnblockAvailableAt": "2026-10-15T15:00:00Z",
    "last4": "4242",
    "expMonth": 12,
    "expYear": 2029,
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "cardCapabilities": {
      "supportsVelocityLimits": true,
      "supportsPanReveal": true,
      "supportsDigitalWalletTokenization": true
    },
    "maxNetworkRiskScore": 700,
    "allowedMccs": [
      "5411"
    ],
    "blockedMccs": [
      "7995"
    ],
    "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
    "currency": "USD",
    "processorRef": "card_b81c2a4f",
    "issuerRef": "lead_card_7a1b9c3d",
    "createdAt": "2026-05-08T14:10:00Z",
    "updatedAt": "2026-05-08T14:11:00Z"
  },
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
  "effectiveBlockedMccs": [
    "7995",
    "6051"
  ],
  "purchase": {
    "amount": 4999,
    "spendLimit": 5749,
    "currency": "USD",
    "description": "Running shoes from example-store.com",
    "fundingSource": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
    "expiresAt": "2026-10-26T15:30:00Z"
  }
}

Changes

  • e3a3f79a161fRevision changes
    • info

      added the optional property / to the response with the status

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status