> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Model

> Reference map of Scrip's resources and how they relate

Every resource in the Scrip API is listed below with its key fields and relationships. For a higher-level walkthrough, see [Core Concepts](/guides/core-concepts).

All resources are identified by a UUID `id` assigned by Scrip. Many also carry an external identifier or human-readable key for integration with your system.

## Entity Overview

| Entity           | Description                                             | Key Fields                                                                                                                   | API Prefix                          |
| ---------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| Organization     | Top-level tenant that owns all other resources          | `id`, `name`, `status`                                                                                                       | Managed via dashboard               |
| Program          | Container for rules, assets, and participants           | `id`, `name`, `status`, `on_unknown_participant`                                                                             | `/v1/programs`                      |
| Asset            | Unit of value (points, cashback, credits)               | `id`, `name`, `symbol`, `scale`, `inventory_mode`, `issuance_policy`                                                         | `/v1/assets`                        |
| Participant      | A user in your system                                   | `id`, `external_id`, `status`, `email`, `phone`, `first_name`, `last_name`, `display_name`, `tags`, `counters`, `attributes` | `/v1/participants`                  |
| Group            | Collection of participants with shared wallet and state | `id`, `name`, `status`                                                                                                       | `/v1/groups`                        |
| Event            | Signal from your app that triggers rule evaluation      | `id`, `idempotency_key`, `event_data`, `status`                                                                              | `/v1/events`                        |
| Rule             | CEL condition + list of actions                         | `id`, `name`, `condition`, `actions`, `order`, `status`                                                                      | `/v1/rules`                         |
| Automation       | Scheduled or triggered event generation                 | `id`, `name`, `type`, `schedule`, `status`                                                                                   | `/v1/programs/{id}/automations`     |
| Tier Type        | Status hierarchy definition with levels                 | `id`, `key`, `display_name`, `levels`, `lifecycle`                                                                           | `/v1/programs/{id}/tiers`           |
| Reward           | Catalog item available for redemption                   | `id`, `name`, `unit_cost`, `redemption_type`, `status`                                                                       | `/v1/programs/{id}/rewards`         |
| Redemption       | Record of a participant spending balance                | `id`, `participant_id`, `asset_id`, `amount`, `status`                                                                       | `/v1/participants/{id}/redemptions` |
| Transfer         | Movement of value between participants and groups       | `id`, `source_external_id`, `recipients`, `total_amount`                                                                     | `/v1/transfers`                     |
| Journal Entry    | Double-entry ledger record                              | `id`, `postings`, `event_id`, `rule_id`, `created_at`                                                                        | `/v1/journal-entries`               |
| Lot              | Individual credit with expiration/vesting               | `id`, `asset_id`, `amount`, `expires_at`, `matures_at`                                                                       | via participant lots endpoint       |
| Webhook Endpoint | Registered URL that receives event notifications        | `id`, `url`, `enabled_events`, `status`, `secret`                                                                            | `/v1/webhook-endpoints`             |
| Webhook Delivery | Record of a delivery attempt to a webhook endpoint      | `id`, `webhook_event_id`, `webhook_endpoint_id`, `event_type`, `status`, `attempt_count`                                     | `/v1/webhook-deliveries`            |

## Relationships

* An **Organization** is the top-level tenant. Programs, Assets, Participants, and Groups all belong to an organization. API keys are scoped to an organization.
* A **Program** belongs to an Organization and contains Rules, links to Assets, and scopes Participants.
* An **Asset** exists at the organization level and can be linked to multiple Programs. Each program maintains independent wallet balances for prefunded assets.
* A **Participant** exists at the organization level and can participate across multiple Programs. Participants can be members of one or more Groups.
* **Events** are sent to a Program for a specific Participant. The event triggers rule evaluation against that participant's state.
* **Rules** belong to a Program and produce Journal Entries when their actions fire.
* **Redemptions**, **Transfers**, and balance adjustments all produce Journal Entries in the double-entry ledger.
* **Lots** track individual credits within a participant's balance. They only exist for assets using `LOT` inventory mode.
* **Tier Types** belong to a Program. Participants progress through tier levels based on counter qualification or explicit rule actions.
* **Automations** are scoped to a Program and generate Events on a schedule, at a specific time, or in response to participant state changes.
* **Webhook Endpoints** belong to an Organization. When domain events occur (balance changes, redemptions, tier transitions), matching endpoints receive signed HTTP notifications via Webhook Deliveries.

