> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Velocity limit query

> Explains how velocity limits work (transaction type × time period × amount or count cap), how to query them, and what each response field means.

## 📄 Guide

Whether your users are making everyday purchases, paying across borders or withdrawing large amounts, you can look up the velocity limit rules and current usage of any card at any time, and use that to show the available headroom to the cardholder and monitor risk. As a licensed issuer with its own BINs, DCS writes the velocity limit rules onto the card at issuance and accumulates usage in real time for you to query.

Velocity limits are a risk control mechanism that caps either the **number of transactions** or the **transaction amount** for a single card within a given period. Well-chosen limits help prevent fraud, contain spending risk, and give partners a lever for managing cash flow.

## Mental model: one velocity limit rule = three dimensions

A card can carry several velocity limit rules at once, and each rule combines three dimensions:

```
Transaction type (e.g. R, retail purchase) × Time period (e.g. 4, calendar month) × Cap type (amount maxAmount / count maxCount)
```

For example, "retail purchase × calendar month × maximum amount of 5,000 USD" is one rule. DCS accumulates `usedAmount` in real time and derives `remainingAmount`, then approves or declines authorizations accordingly.

> **Who does it**: velocity limit rules are defined in the **card profile** and applied automatically by DCS when the card is issued, so partners do not configure them card by card. This endpoint is **read-only** and cannot change a limit. To adjust the rules, contact the DCS team to update the card profile (see [Card profile](./card-profiles)).

### Transaction type (transactionType)

| Code  | Transaction type            |
| :---- | :-------------------------- |
| **R** | Retail purchase             |
| **C** | Cash withdrawal             |
| **I** | Standard installment        |
| **L** | Special-purpose installment |
| **S** | Cash installment            |
| **Q** | Balance inquiry             |
| **P** | Repayment                   |
| **A** | Proxy authorization         |

### Time period (periodUnit)

| Code  | Period unit                    |
| :---- | :----------------------------- |
| **1** | Per-transaction limit          |
| **2** | Calendar day limit             |
| **3** | Calendar week limit            |
| **4** | Calendar month limit           |
| **5** | Calendar year limit            |
| **6** | Billing cycle limit            |
| **7** | Rolling period limit (monthly) |

<Note>
  period unit `7` (rolling period limit) appears only in the API field definition, not in the body of the velocity limit guide. Both are documented as they stand; the API response is authoritative.
</Note>

## Query the velocity limits of a card

**`GET /open-api/card/v1/card-velocity-limits`**

> All date fields on this endpoint are in **UTC**.

### Request parameters

| Field    | In    | Type   | Required | Description                                                        |
| -------- | ----- | ------ | -------- | ------------------------------------------------------------------ |
| `cardId` | query | string | Required | Card ID, returned once the card has been issued. Maximum length 50 |

### Request example

```http theme={null}
GET /open-api/card/v1/card-velocity-limits?cardId=CARD_xxx
```

### Response

Every response uses the standard envelope `{ code, message, messageDetail, data }`:

* `code` / `message`: system-level return code and text.
* `messageDetail`: a message you can show to the end user (`title` / `message` / `type` / `action` / `linkUrl` and similar), meant for frontend guidance.
* `data`: an **array** of velocity limit rules, one element per rule.

Fields inside `data[]`:

| Field             | Type    | Description                                                  |
| ----------------- | ------- | ------------------------------------------------------------ |
| `transactionType` | string  | Transaction type code (R/C/I/L/S/Q/P/A, see the table above) |
| `velocityCode`    | string  | Velocity check code identifying the specific rule            |
| `periodUnit`      | string  | Period unit code (1-7, see the table above)                  |
| `startDate`       | string  | Start of the accumulation window, `yyyy-MM-dd`, UTC          |
| `endDate`         | string  | End of the accumulation window, `yyyy-MM-dd`, UTC            |
| `currencyCode`    | string  | Currency code                                                |
| `maxAmount`       | number  | Maximum amount (used by amount-based rules)                  |
| `maxCount`        | integer | Maximum number of transactions (used by count-based rules)   |
| `usedAmount`      | number  | Amount already used                                          |
| `usedCount`       | integer | Number of transactions already used                          |
| `remainingAmount` | number  | Remaining available amount                                   |
| `remainingCount`  | integer | Remaining available transactions                             |

### Response example

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": [
    {
      "transactionType": "R",
      "velocityCode": "R-MONTH-AMT",
      "periodUnit": "4",
      "startDate": "2026-06-01",
      "endDate": "2026-06-30",
      "currencyCode": "USD",
      "maxAmount": 5000,
      "maxCount": null,
      "usedAmount": 1280.50,
      "usedCount": null,
      "remainingAmount": 3719.50,
      "remainingCount": null
    },
    {
      "transactionType": "C",
      "velocityCode": "C-DAY-CNT",
      "periodUnit": "2",
      "startDate": "2026-06-16",
      "endDate": "2026-06-16",
      "currencyCode": "USD",
      "maxAmount": null,
      "maxCount": 3,
      "usedAmount": null,
      "usedCount": 1,
      "remainingAmount": null,
      "remainingCount": 2
    }
  ]
}
```

> The standard envelope is `{ code, message, messageDetail, data }`, and on success `code` is `SYS_SUCCESS`.

### How to use these fields

* **Showing available headroom to the cardholder**: read `remainingAmount` for amount-based rules and `remainingCount` for count-based rules.
* **Telling which kind of rule you are looking at**: a populated `maxAmount` means an amount cap, a populated `maxCount` means a count cap. Within one rule only one of the two is normally set, and the other is `null`.
* **Reading the accumulation window**: `startDate` and `endDate` delimit the current window (UTC); usage resets according to the period rule once the window closes.

## Next steps

* Where the rules are defined and how to change them: see [Card profile](./card-profiles).
* Basic card information and status: see [Virtual card](./virtual-card) and [Card management](./card-management).
* The standard response envelope and return codes: see [Authentication and security](../../integration-resources/authentication).