Skip to main content
Spending limits are how product and risk teams cap exposure per customer, per segment, or per portfolio without writing code. Common use cases: a daily ceiling on card spending for retail customers, a monthly cap on a specific MCC, a campaign-window limit for a marketing promotion. What changes in your operation: spending caps no longer live as constants hardcoded in config files or scattered across services. They become versioned data with a clear lifecycle (DRAFT → ACTIVE → INACTIVE). Each new period starts counting from zero, and they’re audit-trailed every time a transaction would have pushed past one. Trade-off to be honest about: counters need to stay consistent across replicas and races. Tracer handles that transactionally. If Tracer denies a transaction or sends it to REVIEW, the counter rolls back. You give up “local clever logic in each service” and gain a single, consistent number.
Who is this guide for? Product managers configuring caps, risk teams reviewing exposure, compliance auditing what Tracer denied, and developers integrating the validation call. The Limit types section assumes no API knowledge. The lifecycle and PATCH sections assume basic REST.
Spending limits in Tracer let you control transaction amounts by scope (account, portfolio, segment) and period (daily, weekly, monthly, custom, or per-transaction). Tracer evaluates limits in real-time alongside rules, in the same POST /v1/validations call.

​
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: Every decision reports how much of each cap it consumed
  • Period counting: Daily, weekly, and monthly limits start a new count at each period boundary
  • Time windows: Restrict limit enforcement to specific hours of the day
  • Custom periods: Define date-bound limits for campaigns, promotions, or compliance requirements
By the end of this guide, you will:
  • Understand limit types, time windows, and scoping options
  • Create and configure spending limits with period-based controls
  • Monitor limit usage in real-time
  • Manage the limit lifecycle

​
Core concepts

Understand the building blocks of spending limits.

​
Limit types

Tracer supports five types of spending limits:

​
Time windows

Time windows restrict when Tracer enforces a limit during the day. When a transaction occurs outside the configured time window, Tracer skips the limit and does not enforce it. The transaction proceeds without counting against that limit.
  • Format: HH:MM (24-hour, UTC)
  • Both fields required: If you set activeTimeStart, you must also set activeTimeEnd (and vice versa)
  • Half-open interval: Start is inclusive, end is exclusive [start, end)
  • Overnight windows supported: Setting activeTimeStart: "20:00" and activeTimeEnd: "06:00" creates a window from 8 PM to 6 AM UTC
You can apply time windows to any limit type (DAILY, WEEKLY, MONTHLY, CUSTOM, or PER_TRANSACTION). Without a time window, the limit is active 24/7.
Example: Pix compliance A financial institution needs to enforce lower Pix transfer limits during nighttime hours (as recommended by BACEN):
  • limitType: DAILY
  • maxAmount: "1000.00"
  • activeTimeStart: "20:00"
  • activeTimeEnd: "06:00"
  • Scope: Pix transactions
Tracer checks transactions between 20:00 and 06:00 UTC against the R$ 1,000 limit. This limit does not affect transactions outside this window.

​
Custom periods

Custom periods define a date range during which a limit is active. This is useful for campaigns, promotions, seasonal events, or compliance requirements with specific date boundaries.
  • Required fields: customStartDate and customEndDate (only for CUSTOM type)
  • Half-open interval: Start is inclusive, end is exclusive [start, end)
  • Maximum duration: 5 years
  • Cannot be in the past: The customEndDate must not be entirely before the current date
The customStartDate and customEndDate fields are required for CUSTOM limits and forbidden for other limit types.
Example: Black Friday campaign A retailer wants to set a special spending limit for the Black Friday period:
  • limitType: CUSTOM
  • maxAmount: "100000.00"
  • customStartDate: "2026-11-25T00:00:00Z"
  • customEndDate: "2026-11-30T00:00:00Z"
  • Scope: CARD transactions in the retail segment
Usage accumulates across the whole window in a single count. From customEndDate onward, Tracer stops checking the limit.

​
Combining time windows and custom periods

You can use time windows and custom periods together on CUSTOM limits. Tracer then checks a transaction against the limit only when it falls within both the custom period and the time window. For example, take a CUSTOM limit with customStartDate Nov 25 to customEndDate Nov 30 and a time window of 09:00 to 18:00. Tracer enforces that limit only during business hours within the Black Friday period.

