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

# Update velocity control

> Updates a specific velocity control.

PUT/velocitycontrols/\{token}

Updates a specific velocity control.

## URL path parameters

| Fields | Description |
| - | - |
| token string  Required | Unique identifier of the velocity control resource. **Allowable Values:**  Existing velocity control token |

## Request body

| Fields | Description |
| - | - |
| active boolean  Optional | Indicates whether the velocity control is active. **Allowable Values:**  `true`, `false` **Default value:** `true` |
| amount\_limit decimal  Optional | Maximum monetary sum that can be cleared within the time period defined by the `velocity_window` field. Refunds and reversals cannot exceed this limit. **Allowable Values:**  0 min **Format:** 0.00 |
| approvals\_only boolean  Optional | If set to `true`, only approved transactions are subject to control. If set to `false`, only declined transactions are subject to control. **Allowable Values:**  `true`, `false` **Default value:** `true` |
| association object  Optional | Defines the group of users to which the velocity control applies. **Allowable Values:**  `card_product_token`, `user_token` |
| association.**card\_product\_token** string  Optional | Unique identifier of the card product. Pass either `card_product_token` or `user_token`, not both. **Allowable Values:**  1–36 chars |
| association.**user\_token** string  Optional | Unique identifier of the cardholder. Pass either `card_product_token` or `user_token`, not both. **Allowable Values:**  1–36 chars |
| currency\_code string  Optional | Three-character ISO 4217 currency code. **Allowable Values:**  Valid three-character [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) |
| include\_cashback boolean  Optional | If set to `true`, the cashback components of point-of-sale transactions are subject to control. **Allowable Values:**  `true`, `false` **Default value:** `true` |
| include\_credits boolean  Optional | If set to `true`, original credit transactions are subject to control. Your request can contain either a `money_in_transaction` object or the `include_credits` field, not both. **Allowable Values:**  `true`, `false` **Default value:** `false` |
| include\_purchases boolean  Optional | If set to `true`, the following transactions are subject to control: - **Account funding:** All account funding transactions - **Cashback:** Only the purchase component of cashback transactions - **Purchase transactions:** All authorizations, PIN debit transactions, and incremental transactions - **Quasi-cash:** All quasi-cash transactions - **Refunds:** All refund transactions (see [Controls to limit amount and frequency of spending](https://www.marqeta.com/docs/developer-guides/controlling-spending.md#_controls_to_limit_amount_and_frequency_of_spending) for more information) - **Reversals:** All reversal transactions **Allowable Values:**  `true`, `false` **Default value:** `true` |
| include\_transfers boolean  Optional | If set to `true`, account-to-account transfers are subject to control. Account-to-account transfers are not currently supported. **Allowable Values:**  `true`, `false` **Default value:** `true` |
| include\_withdrawals boolean  Optional | If set to `true`, ATM withdrawals are subject to control. **Allowable Values:**  `true`, `false` **Default value:** `true` |
| merchant\_scope object  Optional | Defines the group of merchants to which the velocity control applies. Populate no more than one field of the `merchant_scope` object. If no fields are populated, the velocity control applies to all merchants. **Allowable Values:**  `mcc`, `mcc_group`, `mid`, or null (no value) |
| merchant\_scope.**mcc** string  Optional | Merchant Category Code (MCC). Identifies the type of products or services provided by the merchant. Enter a value to control spending on a particular type of product or service. **Allowable Values:**  1–4 chars |
| merchant\_scope.**mcc\_group** string  Optional | Token identifying a group of MCCs. Enter a value to control spending on a group of product or service types. Send a `GET` request to `/mccgroups` to retrieve MCC group tokens. **Allowable Values:**  1–36 chars |
| merchant\_scope.**mid** string  Optional | Merchant identifier (MID). Identifies a specific merchant. Enter a value to control spending with a particular merchant. Use the exact MID value as it appears in the `card_acceptor.mid` field of your Gateway JIT Funding request or transaction webhook. Marqeta performs an exact match on this value — no normalization or formatting is applied. **Allowable Values:**  1–36 chars |
| name string  Optional | Description of how the velocity control restricts spending. For example, "Max spend of \$500 per day" or "Max spend of \$5000 per month for non-exempt employees". Ensure that the description you provide here adequately captures the kind of restriction exerted by this velocity control, because the Marqeta platform will send this information to you in a webhook in the event that the transaction authorization attempt is declined by the velocity control. **NOTE:** This field is very important. If your program has multiple velocity controls in place, it is not always clear which one prevented the transaction from being approved. Adding specific details to this field gives you more contextual information when debugging or monitoring declined authorization attempts. **Allowable Values:**  255 char max |
| token string  Required | Unique identifier of the velocity control resource. **Allowable Values:**  1–36 chars |
| usage\_limit integer  Optional | Maximum number of times a card can be used within the time period defined by the `velocity_window` field. If `velocity_window` is set to `TRANSACTION`, do not include a `usage_limit` in your request. **Allowable Values:**  -1 min  -1 to 100, where -1 indicates unlimited uses |
| velocity\_window string  Optional | Defines the time period to which the `amount_limit` and `usage_limit` fields apply: - **DAY** – one day; days begin at 00:00:00 UTC. - **WEEK** – one week; weeks begin Sundays at 00:00:00 UTC. - **MONTH** – one month; months begin on the first day of month at 00:00:00 UTC. - **QUARTER** – one calendar quarter; quarters begin on the first day of the quarter (January 1, April 1, July 1, or October 1). - **YEAR** – one calendar year; years begin on January 1. - **LIFETIME** – forever; time period never expires. - **TRANSACTION** – a single transaction. **NOTE:** If set to `DAY`, `WEEK`, or `MONTH`, the velocity control takes effect retroactively from the beginning of the specified period. The amount and usage data already collected within the first period is counted toward the limits. If set to `LIFETIME`, the velocity control only applies to transactions on or after the date and time that the velocity control was created. `LIFETIME` velocity controls are not retroactively applied to historical transactions. **Allowable Values:**  `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`, `LIFETIME`, `TRANSACTION` |

## Sample request body

```json JSON lines wrap theme={null}
{
  "token": "my_velocitycontrol_01",
  "usage_limit": 20,
  "amount_limit": 1000.25
}
```

## Response body

| Fields | Description |
| - | - |
| active boolean  Conditionally returned | Indicates whether the velocity control is active. **Allowable Values:**  `true`, `false` |
| amount\_limit decimal  Returned | Maximum monetary sum that can be cleared within the time period defined by the `velocity_window` field. Refunds and reversals cannot exceed this limit. **Allowable Values:**  0 min **Format:** 0.00 |
| approvals\_only boolean  Conditionally returned | If set to `true`, only approved transactions are subject to control. If set to `false`, only declined transactions are subject to control. **Allowable Values:**  `true`, `false` |
| association object  Conditionally returned | Defines the group of users to which the velocity control applies. **Allowable Values:**  `card_product_token`, `user_token` |
| association.**card\_product\_token** string  Conditionally returned | Unique identifier of the card product. Pass either `card_product_token` or `user_token`, not both. **Allowable Values:**  1–36 chars |
| association.**user\_token** string  Conditionally returned | Unique identifier of the cardholder. Pass either `card_product_token` or `user_token`, not both. **Allowable Values:**  1–36 chars |
| currency\_code string  Returned | Three-character ISO 4217 currency code. **Allowable Values:**  Valid three-character [ISO 4217 currency code](https://www.iso.org/iso-4217-currency-codes.html) |
| include\_cashback boolean  Conditionally returned | If set to `true`, the cashback components of point-of-sale transactions are subject to control. **Allowable Values:**  `true`, `false` |
| include\_credits boolean  Conditionally returned | If set to `true`, original credit transactions (OCT) are subject to control. **Allowable Values:**  `true`, `false` |
| include\_purchases boolean  Conditionally returned | If set to `true`, the following transactions are subject to control: - **Account funding:** All account funding transactions - **Cashback:** Only the purchase component of cashback transactions - **Purchase transactions:** All authorizations, PIN debit transactions, and incremental transactions - **Quasi-cash:** All quasi-cash transactions - **Refunds:** All refund transactions (see [Controls to limit amount and frequency of spending](https://www.marqeta.com/docs/developer-guides/controlling-spending.md#_controls_to_limit_amount_and_frequency_of_spending) for more information) - **Reversals:** All reversal transactions **Allowable Values:**  `true`, `false` |
| include\_transfers boolean  Conditionally returned | If set to `true`, account-to-account transfers are subject to control. Account-to-account transfers are not currently supported. **Allowable Values:**  `true`, `false` |
| include\_withdrawals boolean  Conditionally returned | If set to `true`, ATM withdrawals are subject to control. **Allowable Values:**  `true`, `false` |
| merchant\_scope object  Conditionally returned | Defines the group of merchants to which the velocity control applies. Populate no more than one field of the `merchant_scope` object. If no fields are populated, the velocity control applies to all merchants. **Allowable Values:**  `mcc`, `mcc_group`, `mid`, or null (no value) |
| merchant\_scope.**mcc** string  Conditionally returned | Merchant Category Code (MCC). Identifies the type of products or services provided by the merchant. Enter a value to control spending on a particular type of product or service. **Allowable Values:**  1–4 chars |
| merchant\_scope.**mcc\_group** string  Conditionally returned | Token identifying a group of MCCs. Enter a value to control spending on a group of product or service types. Send a `GET` request to `/mccgroups` to retrieve MCC group tokens. **Allowable Values:**  1–36 chars |
| merchant\_scope.**mid** string  Conditionally returned | Merchant identifier (MID). Identifies a specific merchant. Enter a value to control spending with a particular merchant. Use the exact MID value as it appears in the `card_acceptor.mid` field of your Gateway JIT Funding request or transaction webhook. Marqeta performs an exact match on this value — no normalization or formatting is applied. **Allowable Values:**  1–36 chars |
| name string  Conditionally returned | Description of how the velocity control restricts spending. For example, "Max spend of \$500 per day" or "Max spend of \$5000 per month for non-exempt employees". **Allowable Values:**  255 char max |
| token string  Conditionally returned | Unique identifier of the velocity control. **Allowable Values:**  1–36 chars |
| usage\_limit integer  Conditionally returned | Maximum number of times a card can be used within the time period defined by the `velocity_window` field. **Allowable Values:**  -1 min  -1 to 100, where -1 indicates unlimited uses |
| velocity\_window string  Returned | Defines the time period to which the `amount_limit` and `usage_limit` fields apply: - **DAY** – one day; days begin at 00:00:00 UTC. - **WEEK** – one week; weeks begin Sundays at 00:00:00 UTC. - **MONTH** – one month; months begin on the first day of month at 00:00:00 UTC. - **QUARTER** – one calendar quarter; quarters begin on the first day of the quarter (January 1, April 1, July 1, or October 1). - **YEAR** – one calendar year; years begin on January 1. - **LIFETIME** – forever; time period never expires. - **TRANSACTION** – a single transaction. **Allowable Values:**  `DAY`, `WEEK`, `MONTH`, `QUARTER`, `YEAR`, `LIFETIME`, `TRANSACTION` |

## Sample response body

```json JSON lines wrap theme={null}
{
  "token": "my_velocitycontrol_01",
  "association": {
    "user_token": "my_user_04"
  },
  "merchant_scope": {},
  "usage_limit": 20,
  "approvals_only": true,
  "include_purchases": true,
  "include_withdrawals": true,
  "include_transfers": true,
  "include_cashback": true,
  "include_credits": false,
  "currency_code": "USD",
  "amount_limit": 1000.25,
  "velocity_window": "DAY",
  "active": true
}
```


## Related topics

- [Velocity Controls Overview](https://www.marqeta.com/docs/core-api/velocity-controls.md)
- [Update Commando Mode control set](https://www.marqeta.com/docs/core-api/commando-mode-addendum/update-control-set.md)
- [List velocity controls](https://www.marqeta.com/docs/core-api/velocity-controls/list-velocity-controls.md)
- [Velocity Controls Object](https://www.marqeta.com/docs/core-api/velocity-controls/velocity-controls-object.md)
- [Create velocity control](https://www.marqeta.com/docs/core-api/velocity-controls/create-velocity-control.md)