Spending limits

Spending limits in Tracer allow you to control transaction amounts by scope (account, portfolio, segment) and period (daily, monthly, per-transaction). Limits are evaluated in real-time alongside rules, providing comprehensive transaction governance.

Why use spending limits

Benefit	Description
Customer protection	Detect overspending and return DENY decisions for unauthorized large transactions
Risk management	Monitor exposure per account, segment, or portfolio
Flexible scoping	Apply limits at different granularity levels
Real-time tracking	Monitor usage and remaining amounts instantly
Automatic resets	Daily and monthly limits reset automatically

By the end of this guide, you will:

Understand limit types and scoping options
Create and configure spending limits
Monitor limit usage in real-time
Manage the limit lifecycle

Core concepts

Limit types

Tracer supports three types of spending limits:

Type	Description	Reset behavior
`DAILY`	Maximum amount per day	Resets at midnight UTC
`MONTHLY`	Maximum amount per month	Resets on 1st of month, midnight UTC
`PER_TRANSACTION`	Maximum amount per single transaction	No tracking; each transaction evaluated independently

Scopes

Scopes define which transactions a limit applies to. A limit matches transactions that fit within its scope definition. Scope fields (all optional, at least one required):

segmentId - Apply to transactions from a specific segment
portfolioId - Apply to transactions from a specific portfolio
accountId - Apply to transactions from a specific account
merchantId - Apply to transactions to a specific merchant
transactionType - Apply to specific transaction types (CARD, WIRE, PIX, CRYPTO)

Scope hierarchy: More specific scopes take precedence. For example, an account-level limit is more specific than a segment-level limit.

Usage tracking

For DAILY and MONTHLY limits, Tracer tracks:

Current usage - Total amount consumed in the current period (in smallest currency unit)
Utilization percent - Percentage of limit used
Reset time - When the limit will reset to zero

How limits work

Limit check flow

When a transaction is validated, Tracer checks all applicable limits:

Find limits - Query all active limits matching the transaction scope
Calculate projected usage - Add transaction amount to current usage
Compare threshold - Check if projected usage exceeds limit amount
Return result - If any limit is exceeded, Tracer returns a DENY decision (your system should then block the transaction)

Example scenario

A corporate segment has a daily limit of R$ 50,000 (5,000,000 centavos):

{
  "name": "Daily Corporate Limit",
  "limitType": "DAILY",
  "maxAmount": 5000000,
  "currency": "BRL",
  "scopes": [
    {
      "segmentId": "corporate-segment-uuid",
      "transactionType": "CARD"
    }
  ]
}

If current usage is 4,500,000 (R

45,000) and a new transaction of 800,000 (R

8,000) arrives:

Projected usage: 4,500,000 + 800,000 = 5,300,000 (R$ 53,000)
Limit: 5,000,000 (R$ 50,000)
Result: Tracer returns DENY decision (your system should block the transaction)

All monetary amounts in Tracer are expressed in the smallest currency unit (e.g., centavos for BRL, cents for USD). R$ 50,000.00 = 5,000,000 centavos.

Create a limit

Request

POST /v1/limits
X-API-Key: {api_key}
Content-Type: application/json

{
  "name": "Daily Corporate Limit",
  "limitType": "DAILY",
  "maxAmount": 5000000,
  "currency": "BRL",
  "scopes": [
    {
      "segmentId": "corporate-segment-uuid",
      "transactionType": "CARD"
    }
  ]
}

Response

{
  "limitId": "limit-uuid-123",
  "name": "Daily Corporate Limit",
  "limitType": "DAILY",
  "maxAmount": 5000000,
  "currency": "BRL",
  "scopes": [
    {
      "segmentId": "corporate-segment-uuid",
      "transactionType": "CARD"
    }
  ],
  "status": "DRAFT",
  "resetAt": "2026-01-31T00:00:00Z",
  "createdAt": "2026-01-30T10:00:00Z",
  "updatedAt": "2026-01-30T10:00:00Z"
}

Limit fields

Field	Type	Required	Description
`name`	string	Yes	Descriptive limit name
`limitType`	enum	Yes	DAILY, MONTHLY, or PER_TRANSACTION
`maxAmount`	int64	Yes	Maximum amount in smallest currency unit (e.g., centavos)
`currency`	string	Yes	ISO 4217 currency code (e.g., BRL, USD)
`scopes`	array	Yes	At least one scope required

Query limit usage

Monitor how much of a limit has been consumed in the current period.

Request

GET /v1/limits/{limitId}/usage
X-API-Key: {api_key}

Response

{
  "limitId": "limit-uuid-123",
  "limitAmount": 5000000,
  "currentUsage": 1500000,
  "utilizationPercent": 30.0,
  "nearLimit": false,
  "resetAt": "2026-01-31T00:00:00Z"
}

Usage fields

