Velocity Controls

A velocity control limits how much users can spend. You can configure velocity controls to limit how much users can spend and the number of transactions they can make in a given span of time. You can apply velocity controls to a single user, to all users associated with a particular card product, or to all users in your program. Only Program Managers can create or modify program-wide velocity controls. A POST or PUT call from a role that does not have Program Manager permissions will receive a 403 error if its association field is null, or if it includes all of the fields in the request body. Avoid this by passing a valid user_token or card_product_token in the velocity control’s association object, indicating that the request is specific to a user or card product, and not program-wide. You should also only include the specific fields you want to update, because a PUT or POST with values for all fields is interpreted as a change that requires Program Manager permissions. See Controlling Spending for a tutorial that walks you through the creation of a spend control.

Note Each program supports a maximum of 90 spend controls (velocity controls and authorization controls combined). The limit of 90 spend controls applies at the program level only; it does not affect the number of user-level spend controls you can use.

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

{
  "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

{
  "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 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

{
  "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

{
  "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

{
  "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

{
  "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 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

{
  "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
      }
    }
  ]
}

​Create velocity control

​Request body

​Sample request body

​Response body

​Sample response body

​List velocity controls

​URL query parameters

​Response body

​Sample response body

​Returns a specific velocity control

​URL path parameters

​URL query parameters

​Response body

​Sample response body

​Update velocity control

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​List user velocity control balances

​URL path parameters

​URL query parameters

​Response body

​Sample response body

Create velocity control

Request body

Sample request body

Response body

Sample response body

List velocity controls

URL query parameters

Response body

Sample response body

Returns a specific velocity control

URL path parameters

URL query parameters

Response body

Sample response body

Update velocity control

URL path parameters

Request body

Sample request body

Response body

Sample response body

List user velocity control balances

URL path parameters

URL query parameters

Response body

Sample response body