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

# Manage spending limits

> A **spending limit** defines the maximum amount that can be spent on a card during a given time period. For example, £10 a day.

When a spending limit on a card is updated, it does not reset the time period or the spending amount already used. Instead, the existing tracking continues as if the limit had not been changed. If a transaction is refunded, the refunded amount is reinstated to the spending limit, but the transaction still counts against the usage limit. For example, if a card has a weekly limit of £1,000, and the user spends £600, they have £400 remaining for that week. If you update the limit to £2,000, the system does not reset the spent amount. The user will now have £1,400 remaining for the rest of the week, not a fresh £2,000. If the £600 spent was refunded, the user will now have £2,000 remaining for the rest of the week.
A card can have both a spending limit and a transaction limit. [Learn more about transaction limits](/pages/cards/manage-transaction-limits).

<Info>
  The endpoints described in this guide are currently in beta mode.
</Info>

## Create a spending limit

<Note>
  **POST** `/v2/cards/{cardId}/spending-limits`
</Note>

### Request

Use this request to create a new spending limit for a given card.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/cards/e9293471-5eb3-4dbc-916c-dbaf9e2deefd/spending-limits?accountId=F12345&budgetId=775596ae-2624-40af-a9dc-9756110a4a03' \
    -H 'Authorization: ApiKey 9cd30b49-812e-46ac-a222-7ce73e9c9dbc' \
    -H 'Content-Type: application/json' \
    -d '{
      "amount": 100.5,
      "active": false,
      "currencyCode": "GBP",
      "limitTurnedOff": true,
      "limitWindow": "DAY"
    }'
  ```

  ```bash Request structure theme={null}
  curl -i -X POST \
    'https://api.equalsmoney.com/v2/cards/{cardId}/spending-limits?accountId={accountId}&budgetId={budgetId}' \
    -H 'Authorization: ApiKey 9cd30b49-812e-46ac-a222-7ce73e9c9dbc' \
    -H 'Content-Type: application/json' \
    -d '{
      "amount": number,
      "active": boolean,
      "currencyCode": "string",
      "limitTurnedOff": boolean,
      "limitWindow": "string"
    }'
  ```
</CodeGroup>

#### Path parameters

<ParamField body="cardId" type="string (uuid)" required>
  The ID of the card that you want to create a new spending limit for.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that the card is associated with.

  Allowable values: An existing `accountId`
</ParamField>

<ParamField body="budgetId" type="string (uuid)" required>
  The ID of the budget that the card is associated with.

  Allowable values: An existing `budgetId` (≤ 36 characters)
</ParamField>

<ParamField body="personId" type="string (uuid)">
  The ID of the person that the card belongs to.

  Allowable values: An existing `personId` (≤ 36 characters)
</ParamField>

#### Request body schema

<ParamField body="amount" type="number" required>
  The amount that you want to set as the spending limit.

  Allowable values: A valid number
</ParamField>

<ParamField body="active" type="boolean">
  Whether or not you want the spending limit to be active on Marqeta.

  Allowable values: `true`, `false`
</ParamField>

<ParamField body="currencyCode" type="string">
  The currency that you want to set the spending limit on. Spending limits only apply to all currencies on the card when they are set in the base currency of the card.

  Allowable values: A valid `currencyCode`
</ParamField>

<ParamField body="limitTurnedOff" type="boolean">
  Whether or not you want the spending limit to be turned off.

  Allowable values: `true`, `false`
</ParamField>

<ParamField body="limitWindow" type="string" required>
  The time period for which the spending limits should apply.

  Allowable values: `DAY`, `WEEK`, `MONTH`, `LIFETIME`
</ParamField>

### Response

If your request is successful, you'll receive a `200` response. The `available` object will contain details about the remaining uses, amount, and number of days remaining until the limit resets.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "id": "775596ae-2624-40af-a9dc-9756110a4a03",
    "amount": 100.5,
    "active": false,
    "limitTurnedOff": true,
    "limitWindow": "DAY",
    "currencyCode": "GBP",
    "available": {
      "uses": 0,
      "amount": 100.5,
      "daysRemaining": 1
    }
  }
  ```

  ```json Response structure theme={null}
  {
    "id": "string",
    "amount": number,
    "active": boolean,
    "limitTurnedOff": boolean,
    "limitWindow": "string",
    "currencyCode": "string",
    "available": {
      "uses": number,
      "amount": number,
      "daysRemaining": number
    }
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see the API reference](/api-reference/spending-limits/create-spending-limit-for-a-card).

## Retrieve a spending limit

<Note>
  **GET** `/v2/cards/{cardId}/spending-limits`
</Note>

### Request

Use this request to retrieve the spending limit for a given card, based on its `id`.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/cards/e9293471-5eb3-4dbc-916c-dbaf9e2deefd/spending-limits?accountId=F12345&budgetId=775596ae-2624-40af-a9dc-9756110a4a03' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```

  ```bash Request format theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/cards/{cardId}/spending-limits?accountId={accountId}&budgetId={budgetId}' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```
</CodeGroup>

#### Path parameters

