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

# Spend Controls

> Spend controls provide a way to monitor the flow of money.

## Overview

In Synctera’s platform, **spend controls are independent entities** that must be associated with another entity (currently, an **account**) to take effect.

A spend control defines:

* **What to monitor** – time window, payment types (for example, CARD, ACH, WIRE, CASH), merchant category codes (MCCs), direction (DEBITS or CREDITS).
* **How much** – amount\_limit over that window.
* **What to do if violated** – decline the transaction (where possible) and/or create a **Case** in Synctera’s case management system.
* **Webhooks** sent to the nominated FinTech endpoint will be sent each time

Key characteristics:

* **Many-to-many** – a spend control can apply to multiple accounts, and an account can have multiple spend controls.
* **Direction-specific** – each spend control applies to either **DEBITS** or **CREDITS**; debits and credits do not offset each other for spend-control purposes.
* **Rail-agnostic** – payment types cover card, ACH, wires, cash, and other movement rails; spend controls can be used for **debit**, **credit**, and **Synctera Pay / external card** flows via the appropriate payment types.

Spending Controls can apply to customers, accounts, and cards. This includes both **deposit accounts** (CHECKING/SAVING/PREPAID) and **credit accounts** (for example, LINE\_OF\_CREDIT, CHARGE\_SECURED, CHARGE\_UNSECURED, REVOLVING credit accounts).

## Managing Spend Controls

You manage spend controls with the Spend Controls API:

* **Create** – POST /v2/spend\_controls
* **Get** – GET /v2/spend\_controls/{id}
* **Update** – PATCH /v2/spend\_controls/{id}
* **List** – GET /v2/spend\_controls

See the [**Spend Controls API reference**](/reference/createspendcontrol) for full request and response schemas.

### Creating a Spend Control

To create a spend control, use [POST /v2/spend\_controls](/v2/reference/createspendcontrol).

For example, to create a limit of \$1,000.00 in card spending over the last seven days:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "name": "One thousand dollars weekly card limit",
    "amount_limit": 100000,
    "time_range": {
      "time_range_type": "ROLLING_WINDOW_DAYS",
      "days": 7
    },
    "payment_types": [
      "CARD"
    ],
    "action_decline": true,
    "action_case": false,
    "is_active": true
  }
  ```
</CodeGroup>

The `amount_limit` uses the smallest currency unit (eg. cents).

The `time_range` field can be a rolling window defined by a number of days, as in the example above, or defined as a single transaction. For example, to create a limit of \$1,000.00 per card transaction:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "name": "One thousand dollars per transaction limit",
    "amount_limit": 100000,
    "time_range": {
      "time_range_type": "SINGLE_TRANSACTION",
    },
    "payment_types": [
      "CARD"
    ],
    "action_decline": true,
    "action_case": false,
    "is_active": true
  }
  ```
</CodeGroup>

The `action_decline` and `action_case` fields specify what will happen for a transaction that would exceed the spend control's limit. If `action_case` is set then a case will be created in Synctera's case management system for any transaction that would exceed the spend control's limit. If `action_decline` is set then the transaction will be declined if possible. Some transactions are forced, because they represent money movement that has already occurred outside of Synctera's platform. In such cases, if the transaction were to exceed the spend control's limit the transaction will not be declined but instead a case will be created, regardless of the `action_case` setting. At least one of `action_decline` and `action_case` must be set. To completely disable the spend control set `is_active` to false.

You may omit the `payment_types` field. In that case, the spend control applies to all payment types.

You may specify multiple payment types. This means that all the specified payment types count toward the limit. For example, to create a rule that creates a case if there is more than \$25,000.00 in combined ACH and wire spending over the last thirty days:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "name": "25 thousand ACH and wire",
    "amount_limit": 2500000,
    "time_range": {
      "time_range_type": "ROLLING_WINDOW_DAYS",
      "days": 30
    },
    "payment_types": [
      "ACH",
      "WIRE"
    ],
    "action_decline": false,
    "action_case": true,
    "is_active": true
  }
  ```
</CodeGroup>

In this example the spending is counted for the entire rule. So if there were \$15,000.00 of ACH and \$15,000.00 of wire spending then the rule would take effect and a case would be created. The \$25,000.00 limit is for ACH and wire spending combined. If you want the payment types to be counted separately, create separate spend controls, one for each payment type.

You may specify the `direction` of money movement to which the spend control applies. The options are `DEBITS` or `CREDITS`. For example, to create a rule that triggers a case if an account receives more than \$10,000.00 in cash deposits in the last seven days:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "name": "seven day cash warning",
    "amount_limit": 1000000,
    "time_range": {
      "time_range_type": "ROLLING_WINDOW_DAYS",
      "days": 7
    },
    "payment_types": [
      "CASH"
    ],
    "action_decline": false,
    "action_case": true,
    "is_active": true,
    "direction": "CREDITS"
  }
  ```
</CodeGroup>

