Setting up a spending limit

Cap what an account, a portfolio, or a segment can spend in a period with Tracer, activate the cap, and read how much of it is left from the validation decision.

A product or risk decision has landed as a sentence: “no more than R$ 20,000 per account per month.” This guide turns that sentence into a live cap, and shows where to read how much of it a customer has left.

What changes in your operation: the ceiling is no longer a constant compiled into a service. It becomes a stored definition you create, activate, raise, and stop, and every decision that touches it reports what it consumed.

Who is this guide for? Product and risk teams setting the ceiling, and developers wiring POST /v1/validations into the payment path. Steps 1 and 2 are decisions to make before any call. Steps 3 to 6 are the calls.

Before you start

---

• Tracer running and reachable, with an API key. See Getting started
• The id of the account, portfolio, or segment the cap applies to
• The asset code for the transactions you want capped
• Familiarity with limit types, time windows, and custom periods. See Spending limits

All calls below send the API key as X-API-Key and run against http://localhost:4020.

---

Step 1: Decide what the cap is addressed to

---

A limit carries a list of scope objects, and each object names what the limit applies to. These fields are available inside one object:

Field	Applies the limit to
accountId	Transactions on one account
portfolioId	Transactions on one portfolio
segmentId	Transactions on one segment
merchantId	Transactions to one merchant
transactionType	One of CARD, WIRE, PIX, CRYPTO
subType	One transaction subtype, such as purchase — matched without regard to case

Fields inside one object combine with AND. A field you leave out is a wildcard. Across objects the list combines with OR, so a limit with two objects applies when either one matches.

The choice that decides the answer to “R$ 20,000 per account” is which id you name:

One account, its own budget

"scopes": [
  { "accountId": "550e8400-e29b-41d4-a716-446655440100" }
]

The cap applies to that account. It counts that account’s spending and no one else’s. For a per-account ceiling across a book of customers, each account gets its own limit.

One segment, one shared budget

"scopes": [
  { "segmentId": "2f1c9b7e-40a5-4d18-9c6b-3e7f5a0d1b24" }
]

The cap applies to the segment as a whole. Every account in that segment draws down the same R$ 20,000 (the first customers to spend consume it for the rest).

Narrowed to one rail

"scopes": [
  {
    "accountId": "550e8400-e29b-41d4-a716-446655440100",
    "transactionType": "PIX"
  }
]

The cap counts only that account’s Pix transactions. Its card and wire traffic passes without touching this limit.

A limit also carries an asset, and Tracer checks a limit against a transaction only when the two match. Tracer does not check a limit created in BRL against a USD transaction. A book that settles in two currencies needs a limit for each.

A limit must carry at least one scope object, and each object must set at least one field. Tracer rejects an empty list or an empty object. See What goes wrong.

---

Step 2: Choose the period

---

limitType decides both the size of the ceiling’s window and when a new count starts. Tracer offers five:

limitType	The count covers	A new count starts
DAILY	One calendar day, UTC	Each day at 00:00 UTC
WEEKLY	One ISO week, UTC	Each Monday at 00:00 UTC
MONTHLY	One calendar month, UTC	On the 1st at 00:00 UTC
CUSTOM	A date range you set	Not at all — one count spans the whole range
PER_TRANSACTION	A single transaction	No count is kept; each transaction is measured on its own

“per month” is MONTHLY.

The boundary is UTC, not local time. A São Paulo customer spending at 21:30 on 31 July is at 00:30 UTC on 1 August. That amount lands in the August count, not July’s. When a cap uses local terms, expect the last hours of the local month to belong to the next one.

CUSTOM takes customStartDate and customEndDate and is the shape for a campaign or a promotion. Those two fields belong to CUSTOM. Tracer rejects them on the other four types. To restrict a cap to certain hours of the day instead, see time windows.

---

Step 3: Create the limit

---

POST /v1/limits stores the definition. Tracer creates it in DRAFT and does not check it against transactions yet.

curl -X POST http://localhost:4020/v1/limits \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Account Spending Cap",
    "description": "Caps total monthly outflow for one account",
    "limitType": "MONTHLY",
    "maxAmount": "20000.00",
    "asset": "BRL",
    "scopes": [
      { "accountId": "550e8400-e29b-41d4-a716-446655440100" }
    ]
  }'

A successful call answers 201. The body carries the stored limit. Two fields matter now:

Field	What to do with it
limitId	The id every later call in this guide takes. Keep it
status	DRAFT — the limit is not being checked yet. Step 4 changes that

Names are unique across limits, and the character set is narrow. name accepts ASCII letters and digits, spaces, and -, _, ., (, ). Tracer rejects an accent, or a dash typed as an em dash, with 0371. Tracer rejects a name another live limit already holds, with 0442. Deleting a limit frees its name again.

For the full payload and every optional field, see Create a limit.

---

Step 4: Activate it

---

Tracer does not check a DRAFT limit. Activation is what puts it in the path:

curl -X POST http://localhost:4020/v1/limits/{limitId}/activate \
  -H "X-API-Key: your-secure-api-key"

The response carries the limit with status set to ACTIVE. From here, Tracer checks every POST /v1/validations whose transaction matches the scope and asset against this limit.

Activating mid-month does not import the month’s history. Tracer counts a transaction against a limit at the moment it decides on it. Spending that happened while the limit was DRAFT is not in the count. A cap activated on the 20th governs what happens from the 20th onward.

See Activate a limit.

---

Step 5: Read how much is left

---

Every POST /v1/validations response carries limitUsageDetails, with one entry per limit Tracer checked:

