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

---

• 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

---

Understand the building blocks of spending limits.

​

Limit types

Tracer supports three types of spending limits:

​

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

---

Tracer evaluates limits during every validation request.

​

Limit check flow

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

1. Find limits - Query all active limits matching the transaction scope
2. Calculate projected usage - Add transaction amount to current usage
3. Compare threshold - Check if projected usage exceeds limit amount
4. 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) for CARD transactions. If current usage is R$45,000 and a new transaction of R$ 8,000 arrives:

• Projected usage: R$45,000 + R$ 8,000 = R$ 53,000
• Limit: R$ 50,000
• Result: Tracer returns DENY decision (your system should block the transaction)

​

Create a limit

---

Create limits using POST /v1/limits. Limits are created in DRAFT status by default. A limit requires:

• name: A descriptive name (e.g., “Daily Corporate Card Limit”)
• limitType: DAILY, MONTHLY, or PER_TRANSACTION
• maxAmount: Maximum amount in smallest currency unit
• currency: ISO 4217 currency code (e.g., BRL, USD)
• scopes: At least one scope to define which transactions it applies to

For complete payload structure and field details, see the API reference.

​

Query limit usage

---

Monitor limit consumption using GET /v1/limits/{limitId}/usage. The response includes:

• currentUsage: Amount consumed in current period
• utilizationPercent: Percentage of limit used
• nearLimit: True when usage exceeds 80% (for proactive management)
• resetAt: When the limit resets (DAILY/MONTHLY only)

​

Update a limit

---

Update limits using PATCH /v1/limits/{limitId}. The limitType and currency fields are immutable and cannot be changed after creation.

​

Limit lifecycle

---

Limits follow the same lifecycle as rules:

​

States

​

Transitions

​

Best practices

---

Recommendations for effective limit management.

​

Naming

• Be descriptive - Include the scope and type in the name
• Use consistent patterns - e.g., “Daily 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

​

Reliability and enforcement

---

Spending limits in Tracer are designed for production environments where accuracy and trust are non-negotiable.

​

Atomic evaluation

Limit checks are performed atomically. When a transaction is validated, Tracer reads the current usage and evaluates the limit in a single, indivisible operation. This means that even when multiple transactions arrive simultaneously for the same account or scope, each evaluation reflects the true state of usage at that moment. There is no window in which concurrent transactions can bypass a limit. If two transactions arrive at the same time and only one fits within the remaining budget, exactly one is approved.

​

Server-side timestamps

All usage tracking relies on server-side timestamps generated by Tracer. Clients cannot influence when a transaction is recorded or when a period resets. This eliminates any possibility of timestamp manipulation affecting limit calculations.

​

What this means in practice

• Concurrent safety: High-throughput environments with many simultaneous transactions per account are fully supported. Limits behave correctly under load.
• Accurate tracking: Usage totals always reflect the actual state, even during peak traffic.
• Trustworthy resets: Daily and monthly resets happen based on Tracer’s internal clock, not client-reported times.

​

Quick reference

---

Key endpoints and configuration options.

​

Endpoints

​

Limit types

​

Scope fields