<ParamField body="cardId" type="string (uuid)" required>
  The ID of the card that you want to retrieve a spending limit for.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that the card is associated with.

  Allowable values: An existing `accountId`
</ParamField>

<ParamField body="budgetId" type="string (uuid)" required>
  The ID of the budget that the card is associated with.

  Allowable values: An existing `budgetId` (≤ 36 characters)
</ParamField>

<ParamField body="limit" type="integer">
  The maximum number of results to return. For example, `limit=25`. By default, this is set to `100`.

  Allowable values: `[ 1 .. 1000 ]`
</ParamField>

<ParamField body="offset" type="integer">
  The number of items to skip before returning results. For example, `offset=200`. By default, this is set to `0`.

  Allowable values: A valid integer
</ParamField>

<ParamField body="search" type="string">
  The term(s) to search for. You can use this to filter the results.

  Allowable values: A valid string
</ParamField>

<ParamField body="personId" type="string (uuid)">
  The ID of the person that the card belongs to.

  Allowable values: A existing `personId` (≤ 36 characters)
</ParamField>

### Response

If your request is successful, you'll receive a `200` response.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "id": "775596ae-2624-40af-a9dc-9756110a4a03",
    "amount": 100.5,
    "active": false,
    "limitTurnedOff": true,
    "limitWindow": "DAY",
    "currencyCode": "GBP",
    "available": {
      "uses": 0,
      "amount": 100.5,
      "daysRemaining": 1
    }
  }
  ```

  ```json Response structure theme={null}
  {
    "id": "string",
    "amount": number,
    "active": boolean,
    "limitTurnedOff": boolean,
    "limitWindow": "string",
    "currencyCode": "string",
    "available": {
      "uses": number,
      "amount": number,
      "daysRemaining": number
    }
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see the API reference](/api-reference/spending-limits/retrieve-spending-limit-for-a-card).

## Update a spending limit

<Note>
  **PUT** `/v2/cards/{cardId}/spending-limits/{limitId}`
</Note>

### Request

Use this request to update an existing spending limit for a card.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X PUT \
    'https://api.equalsmoney.com/v2/cards/e9293471-5eb3-4dbc-916c-dbaf9e2deefd/spending-limits/0684fc07-4abc-46de-b664-da45ef3c4072?accountId=F12345&budgetId=775596ae-2624-40af-a9dc-9756110a4a03' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "id": "775596ae-2624-40af-a9dc-9756110a4a03",
      "amount": 100.5,
      "active": false,
      "limitTurnedOff": true,
      "limitWindow": "DAY"
    }'
  ```

  ```bash Request structure theme={null}
  curl -i -X PUT \
    'https://api.equalsmoney.com/v2/cards/{cardId}/spending-limits/{limitId}?accountId={accountId}&budgetId={budgetId}' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -d '{
      "id": "string",
      "amount": number,
      "active": boolean,
      "limitTurnedOff": boolean,
      "limitWindow": "string"
    }'
  ```
</CodeGroup>

### Path parameters

<ParamField body="cardId" type="string (uuid)" required>
  The ID of the card associated with the spending limit.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

<ParamField body="limitId" type="string" required>
  The ID of the limit that you want to update.

  Allowable values: An existing `limitId` (≤ 36 characters)
</ParamField>

### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that the card is associated with.

  Allowable values: An existing `accountId`
</ParamField>

<ParamField body="budgetId" type="string (uuid)" required>
  The ID of the budget that the card is associated with.

  Allowable values: An existing `budgetId` (≤ 36 characters)
</ParamField>

<ParamField body="personId" type="string (uuid)">
  The ID of the person that the card belongs to.

  Allowable values: An existing `personId` (≤ 36 characters)
</ParamField>

### Request body schema

<ParamField body="id" type="string (uuid)">
  The new ID of the spending limit.

  Allowable values: A valid string
</ParamField>

<ParamField body="amount" type="number" required>
  The amount that you want to set as the spending limit.

  Allowable values: A valid number
</ParamField>

<ParamField body="active" type="boolean" required>
  Whether or not the spending limit is active on Marqeta.

  Allowable values: `true`, `false`
</ParamField>

<ParamField body="limitTurnedOff" type="boolean" required>
  Whether or not the spending limit is turned off.

  Allowable values: `true`, `false`
</ParamField>

### Response

If your request is successful, you'll receive a `200` response.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "id": "775596ae-2624-40af-a9dc-9756110a4a03",
    "amount": 100.5,
    "active": false,
    "limitTurnedOff": true,
    "limitWindow": "DAY",
    "currencyCode": "GBP",
    "available": {
      "uses": 0,
      "amount": 100.5,
      "daysRemaining": 1
    }
  }
  ```

  ```json Response structure theme={null}
  {
    "id": "string",
    "amount": number,
    "active": boolean,
    "limitTurnedOff": boolean,
    "limitWindow": "string",
    "currencyCode": "string",
    "available": {
      "uses": number,
      "amount": number,
      "daysRemaining": number
    }
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see the API reference](/api-reference/spending-limits/update-spending-limit-for-a-card).