​
Scopes

Scopes define which transactions a limit applies to. Unlike rules, every limit must have at least one scope object. Limits cannot be global. Within a single scope object, the supported fields are:
  • 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)
  • subType - Apply to a specific transaction subtype (e.g., debit, credit)
Matching semantics:
  • Within one scope object: fields combine with AND. A field you leave out works as a wildcard (matches any value). You must set at least one field. Tracer rejects empty scope objects ({}) with error code 0009.
  • Across multiple scope objects on the same limit: they combine with OR. The limit applies if any scope object matches the transaction.
No hierarchy between limits. A transaction can match multiple limits, for example an account-level and a segment-level limit. Tracer then checks all applicable limits independently in a single transaction. Tracer denies the transaction as soon as it exceeds any one of them.

​
Usage tracking

For DAILY, WEEKLY, MONTHLY, and CUSTOM limits, Tracer keeps one usage counter per limit, per matched scope, per period. The validation decision reports that counter. See Read consumption. Tracer keeps a counter for 90 days after its period ends, then a background worker deletes it.

​
How limits work

Tracer evaluates limits during every validation request.

​
Limit check flow

When Tracer validates a transaction, it checks all applicable limits:
How Tracer checks all applicable spending limits during a validation request and updates their usage counters

Figure 1. How spending limits work

  1. Find limits - Query all active limits matching the transaction scope
  2. Check time window - If the limit has a time window configured, verify the current server time falls within activeTimeStart/activeTimeEnd. If outside, Tracer skips the limit (it does not use the client-supplied transactionTimestamp here)
  3. Check custom period - If the limit is CUSTOM, verify the current server time falls within customStartDate/customEndDate. If outside, Tracer skips the limit (again, it does not use transactionTimestamp)
  4. Calculate projected usage - Add transaction amount to current usage
  5. Compare threshold - Check if projected usage exceeds limit amount
  6. Return result - If the transaction exceeds any applicable limit, or any DENY rule matches, Tracer returns a DENY decision (your system should then block the transaction)
Limit checks and counter increments are transactional. If Tracer denies a transaction (by limits or rules) or flags it for review, it rolls back all counter increments atomically. This prevents limit leakage from partial operations.
When a limit is skipped during evaluation, limitUsageDetails[i] includes skipped: true and a skipReason field with one of two values:
  • "outside_time_window": current server time is outside the limit’s activeTimeStart/activeTimeEnd window
  • "outside_custom_period": current server time is outside the limit’s customStartDate/customEndDate range
Tracer reports skipped limits for transparency, but they do not participate in the DENY decision, and their counters do not increment. The window check uses server time, not the client-supplied transactionTimestamp, to prevent timestamp-manipulation attacks.
Why server time instead of transactionTimestamp. The client can set transactionTimestamp to whatever they want. That includes a value crafted to fall inside an active window when the real transaction would fall outside it. If Tracer trusted the client clock for time-window enforcement, anyone with access to the payload could bypass off-hours limits. Pinning the window check to Tracer’s own clock removes that attack surface. The downside is that small clock drift between Tracer pods can cause edge-case skips around the window boundary. In practice, Tracer’s NTP-synced clocks keep this in single-digit milliseconds.

​
Example scenario

A corporate segment has a daily limit of R$ 50,000 ("50000.00") for CARD transactions. If current usage is R45,000andanewtransactionofR 45,000 and a new transaction of R 8,000 arrives:
  • Projected usage: R45,000+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. Tracer creates limits in DRAFT status by default. A limit requires:
  • name: A descriptive name (e.g., “Daily Corporate Card Limit”)
  • limitType: DAILY, WEEKLY, MONTHLY, CUSTOM, or PER_TRANSACTION
  • maxAmount: Maximum amount as a decimal value (e.g., "50000.00")
  • asset: ISO 4217 asset code (e.g., BRL, USD)
  • scopes: At least one scope to define which transactions it applies to
