Skip to main content
A lot is an individual credit recorded as its own entry in the ledger, with its own balance, expiration date, and vesting period. Instead of maintaining a single running total, LOT-mode assets track every credit separately. This is useful when points need to expire after a fixed window (e.g., 12 months from issuance), when rewards should vest before becoming spendable (e.g., a referral bonus that unlocks after 30 days), when auth and settlement events need to match by reference_id (the auth/settlement pattern), or when reporting needs to preserve the issuer of redeemed value. Assets configured with SIMPLE mode do not create lots. They track a single balance per bucket. See SIMPLE vs LOT Mode for a comparison.

​
How Lots Work

When a LOT-mode asset is credited, a new lot is created:
When funds are debited, the oldest eligible lot is spent down before the next one is touched. Each lot tracks its remaining balance independently.

​
Lot Lifecycle

A lot moves through a series of statuses from creation to consumption or expiration.

​
Expiration

Set expires_at on a CREDIT action to give lots a deadline. The value can be a positive relative duration, a fixed timestamp, or a ${{ }} expression that resolves to either. To see when outstanding value will expire across a program or asset, for breakage estimation or forecasting, use the expiration schedule report. A relative duration counts from the moment the lot is created, which is when the event is processed, not the event’s event_timestamp:
For live traffic the difference is seconds and does not matter. For backfilled events it does: an event stamped last March but imported today gets a lot that expires 365 days from today. When the expiry must follow the occurrence date, compute it in your backend and send it on the event instead. A fixed timestamp sets the same deadline for all lots created by that rule:
A ${{ }} expression sets a per-event deadline. The expression must resolve to a string in one of the two forms above. This is how you get occurrence-based or calendar-exact expiry: your backend computes the timestamp and sends it in event_data:
Expiration takes effect at expires_at exactly. From that moment the lot is excluded from every operation that consumes or reserves value, so the credits cannot be spent even before the bookkeeping catches up. The bookkeeping follows within a few minutes: a background sweep marks the lot EXPIRED, posts the forfeited value to breakage as an EXPIRATION journal entry, and emits a balance.expired webhook. Until the sweep runs, the balances API still includes the expired value in available, so a balance read in that brief window can show credits that can no longer be spent. The expiration schedule report accounts for the same window: value already past expires_at but not yet swept appears under expiring_before_window, then drops out of the report once forfeited. Durations accept h, d (24 hours), and w (168 hours) units, plus the standard Go units down to seconds and below (m, s, ms). Units can be combined ("1w2d12h") and fractional values are allowed. Months and years are not accepted because their length varies by calendar date. For an approximate policy, use days ("180d" for approximately six months). For an exact calendar policy (“expires on the same day six months later”), compute the date in your backend, include it in event_data, and resolve it through a ${{ }} expression. Use a literal fixed timestamp only when every lot should share the same deadline.
m means minutes, not months. "3m" parses as 3 minutes. For approximately three months, write "90d"; for an exact calendar deadline, pass a caller-computed timestamp through ${{ }}.

​
Vesting

Set matures_at on a CREDIT action to create a vesting period. Lots credited with a future matures_at land in DEFERRED status and automatically transition to AVAILABLE when the date passes. Deferred lots are excluded from debit operations.
Both fields can be combined. This lot vests after 7 days and expires after 90:
DEFERRED cannot be targeted as a bucket for writes. It is read-only and available as a filter in query endpoints (e.g., status=DEFERRED on the lots list, or bucket=DEFERRED on journal entries).

​
Oldest-First Spending

When debiting a LOT-mode asset, Scrip spends the oldest eligible lots first:
Only lots that are mature and not expired are eligible for consumption.

​
Viewing Lots

Inspect a participant’s lots for a specific asset:

​
Lot-Aware Operations

Hold, release, and forfeit operations on LOT-mode assets are lot-aware: Lot bucket transitions (AVAILABLE ↔ HELD) update the lot row in place, preserving the lot UUID across holds, releases, and settles. Partial transitions split the remainder into a new lot. These operations return a lots_processed array showing which lots were affected and by how much:

​
SIMPLE vs LOT Mode

The asset’s inventory_mode determines whether credits are tracked individually or as a running total. Use SIMPLE for balances with no per-credit lifecycle or provenance needs. Use LOT when expiration, vesting, auth/settlement matching, oldest-first spending, issuer attribution, or partner settlement matters.
expires_at and matures_at fields on CREDIT actions are silently ignored for SIMPLE-mode assets. No error is returned.