LIlightsparkdev
Cards

Create a card velocity limit

Changed on

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

Request

  • Base URL
    https://api.lightspark.com/grid/2025-10-13
  • URL
    https://api.lightspark.com/grid/2025-10-13/card-velocity-limits
  • Auth
    HTTP basic

Request body

cardIdstring nullable

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.

namestring required

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

metric'ATTEMPTS' | 'APPROVED' 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.

window'AUTHORIZATION' | 'ROLLING' | 'DAY' | 'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR' 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.

windowSecondsinteger nullable

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

maxCountinteger nullable

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

maxAmountinteger nullable

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.

Example request

{
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000003",
  "name": "Weekly card spending cap",
  "windowSeconds": 600,
  "maxCount": 5,
  "maxAmount": 50000
}

Response

The created rule.

cardIdstring nullable

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.

namestring required

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

metric'ATTEMPTS' | 'APPROVED' 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.

window'AUTHORIZATION' | 'ROLLING' | 'DAY' | 'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR' 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.

windowSecondsinteger nullable

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

maxCountinteger nullable

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

maxAmountinteger nullable

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.

idstring required

System-generated identifier for the rule.

Example response

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

Changes

  • 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

  • 5abf2bb56bcbRevision changes
    • warning

      added the new CORRIDOR_UNDER_MAINTENANCE enum value to the response property for the response status