Optional fields:
  • activeTimeStart: Start of the daily time window in HH:MM format (e.g., "09:00")
  • activeTimeEnd: End of the daily time window in HH:MM format (e.g., "17:00")
  • customStartDate: Start date for CUSTOM limits (ISO 8601 timestamp, required for CUSTOM)
  • customEndDate: End date for CUSTOM limits (ISO 8601 timestamp, required for CUSTOM)
Limit names must be globally unique across all non-deleted limits, unlike rule names, which are unique only within their scope context. Tracer enforces uniqueness on the name exactly as stored, after it trims leading and trailing whitespace. The comparison is case-sensitive and does not collapse whitespace inside the name, so Daily Card Limit and daily card limit are two distinct, both-acceptable limits. Deleting a limit frees its name for reuse. A collision returns 409 Conflict with error code 0442.
For complete payload structure and field details, see the API reference.

​
List and query limits

Query limits for management and auditing using GET /v1/limits.

​
Query parameters

​
Get a specific limit

Use GET /v1/limits/{id} to retrieve the full limit definition including scopes and current status.

​
Read consumption

​
From the decision

Every POST /v1/validations response carries limitUsageDetails, with one entry per limit Tracer checked. Each entry reports:
  • limitId and limitAmount: which cap Tracer checked, and its ceiling
  • currentUsage: the projected consumption of that cap’s current period and matched scope if Tracer allows this transaction
  • attemptedAmount: the amount checked against the cap
  • exceeded: whether the attempted amount would push this cap past its ceiling. Tracer evaluates every cap, so more than one entry can carry exceeded: true, and any of them produces the DENY

​
From the limit

GET /v1/limits/{id}/usage reports a cumulative total. Its currentUsage adds up the usage counters recorded for the limit, across periods and scopes. Use it to review a limit’s overall consumption rather than to answer how much a customer has left in the current period. Tracer deletes a counter 90 days after its period ends (see Usage tracking). On a long-running limit, this total covers only the periods still retained, not the limit’s full lifetime.

​
Update a limit

Update limits using PATCH /v1/limits/{id}. The limitType and asset fields are immutable. You cannot change them after creation.
Changing the limit amount does not clear the current count. If you reduce a limit below what the current period already consumed, Tracer denies subsequent transactions until the next period starts.

​
Limit lifecycle

Limits follow the same lifecycle as rules:
Lifecycle of rules and limits in Tracer, showing the status transitions a definition moves through from creation to active enforcement

Figure 2. Spending limits lifecycle

​
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

​
Time window design

  • Use for regulatory compliance - BACEN nighttime Pix limits are a common use case
  • Consider timezone impact - Time windows use UTC. Account for your users’ local timezone offset
  • Combine with custom periods - Use time windows inside custom periods for precise campaign controls

​
Monitoring

  • Read the decision payload - limitUsageDetails shows how much of each cap every transaction consumed
  • Review denied transactions - High denial rates may indicate limits are too restrictive
  • Adjust seasonally - Consider temporary limit increases during high-spending periods or use CUSTOM limits for specific date ranges
Common pitfalls when working with limits:
  • “My customer is reporting overspend. They should have hit the limit.” Check whether the limit is ACTIVE. Tracer does not evaluate a limit in DRAFT or INACTIVE state. Also confirm the limit’s scope actually matches the transaction (segment, transaction type, etc.).
  • “My PATCH lowered the limit but transactions are still denied.” Lowering the limit does not clear the count. If the current period already consumed more than the new ceiling, Tracer denies subsequent transactions until the next period starts.
  • “I tried to delete an ACTIVE limit and it was rejected.” The deletion comes back 422 with code 0363. Send POST /v1/limits/{id}/deactivate first, then DELETE /v1/limits/{id}. This is intentional: it prevents accidentally removing a live enforcement.
  • “GET /v1/limits/{id}/usage reports more than the customer spent this period.” That endpoint totals the usage counters recorded for the limit, across periods and scopes. For the current period, read limitUsageDetails on the validation response.

​
Quick reference

Key endpoints and configuration options.

​
Endpoints

For limit type definitions (DAILY, WEEKLY, MONTHLY, CUSTOM, PER_TRANSACTION), see Limit types earlier in this guide. The same guide covers the optional time-window and custom-period fields and the full scope-field list. The API reference has schema-level details.