Field	Description
`limitAmount`	Total limit configured (in smallest currency unit)
`currentUsage`	Amount consumed in current period (in smallest currency unit)
`utilizationPercent`	Percentage of limit used
`nearLimit`	True when usage exceeds 80% of limit
`resetAt`	When the limit resets (DAILY/MONTHLY only)

The nearLimit flag activates at 80% utilization, allowing proactive management before limits are exceeded.

Update a limit

Modify limit configuration. The limitType and currency fields are immutable and cannot be changed after creation.

Request

PATCH /v1/limits/{limitId}
X-API-Key: {api_key}
Content-Type: application/json

{
  "name": "Updated Daily Corporate Limit",
  "maxAmount": 7500000
}

Changing the limit amount does not reset current usage. If you reduce a limit below current usage, subsequent transactions will be denied until the period resets.

Limit lifecycle

Limits follow the same lifecycle as rules:

States

State	Description
`DRAFT`	Limit created but not active; can be modified freely
`ACTIVE`	Limit is checked during validations
`INACTIVE`	Limit is not checked; preserved for audit trail; can be reactivated
`DELETED`	Permanently removed; does not appear in listings

Transitions

Operation	From	To	Description
Create	-	DRAFT	Limits are created in DRAFT status by default
Activate	DRAFT, INACTIVE	ACTIVE	Start checking this limit
Deactivate	ACTIVE	INACTIVE	Stop checking this limit
Delete	DRAFT, INACTIVE	DELETED	Permanently remove (cannot delete ACTIVE limits)

Best practices

Naming

Be descriptive - Include the scope and type in the name
Use consistent patterns - e.g., “Daily Limit”

Less clear	More clear
`Limit 1`	`Daily Corporate Card Limit`
`VIP limit`	`Monthly VIP PIX Limit`

Scope design

Start broad, refine as needed - Begin with segment-level limits, add account-level for exceptions
Avoid overlapping scopes - Multiple limits on the same scope can cause confusion
Use transaction types - Different payment methods may need different limits

Monitoring

Watch nearLimit flags - Proactively contact customers nearing limits
Review denied transactions - High denial rates may indicate limits are too restrictive
Adjust seasonally - Consider temporary limit increases during high-spending periods

Common errors

Limit creation

Code	Message	Resolution
`400`	`Invalid limit configuration`	Check amount is positive and scope is valid
`400`	`At least one scope field required`	Include at least one scope field
`400`	`Invalid currency code`	Use valid ISO 4217 code (BRL, USD, etc.)

Limit usage

Code	Message	Resolution
`404`	`Limit not found`	Verify the limit ID exists

Validation denials

When a transaction is denied due to limit exceeded:

{
  "decision": "DENY",
  "reason": "limit_exceeded",
  "limitUsageDetails": [
    {
      "limitId": "limit-uuid-123",
      "limitAmount": 5000000,
      "currentUsage": 4900000,
      "exceeded": true
    }
  ]
}

Quick reference

Endpoints

Operation	Method	Endpoint
Create limit	POST	`/v1/limits`
List limits	GET	`/v1/limits`
Get limit	GET	`/v1/limits/{limitId}`
Update limit	PATCH	`/v1/limits/{limitId}`
Activate limit	POST	`/v1/limits/{limitId}/activate`
Deactivate limit	POST	`/v1/limits/{limitId}/deactivate`
Delete limit	DELETE	`/v1/limits/{limitId}`
Get usage	GET	`/v1/limits/{limitId}/usage`

Limit types

Type	Reset	Use case
`DAILY`	Midnight UTC	Daily spending caps
`MONTHLY`	1st of month	Monthly budgets
`PER_TRANSACTION`	None	Single transaction limits

Scope fields

Field	Type	Description
`segmentId`	UUID	Filter by segment
`portfolioId`	UUID	Filter by portfolio
`accountId`	UUID	Filter by account
`merchantId`	UUID	Filter by merchant
`transactionType`	enum	CARD, WIRE, PIX, CRYPTO

​Why use spending limits

​Core concepts

​Limit types

​Scopes

​Usage tracking

​How limits work

​Limit check flow

​Example scenario

​Create a limit

​Request

​Response

​Limit fields

​Query limit usage

​Request

​Response

​Usage fields

​Update a limit

​Request

​Limit lifecycle

​States

​Transitions

​Best practices

​Naming

​Scope design

​Monitoring

​Common errors

​Limit creation

​Limit usage

​Validation denials

​Quick reference

​Endpoints

​Limit types

​Scope fields

Why use spending limits

Core concepts

Limit types

Scopes

Usage tracking

How limits work

Limit check flow

Example scenario

Create a limit

Request

Response

Limit fields

Query limit usage

Request

Response

Usage fields

Update a limit

Request

Limit lifecycle

States

Transitions

Best practices

Naming

Scope design

Monitoring

Common errors

Limit creation

Limit usage

Validation denials

Quick reference

Endpoints

Limit types

Scope fields