--- title: "Create a card velocity limit" method: POST path: "/card-velocity-limits" tags: ["Cards"] --- # Create a card velocity limit `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 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. ## Request body - CreateCardVelocityRuleRequest - `cardId` string, 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. - `name` string, 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. - `windowSeconds` integer, nullable: Required for ROLLING and absent or null for other windows. The maximum rolling window is 31 days. - `maxCount` integer, nullable: Maximum count within the window. Required for ATTEMPTS. Cannot be set for AUTHORIZATION. Omit or send null to leave the count uncapped. - `maxAmount` integer, 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. ## Response `201` The created rule. - CardVelocityRule: A platform-managed card velocity rule. - `cardId` string, 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. - `name` string, 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. - `windowSeconds` integer, nullable: Required for ROLLING and absent or null for other windows. The maximum rolling window is 31 days. - `maxCount` integer, nullable: Maximum count within the window. Required for ATTEMPTS. Cannot be set for AUTHORIZATION. Omit or send null to leave the count uncapped. - `maxAmount` integer, 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. - `id` string, required: System-generated identifier for the rule. ## Other responses - `400`: Invalid rule or query parameters. - `401`: Unauthorized. - `403`: Insufficient permission. - `404`: Card or rule not found. - `409`: CONFLICT - A rule already exists for this card/platform, metric, window, and rolling duration. The reason identifies the existing rule to delete before creating a replacement. - `500`: Internal service error. - `501`: Cards are not enabled in this environment. ## Changes > 115 revisions in range; 2 not diffed. - **2026-10-28** `d996ddfb9d2b`: 5 info - added the optional property `details/missingFields` to the response with the `400` status - added the optional property `details/permission` to the response with the `403` status - added the optional property `details/policyDenialReason` to the response with the `403` status - added the optional property `details/refusalReason` to the response with the `400` status - …1 more - **2026-10-28** `5abf2bb56bcb`: 1 warning - added the new `CORRIDOR_UNDER_MAINTENANCE` enum value to the `code` response property for the response status `403` - **2026-10-27** `5fbda612feb8`: 1 info - endpoint added [Operation history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/card-velocity-limits/post.md) --- [API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) - [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lightsparkdev/apis/grid-api/revisions/7a1db46ec552?raw)