You may specify `merchant_category_codes` to which the spend control applies. Specifying merchant category codes only works with card transactions. The options for `merchant_category_codes` include individual codes or ranges of codes. For example, to create a weekly limit of \$1,000.00 with merchant category code `6012` or in the range of merchant category codes `7300–7999`:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "name": "One thousand dollars weekly card limit for MCCs 6012, 7300–7999",
    "amount_limit": 100000,
    "time_range": {
      "time_range_type": "ROLLING_WINDOW_DAYS",
      "days": 7
    },
    "payment_types": [
      "CARD"
    ],
    "action_decline": true,
    "action_case": false,
    "is_active": true,
    "merchant_category_codes": [
      "6012",
      "7300–7999"
    ]
  }
  ```
</CodeGroup>

In this example, the spending is counted for the entire rule. So if there were \$750.00 of spending with Merchant Category Code 6012 and subsequently \$750.00 of spending with Merchant Category Code 7375, the rule would take effect. If you want the `merchant_category_codes` to be counted separately, create separate spend controls for each merchant category code or range of merchant category codes.

### Spend Control Response

The API responses from the spend control endpoints include the details of the spend control, including the UUID in the `id` field and the number of accounts that are using the spend control in the `number_of_related_accounts` field (which will be zero for newly-created spend controls). To check the status of a specific spend control by its UUID, use [GET /v2/spend\_controls/{id}](/v2/reference/getspendcontrol):

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
    "name": "One thousand dollars weekly card limit",
    "amount_limit": 100000,
    "time_range": {
      "time_range_type": "ROLLING_WINDOW_DAYS",
      "days": 7
    },
    "payment_types": [
      "CARD"
    ],
    "action_decline": true,
    "action_case": false,
    "is_active": true,
    "creation_time": "2022-03-24T12:59:06.756Z",
    "last_modified_time": "2022-03-24T12:59:06.756Z",
    "number_of_related_accounts": 0,
    "direction": "DEBITS",
    "merchant_category_codes": [
      "6012",
      "7300–7999"
    ]
  }
  ```
</CodeGroup>

### Updating a Spend Control

To update a spend control, use [PATCH /v2/spend\_controls/{id}](/v2/reference/updatespendcontrol).

This request will disable a spend control:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "is_active": false
  }
  ```
</CodeGroup>

This request will set a new time range and amount limit:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "amount_limit": 75000,
    "time_range": {
      "time_range_type": "ROLLING_WINDOW_DAYS",
      "days": 14
    }
  }
  ```
</CodeGroup>

### List Spend Controls

To list spend controls, use [GET /v2/send\_controls](/v2/reference/listspendcontrols). Using query parameters. you can filter by limit amount (range), payment type, number of related accounts (range), specific related account ID and name.

### List Accounts that use a Spend Control

To list all accounts that use a spend control, use [GET /v2/accounts](/v2/reference/listaccounts) and include the spend control ID in the `spend_control_ids` query parameter.

## Link Spend Controls to Accounts

### Create an Account with Spend Controls

To create an account with a spend control, use [POST /v2/accounts](/v2/reference/createaccount) with the optional field `spend_controls_ids`. For example:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "account_template_id": "e14182d8-130c-4fa4-bcac-9b3df1537247",
    "relationships": [
      {
        "person_id": "23ec211e-7c3e-4ead-b340-c5cab70257a2",
        "relationship_type": "ACCOUNT_HOLDER"
      }
    ],
    "spend_control_ids": [
      "b9c7da4e-8220-4044-86a0-f91a592002a5"
    ]
  }
  ```
</CodeGroup>

You may specify as many as ten `spend_control_ids`. Each spend control applies to the account independent of the other spend controls on the account and independent of other accounts that may use the same spend controls.

### Update an Account's Spend Controls

To change the spend controls for an account, use [PATCH /v2/accounts/{id}](/v2/reference/patchaccount). For example, to have the account use two spend controls:

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "spend_control_ids": [
      "ad7495c3-82d0-482d-b1e4-f0cbab6e039c",
      "41d6ab10-73b3-4b82-9e75-a4981b35edfb"
    ]
  }
  ```
</CodeGroup>

<Warning>
  When updating the list of `spend_control_ids` for an account, the entire list is replaced. The list is not appended. Old values are dropped. So if you want to add a new spend controls to an account with existing spend controls make sure your update request includes both the old spend controls and the new ones.
</Warning>

To remove spend controls from an account use an explicitly-empty JSON array.

<CodeGroup>
  ```json JSON theme={"system"}
  {
    "spend_control_ids": []
  }
  ```
</CodeGroup>

### Using Account Templates

[Account templates](/v2/docs/create-accounts-guide#account-templates) may contain spend control IDs. As with other account template fields, these spend control IDs will be the default for any account created using the template but during account creation you can over-ride the template's default.

<Warning>
  If you create an account from a template which contains a list of `spend_control_ids` and specify your own list of `spend_control_ids` then the two lists are not combined. The list will be whatever you specify in the account creation request.
</Warning>

## Spend Monitoring Cases

When spend controls are violated they may create a case in Synctera's case system. If the spend control has `action_case` set, or if the spend control has `action_decline` set and the transaction is forced, then there will be a case based on that specific account and spend control. Multiple accounts using the same spend control will have separate cases if multiple accounts violate the spend control. Multiple spend controls on the same account will have separate cases if multiple of the spend controls are violated.

Multiple violations of a specific spend control for a specific account will combine into the same case as long as the case remains open. Any additional violations will be reflected in violation count of the case. If the case is closed and the account violates the spend control again then a new case will be created.