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

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({status: 'FROZEN', 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  \"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",
    "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"
  }
}

{
  "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"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

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

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

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

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({status: 'FROZEN', 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  \"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",
    "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"
  }
}

{
  "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"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

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

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

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

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

Using the API

API documentation

Tighten or freeze an agent card

Authorizations

Path Parameters

Body

Response