> ## 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.
# Velocity Controls
> Use the velocity controls endpoint to limit how much your users can spend and the number of transactions they can make in a given window of time.
export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
const METHOD_STYLES = {
GET: {
bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
text: "mint-text-green-700 dark:mint-text-green-400",
border: "mint-border-green-300 dark:mint-border-green-700"
},
POST: {
bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
text: "mint-text-blue-700 dark:mint-text-blue-400"
},
PUT: {
bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
text: "mint-text-yellow-700 dark:mint-text-yellow-400"
},
PATCH: {
bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
text: "mint-text-orange-700 dark:mint-text-orange-400"
},
DELETE: {
bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
text: "mint-text-red-700 dark:mint-text-red-400"
},
API: {
bg: "mint-bg-black",
text: "mint-text-white"
}
};
const MethodBadge = ({method}) => {
const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
return
{method?.toUpperCase()}
;
};
const content =
{}
{}
{title}
{children &&
{children}
}
Create velocity control
**Action:** `POST`
**Endpoint:** `/velocitycontrols`
{/* */}
Limits how much and how frequently a user can spend funds. If multiple velocity controls apply to the same user, the user cannot exceed any of the defined spending limits.
**Tip**
You can create program-level controls in the sandbox environment. However, you must work with your Marqeta representative to create program-level controls in a production environment.
Request body
Velocity control object
| Fields | Description |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| active
boolean
Optional | Indicates whether the velocity control is active.
**Allowable Values:**
`true`, `false`
**Default value:**
`true` |
| amount\_limit
decimal
Required | 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
Required | Three-character ISO 4217 currency code.
**Allowable Values:**
Valid three-character ISO 4217 currency code |
| 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 (OCT) 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 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.
**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
Optional | Unique identifier of the velocity control.
If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.
**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.
Set to `-1` to indicate that the card can be used an unlimited number of times.
**Allowable Values:**
-1 min
-1 to 100 |
| velocity\_window
string
Required | 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.
- **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`, `LIFETIME`, `TRANSACTION` |
Sample request body
```json JSON lines wrap theme={null}
{
"usage_limit": 10,
"amount_limit": 500.25,
"velocity_window": "DAY",
"association": {
"user_token": "my_user_04"
},
"currency_code": "USD",
"token": "my_velocitycontrol_01"
}
```
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 |
| 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 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.
**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.
- **LIFETIME** – forever; time period never expires.
- **TRANSACTION** – a single transaction.
**Allowable Values:**
`DAY`, `WEEK`, `MONTH`, `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": 10,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"include_cashback": true,
"include_credits": false,
"currency_code": "USD",
"amount_limit": 500.25,
"velocity_window": "DAY",
"active": true
}
```
List velocity controls
**Action:** `GET`
**Endpoint:** `/velocitycontrols`
{/* */}
Retrieves a list of all the velocity controls associated with a specific user or card product, or lists all the velocity controls defined for your program.
Include either a `user` or a `card_product` query parameter to indicate the user or card product whose associated velocity controls you want to retrieve (do not include both).
To list all velocity controls for your program, omit the `user` and `card_product` query parameters from your request.
This endpoint supports [field filtering](/core-api/field-filtering/) and [pagination](/core-api/sorting-and-pagination/).
URL query parameters
| Fields | Description |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| card\_product
string
Optional | Unique identifier of the card product. Enter the string `null` to retrieve velocity controls that are not associated with any card product.
**Allowable Values:**
Existing card product token |
| user
string
Optional | Unique identifier of the user. Enter the string `null` to retrieve velocity controls that are not associated with any user.
**Allowable Values:**
Existing user token |
| count
integer
Optional | Number of velocity control resources to retrieve.
**Allowable Values:**
1-10
**Default value:**
5 |
| start\_index
integer
Optional | Sort order index of the first resource in the returned array.
**Allowable Values:**
Any integer
**Default value:**
0 |
| fields
string
Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.
**Allowable Values:**
Comma-delimited list of fields, or blank |
| sort\_by
string
Optional | Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order.
**Allowable Values:**
`createdTime`, `lastModifiedTime`, or any field in the resource model |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Conditionally returned | Number of resources retrieved.
This field is returned if there are resources in your returned array.
**Allowable Values:**
1-10 |
| data
array of objects
Conditionally returned | Array of velocity control objects.
Objects are returned as appropriate to your query.
**Allowable Values:**
Valid array of one or more velocity control objects |
| data\[].**active**
boolean
Conditionally returned | Indicates whether the velocity control is active.
**Allowable Values:**
`true`, `false` |
| data\[].**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 |
| data\[].**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` |
| data\[].**association**
object
Conditionally returned | Defines the group of users to which the velocity control applies.
**Allowable Values:**
`card_product_token`, `user_token` |
| data\[].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 |
| data\[].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 |
| data\[].**currency\_code**
string
Returned | Three-character ISO 4217 currency code.
**Allowable Values:**
Valid three-character ISO 4217 currency code |
| data\[].**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` |
| data\[].**include\_credits**
boolean
Conditionally returned | If set to `true`, original credit transactions (OCT) are subject to control.
**Allowable Values:**
`true`, `false` |
| data\[].**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 for more information)
- **Reversals:** All reversal transactions
**Allowable Values:**
`true`, `false` |
| data\[].**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` |
| data\[].**include\_withdrawals**
boolean
Conditionally returned | If set to `true`, ATM withdrawals are subject to control.
**Allowable Values:**
`true`, `false` |
| data\[].**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) |
| data\[].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 |
| data\[].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 |
| data\[].merchant\_scope.**mid**
string
Conditionally returned | Merchant identifier (MID). Identifies a specific merchant.
Enter a value to control spending with a particular merchant.
**Allowable Values:**
1–36 chars |
| data\[].**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 |
| data\[].**token**
string
Conditionally returned | Unique identifier of the velocity control.
**Allowable Values:**
1–36 chars |
| data\[].**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 |
| data\[].**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.
- **LIFETIME** – forever; time period never expires.
- **TRANSACTION** – a single transaction.
**Allowable Values:**
`DAY`, `WEEK`, `MONTH`, `LIFETIME`, `TRANSACTION` |
| end\_index
integer
Conditionally returned | Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| is\_more
boolean
Conditionally returned | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist.
This field is returned if there are resources in your returned array.
**Allowable Values:**
`true`, `false` |
| start\_index
integer
Conditionally returned | The sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"count": 1,
"start_index": 0,
"end_index": 0,
"is_more": false,
"data": [
{
"token": "my_velocitycontrol_01",
"association": {
"user_token": "my_user_04"
},
"merchant_scope": {},
"usage_limit": 10,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"include_cashback": true,
"include_credits": false,
"currency_code": "USD",
"amount_limit": 500.25,
"velocity_window": "DAY",
"active": true
}
]
}
```
Returns a specific velocity control
**Action:** `GET`
**Endpoint:** `/velocitycontrols/{token}`
{/* */}
Retrieves 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 |
URL query parameters
| Fields | Description |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fields
string
Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.
**Allowable Values:**
Comma-delimited list of fields, or blank |
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 |
| 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 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.
**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.
- **LIFETIME** – forever; time period never expires.
- **TRANSACTION** – a single transaction.
**Allowable Values:**
`DAY`, `WEEK`, `MONTH`, `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": 10,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"include_cashback": true,
"include_credits": false,
"currency_code": "USD",
"amount_limit": 500.25,
"velocity_window": "DAY",
"active": true
}
```
Update velocity control
**Action:** `PUT`
**Endpoint:** `/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 |
| 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 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.
**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.
- **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`, `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 |
| 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 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.
**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.
- **LIFETIME** – forever; time period never expires.
- **TRANSACTION** – a single transaction.
**Allowable Values:**
`DAY`, `WEEK`, `MONTH`, `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
}
```
List user velocity control balances
**Action:** `GET`
**Endpoint:** `/velocitycontrols/user/{user_token}/available`
{/* */}
Retrieves a list of the available balances of the velocity controls associated with a user. This operation is unavailable for velocity controls with a window of `TRANSACTION`, because available balances do not apply to single-transaction velocity windows.
Depending on the control, the balance can include an available monetary amount, the number of transactions remaining, and the number of days remaining in the time window.
This endpoint supports [field filtering](/core-api/field-filtering/) and [pagination](/core-api/sorting-and-pagination/).
URL path parameters
| Fields | Description |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| user\_token
string
Required | Unique identifier of the cardholder.
**Allowable Values:**
Existing user token |
URL query parameters
| Fields | Description |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| count
integer
Optional | Number of available balance resources to retrieve.
**Allowable Values:**
1-10
**Default value:**
5 |
| start\_index
integer
Optional | The sort order index of the first resource in the returned array.
**Allowable Values:**
Any integer
**Default value:**
0 |
| fields
string
Optional | Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields.
**Allowable Values:**
Comma-delimited list of fields, or blank |
| sort\_by
string
Optional | Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order.
**Allowable Values:**
`createdTime`, `lastModifiedTime`, or any field in the resource model |
Response body
| Fields | Description |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count
integer
Conditionally returned | Number of velocity control resources retrieved.
This field is returned if there are resources in your returned array.
**Allowable Values:**
1-10 |
| data
array of objects
Conditionally returned | Array of velocity control objects that include available balances.
Objects are returned as appropriate to your query.
**Allowable Values:**
Valid array of one or more velocity control objects |
| data\[].**active**
boolean
Conditionally returned | Indicates whether the velocity control is active.
**Allowable Values:**
`true`, `false` |
| data\[].**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 |
| data\[].**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` |
| data\[].**association**
object
Conditionally returned | Defines the group of users to which the velocity control applies.
**Allowable Values:**
`card_product_token`, `user_token` |
| data\[].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 |
| data\[].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 |
| data\[].**available**
object
Returned | Specifies the available balances of the velocity controls associated with a user.
This object is not returned if the velocity control window is `TRANSACTION`, because available balances do not apply to single-transaction velocity windows.
**Allowable Values:**
`amount`, `days_remaining`, `uses` |
| data\[].available.**amount**
decimal
Returned | Total amount of spend remaining in the velocity control.
**Allowable Values:**
0 min
**Format:**
0.00 |
| data\[].available.**days\_remaining**
integer
Conditionally returned | Number of days remaining in the velocity control time window.
**Allowable Values:**
255 char max |
| data\[].available.**uses**
integer
Returned | Number of uses remaining in the velocity control.
**Allowable Values:**
-1 to 100, where -1 indicates unlimited uses |
| data\[].**currency\_code**
string
Returned | Three-character ISO 4217 currency code.
**Allowable Values:**
Valid three-character ISO 4217 currency code |
| data\[].**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` |
| data\[].**include\_credits**
boolean
Conditionally returned | If set to `true`, original credit transactions (OCT) are subject to control.
**Allowable Values:**
`true`, `false` |
| data\[].**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 for more information)
- **Reversals:** All reversal transactions
**Allowable Values:**
`true`, `false` |
| data\[].**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` |
| data\[].**include\_withdrawals**
boolean
Conditionally returned | If set to `true`, ATM withdrawals are subject to control.
**Allowable Values:**
`true`, `false` |
| data\[].**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) |
| data\[].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 |
| data\[].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 |
| data\[].merchant\_scope.**mid**
string
Conditionally returned | Merchant identifier (MID). Identifies a specific merchant.
Enter a value to control spending with a particular merchant.
**Allowable Values:**
1–36 chars |
| data\[].**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 |
| data\[].**token**
string
Conditionally returned | Unique identifier of the velocity control.
**Allowable Values:**
1–36 chars |
| data\[].**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 |
| data\[].**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.
- **LIFETIME** – forever; time period never expires.
- **TRANSACTION** – a single transaction.
**Allowable Values:**
`DAY`, `WEEK`, `MONTH`, `LIFETIME`, `TRANSACTION` |
| end\_index
integer
Conditionally returned | Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
| is\_more
boolean
Conditionally returned | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist.
This field is returned if there are resources in your returned array.
**Allowable Values:**
`true`, `false` |
| start\_index
integer
Conditionally returned | Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.
**Allowable Values:**
Any integer |
Sample response body
```json JSON expandable lines wrap theme={null}
{
"count": 2,
"start_index": 0,
"end_index": 1,
"is_more": false,
"data": [
{
"token": "card_3",
"name": "Jane Doe",
"association": {},
"merchant_scope": {
"mcc": "3058"
},
"usage_limit": 1,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"include_cashback": true,
"include_credits": false,
"currency_code": "USD",
"amount_limit": 296.25,
"velocity_window": "DAY",
"active": true,
"available": {
"uses": 1,
"amount": 296,
"days_remaining": 1
}
},
{
"token": "card_4",
"association": {},
"merchant_scope": {
"mcc": "1234"
},
"usage_limit": 1000,
"approvals_only": true,
"include_purchases": true,
"include_withdrawals": true,
"include_transfers": true,
"include_cashback": true,
"include_credits": false,
"currency_code": "840",
"amount_limit": 500.25,
"velocity_window": "DAY",
"active": true,
"available": {
"uses": 1000,
"amount": 500.5,
"days_remaining": 1
}
}
]
}
```