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, key, 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, tags, counters, attributes | /v1/participants |
| Group | Collection of participants for team-based incentives | id, name, key, type | /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 | 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 |
| Request Log | Record of an API request | id, method, path, status_code, duration_ms | /v1/logs |
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
LOTinventory 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, 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 |
key | string | URL-safe identifier |
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 | New events are rejected. Can be reactivated. |
ARCHIVED | Hidden from default listings. Historical data remains. |
Enrollment Policy
| Value | Description |
|---|---|
CREATE | Auto-create participant on first event (default) |
REJECT | Reject events for unknown participants |
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. |
LOT | Each credit creates a separate lot with optional expiration and vesting. |
Issuance Policy
| Value | Description |
|---|---|
UNLIMITED | Credits mint new value on demand |
PREFUNDED | Credits draw from the program wallet, which must be funded first |
Participant
A user in your system, identified by your ownexternal_id. Carries 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 |
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 |
id, external_id, status, timestamps). The detail endpoint 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 |
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 |
key | string | URL-safe identifier |
type | string | Group classification |
members | list | Participant members with roles (ADMIN or MEMBER) |
tags | list (string) | Group-level boolean flags |
counters | map (string -> number) | Group-level numeric accumulators |
attributes | map (string -> string) | Group-level key-value metadata |
Member Roles
| Role | Description |
|---|---|
ADMIN | Can manage group membership |
MEMBER | Standard member |
Event
A signal from your application that triggers rule evaluation. Events are processed asynchronously and deduplicated byidempotency_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 |
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. |
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 |
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. |
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 |
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. |
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 |
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 (mutually exclusive with source_participant_id and source_group_id) |
source_participant_id | string (UUID) | Participant sending funds by Scrip UUID (mutually exclusive with source_external_id and source_group_id) |
source_group_id | string (UUID) | Group sending funds (mutually exclusive with source_external_id and source_participant_id) |
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 |
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 |
Lot
An individual credit with its own balance, expiration, and vesting date. Only exists for assets usingLOT inventory mode. Lots are consumed in FIFO order when funds are debited.
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 |
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 for usage patterns. Browse the Participant lots endpoint.
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 |
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. |
ARCHIVED | Soft-deleted via the delete endpoint. |
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) | The event that triggered this delivery |
webhook_endpoint_id | string (UUID) | The target endpoint |
event_type | string | The event type that triggered this delivery (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 |
delivered_at | string (RFC 3339) | When successfully delivered |
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) |
Request Log
A record of an API request made to your organization. Useful for debugging, auditing, and monitoring.Key Fields
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Scrip-assigned identifier |
method | string | HTTP method (GET, POST, etc.) |
path | string | Request path |
status_code | integer | HTTP response status code |
duration_ms | integer | Request duration in milliseconds |
auth_type | string | Authentication method used |
request_id | string | Value of the X-Request-ID header |
created_at | string (RFC 3339) | Request timestamp |