> ## 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.

# Limits · Overview

> Control spending and withdrawals with velocity rules: rule creation (five control groups), full-replacement updates with optimistic locking, batch bind/unbind with partial-success semantics, and querying merged effective quotas.

## 📄 Guide

Velocity rules are standalone objects: owned by a company, bound many-to-many to cards or employees, with the strictest value winning per dimension. This page walks "create → bind → query quota → adjust"; the concepts are in [Limits and statements](../basic-concepts/limits-and-billing).

## Creating a rule

`POST /open-api-corp/velocity/v1/create-rule` — send `ruleRef` (idempotency key: the same company + `ruleRef` on retry returns the first result), `organizationId`, `ruleName`, and **at least one** of the five control groups (none at all returns `DAPI_PARAM_INVALID`):

| Control group        | Content                                                                                                                                                                      |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `purchaseControl`    | Purchase limits: `amountLimits[]` per currency (`perTransaction` / `daily` / `monthly` / `quarterly` / `yearly`, all > 0) + `countLimits` (counts, summed across currencies) |
| `cashAdvanceControl` | Withdrawal limits: same structure, plus the group switch `allowed` (required within the group; `false` bans withdrawals outright)                                            |
| `currencyControl`    | Purchase-currency list: `type` (WHITELIST / BLACKLIST) + `currencies[]` (judged against the **original purchase currency**)                                                  |
| `mccControl`         | Merchant-category list: `type` + `mccList[]` (4 digits)                                                                                                                      |
| `geographicControl`  | Region list: `type` + `countryCodes[]` (two-letter ISO, uppercase; judged against the merchant country code)                                                                 |

<Warning>
  **"Unlimited" is expressed by omitting the field — never send 0 or a negative number** (`VELOCITY_LIMIT_VALUE_INVALID`). Amount limits match on the **settlement currency**, while `currencyControl` judges the original purchase currency — two different axes.
</Warning>

A new rule is always `ACTIVE`, but **constrains nothing until it is bound** to a card or employee. The response returns `ruleId`, `ruleVersion` (optimistic lock), `bindingCount` and more.

```json theme={null}
{
  "ruleRef": "ext-request-0001",
  "organizationId": "e7c9a1f0-3b52-4d8e-9a67-1f2b3c4d5e6f",
  "ruleName": "Employee travel",
  "purchaseControl": {
    "amountLimits": [
      { "currency": "USD", "perTransaction": "3000.00", "daily": "10000.00", "monthly": "80000.00" }
    ],
    "countLimits": { "daily": 5, "monthly": 100 }
  },
  "cashAdvanceControl": {
    "allowed": true,
    "amountLimits": [ { "currency": "USD", "perTransaction": "500.00", "daily": "2000.00" } ]
  }
}
```

## Binding and unbinding

**Bind**: `POST /open-api-corp/velocity/v1/bind` — one request addresses **one rule** (top-level `ruleId`) and a batch of subjects in `targets[]` (`subjectType` CARD / CUSTOMER + `subjectId`). Rule-level problems (missing / not ACTIVE) **reject the whole batch**; subject-level problems are **item-independent with partial success**: the response splits into `successTargets` and `failTargets`, with per-item reasons such as `SUBJECT_INVALID` / `CARD_RULE_DUPLICATE` / `CARD_RULE_CURRENCY_NOT_MATCH`. Rules can also be bound at issue time through `ruleIds`. A single card or employee carries at most 5 rules.

**Unbind**: `POST /open-api-corp/velocity/v1/unbind` — batch, partial success as above; a subject not bound to the rule fails per-item with `VELOCITY_BINDING_NOT_FOUND`.

**Query targets**: `list-rule-targets` (objects bound to a rule) and `list-target-rules` (rules constraining a card / employee; ACTIVE only by default).

## Querying effective quota

`GET /open-api-corp/velocity/v1/query-quota` — the **merged** effective limits and current usage for a card / employee, from which you compute the remainder. Key points:

* Each quota node returns `limitAmount` / `usedAmount` / `remainingAmount` / `utilizationRate` / `periodKey` / `sourceRuleId` — `sourceRuleId` names the rule the strictest value came from; `limit=null` means the dimension is uncapped (`usedAmount` still accumulates).
* `perTransaction` carries only `limitAmount` and `sourceRuleId` — per-transaction limits do not accumulate.
* Each currency group carries an `effective` flag: `false` + `NOT_CARD_SETTLEMENT_CURRENCY` means the currency is not among the card's settlement currencies and does not apply.
* `cashAdvance.allowed` is the merged switch: **false if any rule says false**, with `sourceRuleId` naming which one.
* `appliedRules` lists the rules in the merge (always ACTIVE — INACTIVE rules never participate).

## Adjusting rules

**Update**: `POST /open-api-corp/velocity/v1/update-rule` — **full-replacement semantics**: any dimension or control group absent from the request is deleted; `ruleVersion` must be echoed back, and a mismatch returns `VELOCITY_RULE_VERSION_CONFLICT` (concurrent modification — re-query and retry). Changes take effect **immediately** on bound objects.

**Enable / disable**: `POST /open-api-corp/velocity/v1/change-rule-status` — toggles `ACTIVE` ⇄ `INACTIVE` (also versioned). An `INACTIVE` rule takes no part in checks but keeps its targets; the response echoes `bindingCount` — before disabling, warn the customer that the rule currently constrains N objects.

**Detail / list**: `query-rule` (full configuration) and `list-rules` (paginated summaries, filterable by status).

## Next steps

* Bind rules at issue time: [Managing cards](./managing-cards)
* How limits participate in authorization: [Authorization and 3DS](./authorization-and-3ds)
* In this group: [Creating velocity rules](./creating-rules) · [Binding and unbinding](./binding-and-unbinding) · [Quota and adjustment](./quota-and-adjustment)