> ## 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. # How to configure spend controls The following tutorial walks you through creating and testing a control in the public or private sandbox environment. You will create an authorization control that prevents users of your new card product from spending at liquor stores, which are represented by a single merchant category code. If you want to test these controls after you create them, make sure to track the user and card product tokens you specify throughout the tutorial. Creating and testing a spend control ### Step 1 — List existing controls Before creating a new control, consider any existing controls you might have at the program and card product levels. To view existing authorization controls, send a `GET` request to the `/authcontrols` endpoint. Make sure you understand your program's default authorization behavior (allow vs. deny). In the public/private sandbox environment, the program's default behavior is set to globally allow transactions at all merchants. ### Step 2 — Design your controls The business logic of the control you want to add determines the data you include in your request. * To block spending at all liquor stores, include the merchant category code in the `merchant_scope` object. * To apply the control to all users in your card product, include the card product token in the `association` object. To avoid receiving an error, include all other necessary parameters. * Create a meaningful name for the control: e.g. `Deny Liquor Stores`. * Create a unique token for the control: e.g. `deny_liquor_stores`. **Warning**
Do not use the example tokens shown in the tutorial while working in your public or private sandbox environment. If an object with the same token already exists, the system will handle the request as a duplicate, and your request will not take effect. ### Step 3 — Set up the authorization controls The following code block provides a JSON-formatted sample message body for creating your control. Copy the code sample and paste it into the body field of your `POST /authcontrols` request. Replace any placeholder text (`**UNIQUE TOKEN**`, `**CARD PRODUCT TOKEN**`) with your sample data, then submit the request. Review the response to ensure you successfully created the authorization control. ```json JSON lines wrap theme={null} { "token": "**UNIQUE TOKEN**", "name": "Deny Liquor Stores", "association": { "card_product_token": "**CARD PRODUCT TOKEN**" }, "merchant_scope": { "mcc": "5921" }, "active": true } ``` Alternatively, you can use the following sample cURL to create the same control. ```sh cURL lines wrap theme={null} curl \ -X POST \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \ -d '{ "token": "**UNIQUE TOKEN**", "name": "Deny Liquor Stores", "association": { "card_product_token": "**CARD PRODUCT TOKEN**" }, "merchant_scope": { "mcc": "5921" }, "active": true }' \ 'https://sandbox-api.marqeta.com/v3/authcontrols' ``` ### Step 4 — Confirm the new control exists To confirm that you created the control, send a `GET` request to the `/authcontrols` endpoint using the card product token you used previously. Replace any placeholder text (`**CARD PRODUCT TOKEN**`) with your sample data. Your new control should be included in the returned list. ```html HTML lines wrap theme={null} https://sandbox-api.marqeta.com/v3/authcontrols?card_product=**CARD PRODUCT TOKEN**&count=5&sort_by=-lastModifiedTime ``` ### Step 5 — Call the /simulations/cardtransactions endpoint To test if the control functions properly, simulate an authorization transaction by sending a `POST` request to the `/simulations/cardtransactions/authorization` endpoint. Test several transactions that each force the Marqeta platform to allow or deny them. The following sample message body creates a transaction that the Marqeta platform denies because of the authorization control created in the tutorial. Replace any placeholder text (`**YOUR CARD TOKEN**`) with your sample data. Change the MCC and resubmit the request to simulate a transaction that Marqeta allows. **Tip**
Ensure that the card token you enter in the message body references a sample card that is active and funded, otherwise the transaction will be declined due to lack of activation or insufficient funds. ```json JSON lines wrap theme={null} { "amount": "100", "card_token": "**YOUR CARD TOKEN**", "card_acceptor": { "mid": "12345", "mcc": "5921" }, "network": "VISA" } ``` **Tip**
If the transaction result is unexpected, check the response body for details on what went wrong. ## Samples Use the following samples to help build your program's spend controls. Each sample includes a description of the use case and sample JSON and cURL code snippets. ### Allow user spending at a single merchant You can limit a user's spending to a single merchant. This is handy if you are creating a rewards card that should only be used at a specific retailer or service. (Depending on your program's default authorization behavior, the same control could be used to block spending at a single merchant.) ```json JSON lines wrap theme={null} { "token": "**UNIQUE TOKEN**", "name": "Only Dunkin Donuts", "association": { "user_token": "**USER TOKEN REQUIRED**" }, "merchant_scope": { "mid": "252824676910001" }, "active": true } ``` ```sh cURL lines wrap theme={null} curl \ -X POST \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \ -d '{ "token": "**UNIQUE TOKEN**", "name": "Only Dunkin Donuts", "association": { "user_token": "**USER TOKEN REQUIRED**" }, "merchant_scope": { "mid": "252824676910001" }, "active": true }' \ 'https://sandbox-api.marqeta.com/v3/authcontrols' ``` ### Limit spending to \$100 per day Using a velocity control, you can cap the amount a user spends in a given timeframe. If, for example, you know your cardholders shouldn't spend more than \$100 per day, you could use a velocity control to deny any transactions beyond that limit. ```json JSON lines wrap theme={null} { "token": "**UNIQUE TOKEN**", "name": "100 Daily Spend Limit", "association": { "user_token": "**USER TOKEN**" }, "usage_limit": 100, "currency_code": "USD", "amount_limit": 100, "velocity_window": "DAY", "active": true } ``` ```sh cURL lines wrap theme={null} curl \ -X POST \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \ -d '{ "token": "**UNIQUE TOKEN**", "name": "100 Daily Spend Limit", "association": { "user_token": "**USER TOKEN**" }, "usage_limit": 100, "currency_code": "USD", "amount_limit": 100, "velocity_window": "DAY", "active": true }' \ 'https://sandbox-api.marqeta.com/v3/velocitycontrols' ``` ### Limit spending to \$100 per transaction You can limit a user's per-transaction spending by creating a velocity control with the `velocity_window` field set to TRANSACTION. ```json JSON lines wrap theme={null} { "token": "**UNIQUE TOKEN**", "name": "100 Per Transaction Limit", "association": { "user_token": "**USER TOKEN**" }, "currency_code": "USD", "amount_limit": 100, "velocity_window": "TRANSACTION", "active": true } ``` ```sh cURL lines wrap theme={null} curl \ -X POST \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \ -d '{ "token": "**UNIQUE TOKEN**", "name": "100 Per Transaction Limit", "association": { "user_token": "**USER TOKEN**" }, "currency_code": "USD", "amount_limit": 100, "velocity_window": "TRANSACTION", "active": true }' \ 'https://sandbox-api.marqeta.com/v3/velocitycontrols' ``` ### Limit users to one transaction per week at a category of merchants You can limit a user's maximum number of transactions for a given time period. For example, you can create a limited-use card product that prevents users from spending too frequently at a given merchant or category of merchants, such as hotels and motels. This is handy if you know how frequently a cardholder should be spending with their card. ```json JSON lines wrap theme={null} { "token": "**UNIQUE TOKEN**", "name": "One Transaction Per Week at Hotels", "association": { "card_product_token": "**CARD PRODUCT TOKEN REQUIRED**" }, "merchant_scope": { "mcc": "7011" }, "usage_limit": "1", "currency_code": "USD", "amount_limit": 1000, "velocity_window": "WEEK", "active": true } ``` ```sh cURL lines wrap theme={null} curl \ -X POST \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \ -d '{ "token": "**UNIQUE TOKEN**", "name": "One Transaction Per Week At Hotels", "association": { "card_product_token": "**CARD PRODUCT TOKEN REQUIRED**" }, "merchant_scope": { "mcc": "7011" }, "usage_limit": 1, "currency_code": "USD", "amount_limit": 1000, "velocity_window": "WEEK", "active": true }' \ 'https://sandbox-api.marqeta.com/v3/velocitycontrols' ``` ### Limit users to a single purchase You can add a velocity control that allows a user to spend exactly once. By setting the usage limit to one (a single transaction) and the velocity window to lifetime, users can spend up to the amount limit once. Any future attempts to spend are blocked. ```json JSON lines wrap theme={null} { "token": "**UNIQUE TOKEN**", "name": "Single Use Card", "association": { "card_product_token": "**CARD PRODUCT TOKEN REQUIRED**" }, "usage_limit": 1, "currency_code": "USD", "amount_limit": 1000, "velocity_window": "LIFETIME", "active": true } ``` ```sh cURL lines wrap theme={null} curl \ -X POST \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \ -d '{ "token": "**UNIQUE TOKEN**", "name": "Single Use Card", "association": { "card_product_token": "**CARD PRODUCT TOKEN**" }, "usage_limit": 1, "currency_code": "USD", "amount_limit": 1000, "velocity_window": "LIFETIME", "active": true }' \ 'https://sandbox-api.marqeta.com/v3/velocitycontrols' ``` ### Limit ATM withdrawals and bank transfers You can create a velocity control to limit the funds users can withdraw from ATMs or transfer from a bank. By setting the spending limit for ATMs and bank transfers to \$0, the user can only make retail purchases. ```json JSON lines wrap theme={null} { "token": "**UNIQUE TOKEN**", "name": "No ATMS or Bank Transfers", "association": { "user_token": "**USER TOKEN REQUIRED**" }, "usage_limit": 100, "approvals_only": true, "include_purchases": false, "include_cashbacks": false, "include_withdrawals": true, "include_transfers": true, "currency_code": "USD", "amount_limit": 0, "velocity_window": "MONTH", "active": true } ``` ```sh cURL expandable lines wrap theme={null} curl \ -X POST \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \ -d '{ "token": "**UNIQUE TOKEN**", "name": "No ATMS or Bank Transfers", "association": { "user_token": "**USER TOKEN**" }, "usage_limit": 100, "approvals_only": true, "include_purchases": false, "include_cashbacks": false, "include_withdrawals": true, "include_transfers": true, "currency_code": "USD", "amount_limit": 0, "velocity_window": "MONTH", "active": true }' \ 'https://sandbox-api.marqeta.com/v3/velocitycontrols' ``` ### List all velocity controls for a single user You can retrieve a list of all velocity controls applied at the program level, or use a query parameter to filter the list of controls by user or card product. ```html HTML lines wrap theme={null} https://sandbox-api.marqeta.com/v3/velocitycontrols?user=**USER TOKEN REQUIRED** ``` ```sh cURL lines wrap theme={null} curl \ -X GET \ --header 'Accept: application/json' \ --header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \ 'https://sandbox-api.marqeta.com/v3/velocitycontrols?user=**USER TOKEN REQUIRED**' ``` ## Related topics - [Velocity Controls](/docs/core-api/velocity-controls.md) - [Limits and Controls in Europe](/docs/developer-guides/mq-eu-limits-controls.md) - [Managing Customers in the Marqeta Dashboard](/docs/developer-guides/customers-dashboard.md) - [Authorization Controls](/docs/core-api/authorization-controls.md) - [About Cards](/docs/developer-guides/about-cards.md)