> ## 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.

# Asset Configuration

> Inventory modes, issuance policies, and precision settings

An asset defines the unit of value participants earn and spend. Points, cashback dollars, hotel nights, referral credits, promotional tokens. Each asset has its own ledger, and every credit has a corresponding debit somewhere in the system.

Three settings define how an asset behaves: **inventory mode**, **issuance policy**, and **scale**. All three are set at creation and cannot be changed afterward.

## Creating an Asset

```bash theme={null}
curl -X POST https://api.scrip.dev/v1/assets \
  -H "Authorization: Bearer $SCRIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "program_id": "{program_id}",
    "name": "Loyalty Points",
    "symbol": "PTS",
    "inventory_mode": "SIMPLE",
    "issuance_policy": "UNLIMITED",
    "scale": 0
  }'
```

| Field                    | Required | Description                                                                                                             |
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `program_id`             | Yes      | Links the asset to a program on creation                                                                                |
| `name`                   | Yes      | Display name (1-255 characters)                                                                                         |
| `symbol`                 | Yes      | Short code like `PTS`, `NIGHTS`, `USD` (1-16 alphanumeric characters, unique per org)                                   |
| `inventory_mode`         | Yes      | `SIMPLE` or `LOT`                                                                                                       |
| `issuance_policy`        | Yes      | `UNLIMITED` or `PREFUNDED`                                                                                              |
| `scale`                  | Yes      | Decimal precision, `0` to `18`                                                                                          |
| `max_transaction_amount` | No       | Optional per-transaction ceiling. Any single credit or debit exceeding this value is rejected. Positive decimal string. |

Assets are created at the organization level and automatically linked to the specified program. They can be [shared across programs](#asset-sharing).

## Inventory Mode

| Mode     | Behavior                                                                                                                                                                  | Use when                                                                                                           |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `SIMPLE` | Tracks one aggregate balance per account and bucket. Credits merge into the balance, and the system does not keep per-credit provenance.                                  | Basic points or credits with no expiration, vesting, auth matching, or issuer attribution                          |
| `LOT`    | Each credit creates a separate lot with its own remaining amount, issuer lineage, and optional expiration or maturity dates. Debits spend the oldest eligible lots first. | Expiration, vesting, auth/settlement correlation, oldest-first spending, partner settlement, or issuer attribution |

Choose `SIMPLE` only when the balance can be treated as one pool. It cannot later answer which program, campaign, partner, or credit issued the value that was redeemed.

Choose `LOT` when individual units of value carry meaning. For example, an airline program where points expire 18 months after they're earned should use `LOT`; each credit creates a lot with its own `expires_at`, and expired lots are automatically excluded when the participant spends.

A fixed budget alone does not require `LOT`: either mode works with `PREFUNDED` issuance.

See [Lots & Expiration](/guides/lots-and-expiration) for more on how lots work.

## Issuance Policy

| Policy      | Behavior                                                                                               | Use when                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| `UNLIMITED` | Credits mint new value on demand. No program wallet funding needed.                                    | Open-ended programs where supply doesn't need to be capped |
| `PREFUNDED` | Credits draw from the program wallet, which must be funded first. Credits fail if the wallet is empty. | Fixed budgets or strict supply control                     |

Most programs start with `UNLIMITED`. Use `PREFUNDED` when you have a hard cap, like a "\$50,000 Summer Promo" where the program wallet is funded once and credits stop when it's empty. See [Programs](/guides/programs#the-program-wallet) for how to fund and burn.

## Scale

The number of decimal places for all amounts on this asset. Any value from `0` to `18`.

| Scale | Example      | Common use                                            |
| ----- | ------------ | ----------------------------------------------------- |
| `0`   | `100`        | Whole units: loyalty points, nights, referral credits |
| `2`   | `49.99`      | Currency: dollars, euros, cashback                    |
| `8`   | `0.00000001` | High-precision tokens                                 |

Amounts with more decimal places than the configured `scale` are rounded (half-up) to fit. For example, crediting `"1.009"` on an asset with `scale: 2` records `"1.01"`. No error is returned. Use the `round()` function in CEL expressions when you need explicit control over precision before the amount reaches the ledger.

<Note>
  **Working in cents:** If your issuer-processor sends amounts in minor units (smallest currency denomination, e.g., 200 = \$2.00), use `scale: 0` and treat the asset as cents. Your application handles the display conversion. Alternatively, use `scale: 2` and pass dollar amounts directly.
</Note>

## Examples

The table below shows common asset configurations.

| Asset               | Symbol   | Scale | Mode     | Policy      | Description                                |
| ------------------- | -------- | ----- | -------- | ----------- | ------------------------------------------ |
| Loyalty points      | `PTS`    | `0`   | `SIMPLE` | `UNLIMITED` | Earn and redeem whole points               |
| Cashback            | `USD`    | `2`   | `SIMPLE` | `UNLIMITED` | Dollar-denominated rewards                 |
| Expiring points     | `PTS`    | `0`   | `LOT`    | `UNLIMITED` | Points that expire after 12 months         |
| Vesting rewards     | `TOKENS` | `2`   | `LOT`    | `UNLIMITED` | Credits that unlock after a waiting period |
| Promotional credits | `PROMO`  | `2`   | `SIMPLE` | `PREFUNDED` | Fixed-budget campaign with a capped pool   |

## Asset Sharing

Assets can be linked to multiple programs. This lets participants earn the same asset across different campaigns.

```bash theme={null}
POST /v1/programs/{programId}/assets
{"asset_id": "{asset_id}"}
```

When using `PREFUNDED` assets, each program maintains its own wallet balance independently. Funding one program doesn't affect another.

If a shared asset needs issuer attribution for cross-program settlement, create it as `LOT`. `SIMPLE` shared balances can still report total redemptions by channel, but they cannot reconstruct which program originally issued the redeemed value.

For example, a member earns 100 points through Program A and 50 points through Program B, then redeems 120 points through Program B. With `LOT`, redemption attribution can report 100 points issued by Program A and 20 issued by Program B, all redeemed through Program B. With `SIMPLE`, the report can show 120 points redeemed through Program B, but the original issuer split is no longer available.

## Updating Assets

You can update `name` and `max_transaction_amount`, and set `status` to `ARCHIVED` to permanently retire the asset. `symbol`, `inventory_mode`, `issuance_policy`, and `scale` are locked after creation.

```bash theme={null}
PATCH /v1/assets/{id}
{"name": "Premium Points", "max_transaction_amount": "5000.00"}
```

Set `max_transaction_amount` to `null` to remove the ceiling.