Create a card velocity limit

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/card-velocity-limits \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Five attempts in ten minutes",
  "metric": "ATTEMPTS",
  "window": "ROLLING",
  "windowSeconds": 600,
  "maxCount": 5
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Five attempts in ten minutes',
    metric: 'ATTEMPTS',
    window: 'ROLLING',
    windowSeconds: 600,
    maxCount: 5
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/card-velocity-limits', 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  \"name\": \"Five attempts in ten minutes\",\n  \"metric\": \"ATTEMPTS\",\n  \"window\": \"ROLLING\",\n  \"windowSeconds\": 600,\n  \"maxCount\": 5\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/card-velocity-limits")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

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

{
  "name": "Weekly card spending cap",
  "metric": "ATTEMPTS",
  "window": "AUTHORIZATION",
  "id": "CardVelocityRule:019542f5-b3e7-1d02-0000-000000000004",
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000003",
  "windowSeconds": 600,
  "maxCount": 5,
  "maxAmount": 50000
}

{
  "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": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

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

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

Cards

Create a card velocity limit

Create a rule for one card or for every eligible card on your platform. A rule with the same cardId, metric, window, and windowSeconds returns 409 CONFLICT, even if its name or caps differ. The error identifies the existing rule. Delete that rule before creating its replacement; these requests are separate operations, so other applicable limits govern authorizations between them. Different windows, rolling durations, and card/platform scopes may coexist. At least one cap is required. A target can hold at most 50 rules. Amounts use the smallest unit of each card’s currency; USD- and USDB-funded USD cards both use USD cents.

Manage per-authorization amount, UTC calendar amount/count, and rolling amount/count caps through this collection. Limits are not configured on card issuance/update requests or platform cardConfigs. APPROVED counts approved authorizations, including zero-amount approvals; ATTEMPTS counts real-time authorization requests, including declines. Reversals and expiries restore held-amount capacity but do not remove an approved authorization from the count. Clearing against a hold does not restore amount capacity. Resolve each cap at the most specific configured scope: card, then platform, then program. Amount and count inherit separately for each metric/window; rolling durations are distinct windows. Deleting the last cap at a scope restores the next configured scope.

Applies only where Grid makes authorization decisions. A cardId naming a provider-decided card is rejected. Platform-wide rules apply separately to each eligible card. AUTHORIZATION caps also protect asynchronous authorizations; ATTEMPTS counts real-time requests only. Settlement of previously authorized transactions continues even if a rule is tightened.

POST

card-velocity-limits

Create a card velocity limit

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/card-velocity-limits \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Five attempts in ten minutes",
  "metric": "ATTEMPTS",
  "window": "ROLLING",
  "windowSeconds": 600,
  "maxCount": 5
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Five attempts in ten minutes',
    metric: 'ATTEMPTS',
    window: 'ROLLING',
    windowSeconds: 600,
    maxCount: 5
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/card-velocity-limits', 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  \"name\": \"Five attempts in ten minutes\",\n  \"metric\": \"ATTEMPTS\",\n  \"window\": \"ROLLING\",\n  \"windowSeconds\": 600,\n  \"maxCount\": 5\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/card-velocity-limits")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

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

{
  "name": "Weekly card spending cap",
  "metric": "ATTEMPTS",
  "window": "AUTHORIZATION",
  "id": "CardVelocityRule:019542f5-b3e7-1d02-0000-000000000004",
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000003",
  "windowSeconds": 600,
  "maxCount": 5,
  "maxAmount": 50000
}

{
  "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": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

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

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

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Body

application/json

name

string

required

A descriptive label for this rule. Whitespace-only names are rejected.

Required string length: 1 - 255

Example:

"Weekly card spending cap"

metric

enum<string>

required

ATTEMPTS counts every real-time authorization request, including declined requests. APPROVED counts distinct approved authorizations, including zero-amount authorizations, and can also cap the amount they hold.

Available options:

ATTEMPTS,

APPROVED

window

enum<string>

required

AUTHORIZATION caps one authorization amount. ROLLING covers the trailing windowSeconds. Calendar windows use UTC: DAY starts at midnight, WEEK on Monday, MONTH on the first, QUARTER in January/April/July/October, and YEAR on January 1.

Available options:

AUTHORIZATION,

ROLLING,

DAY,

WEEK,

MONTH,

QUARTER,

YEAR

cardId

string | null

Card to restrict. Omit or send null to apply the rule separately to every eligible card on your platform, including cards issued later. A platform rule does not pool usage across cards.

Example:

"Card:019542f5-b3e7-1d02-0000-000000000003"

windowSeconds

integer | null

Required for ROLLING and absent or null for other windows. The maximum rolling window is 31 days.

Required range: 1 <= x <= 2678400

Example:

600

maxCount

integer | null

Maximum count within the window. Required for ATTEMPTS. Cannot be set for AUTHORIZATION. Omit or send null to leave the count uncapped.

Required range: 0 <= x <= 100000

Example:

5

maxAmount

integer<int64> | null

Maximum amount in the smallest unit of the card's currency. Supported for APPROVED only. Platform rules apply this amount separately to each eligible card in that card's currency, without foreign-exchange conversion. USD- and USDB-funded USD cards both use USD cents. The amount is holds less releases for transactions opened within the window. Releases restore capacity; clearing against a hold does not. Omit or send null to leave the amount uncapped. At least one of maxCount or maxAmount must be set. A zero cap blocks applicable new authorizations, including zero-amount checks.

Required range: 0 <= x <= 9007199254740991

Example:

50000

Response

The created rule.

A platform-managed card velocity rule.

name

string

required

A descriptive label for this rule. Whitespace-only names are rejected.

Required string length: 1 - 255

Example:

"Weekly card spending cap"

metric

enum<string>

required

Available options:

ATTEMPTS,

APPROVED

window

enum<string>

required

Available options:

AUTHORIZATION,

ROLLING,

DAY,

WEEK,

MONTH,

QUARTER,

YEAR

string

required

System-generated identifier for the rule.

Example:

"CardVelocityRule:019542f5-b3e7-1d02-0000-000000000004"

cardId

string | null

Card to restrict. Omit or send null to apply the rule separately to every eligible card on your platform, including cards issued later. A platform rule does not pool usage across cards.

Example:

"Card:019542f5-b3e7-1d02-0000-000000000003"

windowSeconds

integer | null

Required for ROLLING and absent or null for other windows. The maximum rolling window is 31 days.

Required range: 1 <= x <= 2678400

Example:

600

maxCount

integer | null

Maximum count within the window. Required for ATTEMPTS. Cannot be set for AUTHORIZATION. Omit or send null to leave the count uncapped.

Required range: 0 <= x <= 100000

Example:

5

maxAmount

integer<int64> | null

Required range: 0 <= x <= 9007199254740991

Example:

50000

Using the API

API documentation

Create a card velocity limit

Authorizations

Body

Response