***

## Organization

The top-level tenant in Scrip. Every other resource (programs, assets, participants, groups) belongs to an organization. API keys are scoped to an organization. Organizations are managed through the [Scrip dashboard](https://app.scrip.dev), not the API.

### Key Fields

| Field        | Type                | Description                 |
| ------------ | ------------------- | --------------------------- |
| `id`         | `string (UUID)`     | Scrip-assigned identifier   |
| `name`       | `string`            | Display name                |
| `status`     | `string`            | Lifecycle state             |
| `created_at` | `string (RFC 3339)` | Creation timestamp          |
| `updated_at` | `string (RFC 3339)` | Last modification timestamp |

### Status Values

| Status     | Description      |
| ---------- | ---------------- |
| `ACTIVE`   | Normal operation |
| `ARCHIVED` | Deactivated      |

***

## Program

The top-level container within an organization that holds rules, links to assets, and scopes participants. Most teams create one program per use case.

### Key Fields

| Field                    | Type                | Description                                                        |
| ------------------------ | ------------------- | ------------------------------------------------------------------ |
| `id`                     | `string (UUID)`     | Scrip-assigned identifier                                          |
| `name`                   | `string`            | Display name                                                       |
| `status`                 | `string`            | Current lifecycle state                                            |
| `on_unknown_participant` | `string`            | Enrollment policy when an event arrives for an unknown participant |
| `description`            | `string`            | Optional context                                                   |
| `created_at`             | `string (RFC 3339)` | Creation timestamp                                                 |
| `updated_at`             | `string (RFC 3339)` | Last modification timestamp                                        |

### Status Values

| Status      | Description                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `ACTIVE`    | Events process and rules evaluate normally                                                             |
| `SUSPENDED` | Event processing fails with `program_inactive`. Can be reactivated.                                    |
| `ARCHIVED`  | Hidden from default listings. Event processing fails with `program_inactive`. Historical data remains. |

### Enrollment Policy

| Value    | Description                                      |
| -------- | ------------------------------------------------ |
| `CREATE` | Auto-create participant on first event (default) |
| `REJECT` | Reject events for unknown participants           |

See the [Programs guide](/guides/programs) for usage patterns. Browse the [Programs endpoints](/api-reference/programs/list-programs).

***

## Asset

Defines the unit of value participants earn and spend. Three immutable settings control behavior: inventory mode, issuance policy, and scale.

### Key Fields

| Field                    | Type                | Description                                                                                   |
| ------------------------ | ------------------- | --------------------------------------------------------------------------------------------- |
| `id`                     | `string (UUID)`     | Scrip-assigned identifier                                                                     |
| `name`                   | `string`            | Display name                                                                                  |
| `symbol`                 | `string`            | Short code (e.g., `PTS`, `USD`), unique per organization                                      |
| `scale`                  | `integer`           | Decimal precision (`0` to `18`)                                                               |
| `inventory_mode`         | `string`            | `SIMPLE` or `LOT`                                                                             |
| `issuance_policy`        | `string`            | `UNLIMITED` or `PREFUNDED`                                                                    |
| `max_transaction_amount` | `string (decimal)`  | Optional per-transaction ceiling. Rejects any single credit or debit that exceeds this value. |
| `created_at`             | `string (RFC 3339)` | Creation timestamp                                                                            |

### Inventory Mode

| Value    | Description                                                                                                      |
| -------- | ---------------------------------------------------------------------------------------------------------------- |
| `SIMPLE` | Single balance per bucket. No per-credit lifecycle, oldest-first spending, or issuer attribution.                |
| `LOT`    | Each credit creates a separate lot with optional expiration, vesting, oldest-first spending, and issuer lineage. |

### Issuance Policy

| Value       | Description                                                      |
| ----------- | ---------------------------------------------------------------- |
| `UNLIMITED` | Credits mint new value on demand                                 |
| `PREFUNDED` | Credits draw from the program wallet, which must be funded first |

See the [Asset Configuration guide](/guides/asset-configuration) for usage patterns. Browse the [Assets endpoints](/api-reference/assets/list-assets).

***

## Participant

A user in your system, identified by your own `external_id`. Carries profile information and state (tags, counters, attributes, tiers) that rules read and write.

### Key Fields

| Field          | Type                     | Description                                 |
| -------------- | ------------------------ | ------------------------------------------- |
| `id`           | `string (UUID)`          | Scrip-assigned identifier                   |
| `external_id`  | `string`                 | Your application's user identifier          |
| `status`       | `string`                 | Current lifecycle state                     |
| `email`        | `string`                 | Contact email (optional)                    |
| `phone`        | `string`                 | Contact phone number (optional)             |
| `first_name`   | `string`                 | First name (optional)                       |
| `last_name`    | `string`                 | Last name (optional)                        |
| `display_name` | `string`                 | Display name (optional)                     |
| `tags`         | `list (string)`          | Boolean flags (normalized to lowercase)     |
| `counters`     | `map (string -> number)` | Numeric accumulators                        |
| `attributes`   | `map (string -> string)` | Key-value metadata                          |
| `balances`     | `list`                   | Current balances per asset, split by bucket |
| `tiers`        | `map`                    | Current tier level per tier type            |
| `program_ids`  | `list (UUID)`            | Programs this participant is enrolled in    |
| `created_at`   | `string (RFC 3339)`      | Creation timestamp                          |

The [list endpoint](/api-reference/participants/list-or-get-participants) returns a slim response (`id`, `external_id`, `status`, profile fields, timestamps). The [detail endpoint](/api-reference/participants/get-a-participant-by-internal-id) returns all fields above in a single call.

### Identifiers

| ID            | Format | Use                                                              |
| ------------- | ------ | ---------------------------------------------------------------- |
| `id`          | UUID   | Scrip's internal identifier, used in all API paths               |
| `external_id` | String | Your application's user ID, used for lookups via query parameter |

### Status Values

| Status      | Earning | Spending | State Updates            |
| ----------- | ------- | -------- | ------------------------ |
| `ACTIVE`    | Yes     | Yes      | All                      |
| `SUSPENDED` | No      | No       | Tags and attributes only |
| `CLOSED`    | No      | No       | Tags and attributes only |

See the [Participants guide](/guides/participants) for usage patterns. Browse the [Participants endpoints](/api-reference/participants/list-or-get-participants).

***

## Group

A collection of participants that shares a wallet and state. Groups exist at the organization level and can participate across programs.

### Key Fields

| Field        | Type                     | Description                                                                                        |
| ------------ | ------------------------ | -------------------------------------------------------------------------------------------------- |
| `id`         | `string (UUID)`          | Scrip-assigned identifier                                                                          |
| `name`       | `string`                 | Display name                                                                                       |
| `status`     | `string`                 | `ACTIVE` or `ARCHIVED`                                                                             |
| `members`    | `list`                   | Participant members with roles (via [members endpoints](/api-reference/groups/list-group-members)) |
| `tags`       | `list (string)`          | Group-level boolean flags (via [state endpoints](/api-reference/groups/get-group-tags))            |
| `counters`   | `map (string -> number)` | Group-level numeric accumulators (via [state endpoints](/api-reference/groups/get-group-counters)) |
| `attributes` | `map (string -> string)` | Group-level key-value metadata (via [state endpoints](/api-reference/groups/get-group-attributes)) |

### Member Roles

| Role     | Description                 |
| -------- | --------------------------- |
| `ADMIN`  | Can manage group membership |
| `MEMBER` | Standard member             |

See the [Groups guide](/guides/groups) for usage patterns. Browse the [Groups endpoints](/api-reference/groups/list-groups).

***

## Event

A signal from your application that triggers rule evaluation. Events are processed asynchronously and deduplicated by `idempotency_key` per program.

### Key Fields

| Field             | Type                | Description                                                   |
| ----------------- | ------------------- | ------------------------------------------------------------- |
| `id`              | `string (UUID)`     | Scrip-assigned identifier                                     |
| `program_id`      | `string (UUID)`     | Target program                                                |
| `external_id`     | `string`            | Participant's external identifier                             |
| `participant_id`  | `string (UUID)`     | Participant's Scrip identifier (alternative to `external_id`) |
| `idempotency_key` | `string`            | Unique key per program for exactly-once processing            |
| `event_timestamp` | `string (RFC 3339)` | When the event occurred in your system                        |
| `event_data`      | `object`            | JSON payload available to rules as `event.*` in CEL           |
| `status`          | `string`            | Processing state                                              |
| `created_at`      | `string (RFC 3339)` | Ingestion timestamp                                           |

### Status Values

| Status       | Description                              |
| ------------ | ---------------------------------------- |
| `PENDING`    | Received, waiting for processing         |
| `PROCESSING` | Worker is evaluating rules               |
| `COMPLETED`  | All rules evaluated and actions executed |
| `FAILED`     | Processing error or max retries exceeded |

See the [Event Processing guide](/guides/event-processing) for usage patterns. Browse the [Events endpoints](/api-reference/events/list-events).

***

## Rule

A CEL condition paired with a list of actions. When an event is processed, rules evaluate in order. Matching rules execute their actions within the same transaction.

### Key Fields

| Field              | Type                | Description                                   |
| ------------------ | ------------------- | --------------------------------------------- |
| `id`               | `string (UUID)`     | Scrip-assigned identifier                     |
| `program_id`       | `string (UUID)`     | Owning program                                |
| `name`             | `string`            | Display name                                  |
| `condition`        | `string`            | CEL expression that must return `true`        |
| `actions`          | `list`              | Actions to execute when the condition matches |
| `order`            | `integer`           | Evaluation order (lower first)                |
| `stop_after_match` | `boolean`           | Skip subsequent rules when this one matches   |
| `active_from`      | `string (RFC 3339)` | Start of time window (optional)               |
| `active_to`        | `string (RFC 3339)` | End of time window (optional)                 |
| `budgets`          | `list`              | Per-asset spending caps                       |
| `status`           | `string`            | Current lifecycle state                       |

### Status Values

| Status      | Description                                                  |
| ----------- | ------------------------------------------------------------ |
| `ACTIVE`    | Evaluates on every event                                     |
| `SUSPENDED` | Skipped during evaluation. Can be reactivated.               |
| `ARCHIVED`  | Soft-deleted. Excluded from evaluation and default listings. |

See the [Writing Rules guide](/guides/writing-rules) for usage patterns. Browse the [Rules endpoints](/api-reference/rules/list-rules).

***

## Automation

Generates events on a schedule, at a specific time, or in response to participant state changes. Scoped to a program.

### Key Fields

| Field                        | Type                | Description                                                                             |
| ---------------------------- | ------------------- | --------------------------------------------------------------------------------------- |
| `id`                         | `string (UUID)`     | Scrip-assigned identifier                                                               |
| `program_id`                 | `string (UUID)`     | Owning program                                                                          |
| `name`                       | `string`            | Display name (unique per program)                                                       |
| `trigger.type`               | `string`            | `cron`, `one_time`, `immediate`, or `participant_state`                                 |
| `scope`                      | `string`            | `program` or `participants`                                                             |
| `event_name`                 | `string`            | Event type generated when the automation fires                                          |
| `payload`                    | `object`            | JSON merged into the event's `event_data`                                               |
| `participant_filter`         | `string (CEL)`      | Controls which participants get subscriptions. Evaluated during participant evaluation. |
| `guard_condition`            | `string (CEL)`      | Checked at trigger time. When `false`, the event is skipped for that participant.       |
| `participants_skipped_error` | `number`            | Count of participants skipped because the filter or guard expression errored            |
| `status`                     | `string`            | Current lifecycle state                                                                 |
| `last_run_at`                | `string (RFC 3339)` | Timestamp of the most recent execution                                                  |

### Status Values

| Status      | Description                                                          |
| ----------- | -------------------------------------------------------------------- |
| `active`    | Ready to fire on schedule                                            |
| `paused`    | Disabled. Will not fire until reactivated.                           |
| `completed` | Terminal. One-time and immediate automations move here after firing. |
| `failed`    | Terminal. Disabled after repeated consecutive failures.              |
| `archived`  | Soft-deleted via the delete endpoint.                                |

Automation statuses are lowercase, unlike other resources which use uppercase.

See the [Automations guide](/guides/automations) for usage patterns. Browse the [Automations endpoints](/api-reference/automations/list-automations).

***

## Tier Type

Defines a ranked progression track (e.g., Silver / Gold / Platinum) with ordered levels. Participants advance based on counter qualification or explicit rule actions.

### Key Fields

| Field          | Type            | Description                                                                   |
| -------------- | --------------- | ----------------------------------------------------------------------------- |
| `id`           | `string (UUID)` | Scrip-assigned identifier                                                     |
| `key`          | `string`        | Unique identifier within the program                                          |
| `display_name` | `string`        | Human-readable name                                                           |
| `levels`       | `list`          | Ordered tier levels, each with `key`, `rank`, `qualification`, and `benefits` |
| `lifecycle`    | `object`        | Retention mode, qualification period, downgrade policy, and counter rollover  |

### Level Fields

| Field           | Type      | Description                                      |
| --------------- | --------- | ------------------------------------------------ |
| `key`           | `string`  | Unique within the tier type                      |
| `rank`          | `integer` | Hierarchy position (higher = higher tier)        |
| `display_name`  | `string`  | Human-readable name                              |
| `qualification` | `object`  | Counter-based criteria for automatic advancement |
| `benefits`      | `object`  | Arbitrary JSON returned with tier state          |

See the [Tiers guide](/guides/tiers) for usage patterns. Browse the [Tiers endpoints](/api-reference/tiers/list-tiers).

***

## Reward

A catalog item that participants can redeem with their balance. Scoped to a program and priced in a linked asset.

### Key Fields

| Field                 | Type                | Description                                               |
| --------------------- | ------------------- | --------------------------------------------------------- |
| `id`                  | `string (UUID)`     | Scrip-assigned identifier                                 |
| `name`                | `string`            | Display name (unique per program)                         |
| `redemption_type`     | `string`            | `UNIT_BASED` or `AMOUNT_BASED` (immutable after creation) |
| `asset_id`            | `string (UUID)`     | Asset this reward is priced in (immutable after creation) |
| `unit_cost`           | `string (decimal)`  | Cost per unit, or minimum amount for `AMOUNT_BASED`       |
| `max_total`           | `integer`           | Global inventory cap (`UNIT_BASED` only)                  |
| `max_per_participant` | `integer`           | Per-participant cap (`UNIT_BASED` only)                   |
| `redeemed_count`      | `integer`           | Current global redemption count                           |
| `available_from`      | `string (RFC 3339)` | Start of availability window                              |
| `available_until`     | `string (RFC 3339)` | End of availability window                                |
| `status`              | `string`            | Current lifecycle state                                   |

### Status Values

| Status         | Description                                |
| -------------- | ------------------------------------------ |
| `DRAFT`        | Not yet available for redemption           |
| `ACTIVE`       | Available for redemption                   |
| `OUT_OF_STOCK` | Inventory exhausted (set automatically)    |
| `ARCHIVED`     | Removed from listings. Cannot be redeemed. |

See the [Rewards Catalog guide](/guides/rewards-catalog) for usage patterns. Browse the [Rewards endpoints](/api-reference/rewards/list-rewards).

***

## Redemption

A record of a participant spending balance, either as a raw amount debit or a catalog item purchase. Supports full and partial reversals.

### Key Fields

| Field             | Type                | Description                                      |
| ----------------- | ------------------- | ------------------------------------------------ |
| `id`              | `string (UUID)`     | Scrip-assigned identifier                        |
| `participant_id`  | `string (UUID)`     | Participant who redeemed                         |
| `program_id`      | `string (UUID)`     | Program context                                  |
| `asset_id`        | `string (UUID)`     | Asset debited                                    |
| `amount`          | `string (decimal)`  | Total amount debited                             |
| `reward_id`       | `string (UUID)`     | Catalog item redeemed (null for raw redemptions) |
| `description`     | `string`            | Reason for the redemption                        |
| `idempotency_key` | `string`            | Deduplication key (scoped per program)           |
| `reversed_amount` | `string (decimal)`  | Cumulative amount reversed                       |
| `status`          | `string`            | Current state                                    |
| `created_at`      | `string (RFC 3339)` | Creation timestamp                               |

### Status Values

| Status               | Description                           |
| -------------------- | ------------------------------------- |
| `COMPLETED`          | No reversals applied                  |
| `PARTIALLY_REVERSED` | Some amount reversed, more can follow |
| `FULLY_REVERSED`     | Entire redemption reversed            |

See the [Redemptions guide](/guides/redemptions) for usage patterns. Browse the [Redemptions endpoints](/api-reference/redemptions/redeem-points-assets).

***

## Transfer

An atomic movement of funds from one participant or group to one or more recipients. Zero-sum: the source is debited by the total credited to all recipients.

### Key Fields

| Field                   | Type               | Description                                                                                   |
| ----------------------- | ------------------ | --------------------------------------------------------------------------------------------- |
| `id`                    | `string (UUID)`    | Scrip-assigned identifier                                                                     |
| `program_id`            | `string (UUID)`    | Program context                                                                               |
| `asset_id`              | `string (UUID)`    | Asset transferred                                                                             |
| `source_external_id`    | `string`           | Participant sending funds, by external ID                                                     |
| `source_participant_id` | `string (UUID)`    | Participant sending funds, by Scrip UUID                                                      |
| `source_group_id`       | `string (UUID)`    | Group sending funds                                                                           |
| `recipients`            | `list`             | Array of recipients, each with `external_id`, `participant_id`, or `group_id` and an `amount` |
| `total_amount`          | `string (decimal)` | Sum of all recipient amounts                                                                  |
| `description`           | `string`           | Reason for the transfer                                                                       |
| `idempotency_key`       | `string`           | Deduplication key (scoped per program)                                                        |
| `journal_entry_id`      | `string (UUID)`    | Corresponding ledger record                                                                   |

<Note>
  Exactly one source identifier is required per transfer. The three source fields (`source_external_id`, `source_participant_id`, `source_group_id`) are mutually exclusive.
</Note>

See the [Transfers guide](/guides/transfers) for usage patterns. Browse the [Transfers endpoints](/api-reference/transfers/create-a-transfer).

***

## Journal Entry

An immutable double-entry ledger record. Every balance change (credits, debits, holds, releases, forfeits, redemptions, transfers) produces a journal entry with postings that sum to zero.

### Key Fields

| Field                   | Type                | Description                                                                                                  |
| ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `id`                    | `string (UUID)`     | Scrip-assigned identifier                                                                                    |
| `description`           | `string`            | Human-readable summary                                                                                       |
| `postings`              | `list`              | Debit and credit lines, each with account, signed amount, and bucket                                         |
| `event_id`              | `string (UUID)`     | Event that triggered this entry (null for direct API operations)                                             |
| `action_type`           | `string`            | Ledger action type (e.g. `CREDIT`, `DEBIT`, `HOLD`, `RELEASE`, `FORFEIT`, `MATURITY`)                        |
| `reference_id`          | `string`            | Correlation ID linking hold, release, and settle operations (LOT-mode assets only, null when not applicable) |
| `created_by_api_key_id` | `string (UUID)`     | API key that triggered this entry (null for rule-triggered operations)                                       |
| `entry_hash`            | `string`            | SHA-256 hash sealing this entry into the organization's hash chain                                           |
| `created_at`            | `string (RFC 3339)` | Creation timestamp                                                                                           |

### Posting Fields

| Field            | Type                | Description                                                                                                         |
| ---------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `id`             | `string (UUID)`     | Posting identifier                                                                                                  |
| `entity_type`    | `string`            | Account owner type: `PARTICIPANT`, `PROGRAM`, `GROUP`, `SYSTEM_ISSUANCE`, `SYSTEM_BREAKAGE`, or `SYSTEM_REDEMPTION` |
| `asset_symbol`   | `string`            | Symbol of the asset being transacted                                                                                |
| `amount`         | `string (decimal)`  | Signed amount (positive = credit, negative = debit)                                                                 |
| `bucket`         | `string`            | `AVAILABLE`, `HELD`, or `DEFERRED`                                                                                  |
| `participant_id` | `string (UUID)`     | Participant who owns this account (present when `entity_type` is `PARTICIPANT`)                                     |
| `group_id`       | `string (UUID)`     | Group that owns this account (present when `entity_type` is `GROUP`)                                                |
| `program_id`     | `string (UUID)`     | Program that owns this account (present when `entity_type` is `PROGRAM`)                                            |
| `created_at`     | `string (RFC 3339)` | Creation timestamp                                                                                                  |

See the [Ledger guide](/guides/ledger) for usage patterns. Browse the [Reporting endpoints](/api-reference/reporting/list-journal-entries).

***

## Lot

An individual credit with its own balance, expiration, vesting date, and issuer lineage. Only exists for assets using `LOT` inventory mode. When funds are debited, the oldest eligible lots are spent first.

### Key Fields

| Field          | Type                | Description                                                                                 |
| -------------- | ------------------- | ------------------------------------------------------------------------------------------- |
| `id`           | `string (UUID)`     | Scrip-assigned identifier                                                                   |
| `asset_id`     | `string (UUID)`     | Asset this lot belongs to                                                                   |
| `amount`       | `string (decimal)`  | Original credited amount                                                                    |
| `remaining`    | `string (decimal)`  | Current unspent balance                                                                     |
| `status`       | `string`            | Current lifecycle state                                                                     |
| `reference_id` | `string`            | Correlation ID linking this held lot to a hold operation (null when not held via reference) |
| `created_at`   | `string (RFC 3339)` | Creation timestamp                                                                          |
| `expires_at`   | `string (RFC 3339)` | Expiration deadline (null if no expiry)                                                     |
| `matures_at`   | `string (RFC 3339)` | Vesting date (null if immediately available)                                                |

### Status Values

| Status      | Spendable | Description                                                         |
| ----------- | --------- | ------------------------------------------------------------------- |
| `DEFERRED`  | No        | Lot has a future `matures_at` and is waiting for automatic maturity |
| `AVAILABLE` | Yes       | Mature and spendable                                                |
| `HELD`      | No        | Reserved via a hold operation                                       |
| `CONSUMED`  | No        | Fully spent                                                         |
| `EXPIRED`   | No        | `expires_at` has passed, forfeited to breakage                      |

Lots credited with a future `matures_at` land in `DEFERRED` and automatically transition to `AVAILABLE` when the maturity date passes. `DEFERRED` is read-only and cannot be targeted by rules or API writes.

See the [Lots & Expiration guide](/guides/lots-and-expiration) for usage patterns. Browse the [Participant lots endpoint](/api-reference/participants/list-participant-lots).

***

## Webhook Endpoint

A registered URL that receives signed HTTP notifications when domain events occur. Endpoints are scoped to an organization and filter events by type.

### Key Fields

| Field                  | Type                | Description                                                                       |
| ---------------------- | ------------------- | --------------------------------------------------------------------------------- |
| `id`                   | `string (UUID)`     | Scrip-assigned identifier                                                         |
| `url`                  | `string`            | HTTPS destination URL                                                             |
| `description`          | `string`            | Human-readable label                                                              |
| `secret`               | `string`            | HMAC-SHA256 signing secret (`whsec_` prefix). Only returned on create and rotate. |
| `enabled_events`       | `list (string)`     | Subscribed event types, or `["*"]` for all                                        |
| `status`               | `string`            | Current lifecycle state                                                           |
| `metadata`             | `object`            | Arbitrary key-value metadata                                                      |
| `circuit_broken_until` | `string (RFC 3339)` | When sustained failures have paused deliveries until a cooldown expires           |
| `rate_limited_until`   | `string (RFC 3339)` | Time until which 429 backoff has paused deliveries                                |
| `created_at`           | `string (RFC 3339)` | Creation timestamp                                                                |
| `updated_at`           | `string (RFC 3339)` | Last modification timestamp                                                       |

### Status Values

| Status     | Description                                                                                                  |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| `ACTIVE`   | Receiving deliveries                                                                                         |
| `DISABLED` | Not receiving deliveries. Can be reactivated. Queued deliveries are failed out when an endpoint is disabled. |
| `ARCHIVED` | Soft-deleted via the delete endpoint. Queued deliveries are failed out when an endpoint is archived.         |

See the [Webhooks guide](/guides/webhooks) for usage patterns. Browse the [Webhooks endpoints](/api-reference/webhooks/list-webhook-endpoints).

***

## Webhook Delivery

A record of a delivery attempt from a webhook event to a specific endpoint. Tracks attempt count, response details, and retry scheduling.

### Key Fields

| Field                  | Type                | Description                                                          |
| ---------------------- | ------------------- | -------------------------------------------------------------------- |
| `id`                   | `string (UUID)`     | Scrip-assigned identifier                                            |
| `webhook_event_id`     | `string (UUID)`     | Event that triggered this delivery                                   |
| `webhook_endpoint_id`  | `string (UUID)`     | Target endpoint                                                      |
| `event_type`           | `string`            | Event type (e.g. `balance.credited`)                                 |
| `status`               | `string`            | Current delivery state                                               |
| `attempt_count`        | `integer`           | Number of attempts made                                              |
| `max_attempts`         | `integer`           | Maximum attempts before marking failed (default 8)                   |
| `next_attempt_at`      | `string (RFC 3339)` | When the next attempt is scheduled                                   |
| `last_attempt_at`      | `string (RFC 3339)` | When the last attempt was made                                       |
| `last_response_status` | `integer`           | HTTP status code from the last attempt                               |
| `last_response_body`   | `string`            | Response body from the last attempt (truncated to 4 KB)              |
| `last_error`           | `string`            | Error message for network-level failures                             |
| `error_code`           | `string`            | Stable machine-readable failure classification                       |
| `delivered_at`         | `string (RFC 3339)` | When successfully delivered                                          |
| `resend_seq`           | `integer`           | Manual resend sequence (`0` for original delivery, `1+` for resends) |
| `created_at`           | `string (RFC 3339)` | Creation timestamp                                                   |
| `updated_at`           | `string (RFC 3339)` | Last modification timestamp                                          |

### Status Values

| Status      | Description                                                |
| ----------- | ---------------------------------------------------------- |
| `PENDING`   | Awaiting delivery attempt                                  |
| `SENDING`   | Claimed by the delivery worker                             |
| `DELIVERED` | Successfully delivered (2xx response)                      |
| `FAILED`    | Permanently failed (4xx response or max attempts exceeded) |

See the [Webhooks guide](/guides/webhooks) for usage patterns. Browse the [Webhooks endpoints](/api-reference/webhooks/list-webhook-deliveries).