{
  "limitId": "b2d4f6a8-1c3e-4507-9b8d-6f0a2c4e6810",
  "limitAmount": "20000",
  "scope": "(account:550e8400-e29b-41d4-a716-446655440100)",
  "period": "MONTHLY",
  "currentUsage": "20000",
  "attemptedAmount": "1500",
  "exceeded": false
}

Field	What it reports
limitAmount	The ceiling that was checked
currentUsage	Projected consumption of that limit’s current period and matched scope if this transaction is allowed
attemptedAmount	The amount measured against the ceiling
period	The limit’s type — MONTHLY here
scope	The limit’s scope as text, each object in parentheses, several objects joined by OR
exceeded	Whether the amount would push this cap past its ceiling

In the entry above, a R$ 1,500 purchase took an 18,500 month to exactly 20,000 and spent the cap. Tracer denies the next transaction on that account until August.

When a transaction exceeds a limit, the decision is DENY and reason is limit_exceeded. Tracer does not add to the count the amount that would have crossed the ceiling. A limit produces a denial, not a flag for review. To go from such a denial back to the limit that caused it, see Reviewing a denied transaction.

The other reading

GET /v1/limits/{limitId}/usage answers with a total for the limit rather than for one period. It adds up the usage counters recorded against it, across the periods and scopes it has accumulated. Use it to review how much a limit has absorbed overall, not to answer how much a customer has left this month.

Tracer deletes a counter 90 days after its period ends. On a long-running limit, this total covers only the periods still retained, not the limit’s full lifetime. See Usage tracking.

See Retrieve a limit usage snapshot.

---

Step 6: Change it, pause it, remove it

---

1. Raise or lower the ceiling

   curl -X PATCH http://localhost:4020/v1/limits/{limitId} \
     -H "X-API-Key: your-secure-api-key" \
     -H "Content-Type: application/json" \
     -d '{ "maxAmount": "30000.00" }'
   

   name, description, maxAmount, and scopes are editable, and so are the time-window and custom-period fields. limitType and asset are not. Tracer rejects a request that sends either with 0380, and a different period or asset means a new limit. Tracer rejects an empty body with 0183. See Update a limit.

   Changing the ceiling does not clear the running count. Lower it below what the current period already consumed, and Tracer denies the account until the next period starts.

2. Stop enforcing it

   curl -X POST http://localhost:4020/v1/limits/{limitId}/deactivate \
     -H "X-API-Key: your-secure-api-key"
   

   The limit moves to INACTIVE and Tracer stops checking it. It keeps its definition and its place in the , and POST /v1/limits/{limitId}/activate puts it back in the path. See Deactivate a limit.

3. Take it back to draft

   curl -X POST http://localhost:4020/v1/limits/{limitId}/draft \
     -H "X-API-Key: your-secure-api-key"
   

   Moves an INACTIVE limit back to DRAFT. See Return a limit to draft.

4. Remove it

   curl -X DELETE http://localhost:4020/v1/limits/{limitId} \
     -H "X-API-Key: your-secure-api-key"
   

   Answers 204. You have to deactivate a limit that is currently ACTIVE first. Tracer rejects the deletion with 0363, which is what keeps a live ceiling from disappearing by accident. See Delete a limit.

Find the limits you already have

GET /v1/limits lists them, and filters by the same scope fields you set in Step 1:

GET /v1/limits?status=ACTIVE&account_id=550e8400-e29b-41d4-a716-446655440100&limit_type=MONTHLY
X-API-Key: {api_key}

name, status, limit_type, account_id, segment_id, portfolio_id, merchant_id, transaction_type, and sub_type all filter. Results are cursor-paginated. See List limits, and Retrieve a limit for one by id.

---

What goes wrong

---

What usually goes wrong when you set up a cap:

• “The customer overspent and nothing stopped them.” Check status first. Tracer does not check a limit in DRAFT or INACTIVE. Then check that the limit’s asset matches the transaction’s, and that the scope names the id the transaction actually carried.
• “The segment cap ran out on day two.” A segment-scoped limit is one budget for the whole segment, not one per account in it. A per-account ceiling means a limit addressed to each account.
• “The month rolled over a few hours early.” Period boundaries are UTC. Spending after 21:00 in UTC-3 belongs to the next UTC day, and on the last day of the month, to the next month.
• “I raised the limit and the account is still denied.” Raising the ceiling does not clear the count. Confirm the new maxAmount is above what the period already consumed.
• “GET /v1/limits/{id}/usage reports more than the customer spent this month.” That endpoint totals the counters recorded for the limit, across periods and scopes. For the current period, read limitUsageDetails on the validation response.

Error codes

Code	Status	What to change
0009	400	A field failed validation — detail names it, for example scopes must have at least 1 item(s), scope at index 0 must have at least one field set, or maxAmount must be greater than 0
0065	400	The id in the path is not a UUID
0183	400	The PATCH body carried no editable field
0362	404	No limit has that id
0363	422	The transition is not allowed — deleting an ACTIVE limit, for instance
0366	400	asset is three uppercase letters but not an ISO 4217 code
0371	400	name carries a character the field does not accept
0380	422	The request tried to change limitType or asset
0442	409	Another live limit already holds that name

The complete list is in the Tracer error list.

---

Quick reference

---

Step	Method	Endpoint
Create a limit	POST	/v1/limits
Activate it	POST	/v1/limits/{id}/activate
Read consumption with the decision	POST	/v1/validations
Read the limit’s cumulative total	GET	/v1/limits/{id}/usage
Change the ceiling	PATCH	/v1/limits/{id}
Stop enforcing it	POST	/v1/limits/{id}/deactivate
Take it back to draft	POST	/v1/limits/{id}/draft
Remove it	DELETE	/v1/limits/{id}
Find limits	GET	/v1/limits · /v1/limits/{id}