# Products and prepaid credits

Use `Products` for a catalog of fixed-price purchases, and `Credit Token` for a prepaid balance bought in scalable units. Neither standard proves off-chain delivery or automatically settles refunds.

## Product catalog variants

`bb build product-catalog --products <json> --store-address <address>` creates one token ID per array entry, beginning at 1. `bb products build` is the corresponding alias. Each product has `name`, `price`, and `denom`; optional fields are `maxSupply`, `burn`, `uri`, `image`, and `description`. Provide collection metadata with `--uri` or the complete inline metadata fields.

| Configuration | Purchase result | Tracking |
| --- | --- | --- |
| Default product | Buyer keeps one unit of the product ID | Its purchase approval tracks sales when capped |
| `burn: true` | Purchase mints directly to the burn address | A sale does not leave the buyer a collectible balance |
| Positive `maxSupply` | At most that many successful purchases through the product approval | Overall transfer count, separately scoped per product approval |
| Missing or zero `maxSupply` | Unlimited sales through that approval | Do not interpret zero as sold out |
| Multiple catalog entries | Independent product IDs, prices, denominations, and caps | No shared catalog-wide stock cap |

Prices are display-unit numbers converted to the resolved denomination's base units. `maxSupply` must be a non-negative integer. Per-product metadata overrides catalog defaults; a catalog URI can supply a fallback when product metadata is omitted.

```bash
bb build product-catalog --products '[{"name":"Admission","price":5,"denom":"USDC","maxSupply":100,"burn":true}]' \
  --store-address "$STORE" --creator "$CREATOR" --uri "$METADATA_URI"
bb products list "$COLLECTION_ID"
bb products show "$COLLECTION_ID"
bb products purchase "$COLLECTION_ID" --token-id 1 --creator "$BUYER"
```

The purchase action buys one unit. The standard also contains a holder burn approval, but no dedicated `bb products burn` command is registered. Use the generic transfer tools with the matching approval when needed. Burning a receipt is not a refund, and a purchase count is not a delivery count. The builder freezes collection permissions; do not assume a mutable stock or price editor exists for the created catalog.

## Credit Token variants

```bash
bb build credit-token --payment-denom USDC --recipient "$STORE" \
  --tokens-per-unit 100 --creator "$CREATOR" --uri "$METADATA_URI"
bb credit-tokens list "$COLLECTION_ID"
bb credit-tokens show "$COLLECTION_ID"
bb credit-tokens purchase "$COLLECTION_ID" --units 3 --creator "$BUYER"
```

The builder's `credit-scaled` approval defines the tokens received per payment unit. `--units` is an integer multiplier of that purchase unit, not a token display amount: with 100 tokens per unit, three units buy 300 raw token units and scale the required payment by three. The current builder sets the payment leg to one base unit of the payment denomination per multiplier; do not read the builder help’s “per display unit” wording as the actual emitted price. Wrapper display decimals are separate from raw token amounts. `--payment-denom` also accepts the builder alias `--denom`. The token symbol defaults to `CREDIT`.

The action also recognizes older fixed purchase tiers through `--tier <approvalId>`; those require `--units 1` per invocation. The scaled helper caps a request at a positive configured maximum multiplier, so verify the emitted quantity rather than assuming an oversized request is fulfilled unchanged. `--api-credits` selects BitBadges' own API credit collection where configured and is mutually exclusive with a positional collection ID; the standard otherwise supports arbitrary recognized Credit Token collections.

Credits are non-transferable: purchase with the address that will hold and use them. A throwaway creator wallet is not a substitute for the buyer. Track remaining usable balance separately from purchase history and any application consumption policy. There is no generic refund or service-delivery action in the credit CLI.

See [product catalog primitives](https://docs.bitbadges.io/agents/skills/product-catalog), [credit token primitives](https://docs.bitbadges.io/agents/skills/credit-token), [coin transfers](https://docs.bitbadges.io/token-standard/approval-criteria/coin-transfers), and [approval trackers](https://docs.bitbadges.io/token-standard/approval-criteria/approval-trackers). Run the command's `--help` and inspect emitted messages before using optional signing flags.

## Product JSON

Save the following input as `product-catalog.json`, replace the demo addresses and metadata, then build it with the CLI command below. Each array entry receives token ID `index + 1`. `price` is a display-unit number; `maxSupply` counts purchases. `burn` controls whether the purchase leaves a holder receipt. `storeAddress` receives every product payment.

<!-- sdk-example: buildProductCatalog -->
```json
{
  "products": [
    {
      "name": "Admission",
      "price": 5,
      "denom": "BADGE",
      "maxSupply": 100,
      "burn": true
    }
  ],
  "storeAddress": "bb1xvenxvenxvenxvenxvenxvenxvenxvenlrd2nm",
  "uri": "https://example.com/metadata.json"
}
```

```bash
bb build product-catalog --json product-catalog.json \
  --products "$(jq -c '.products' product-catalog.json)" \
  --store-address "$(jq -r '.storeAddress' product-catalog.json)" \
  --creator "$CREATOR" --output-file product-catalog-proposal.json
```

The repeated required flags are read from the same JSON file because CLI argument validation runs before loading JSON. Review the resulting proposal using the [CLI lifecycle](https://docs.bitbadges.io/standards/lifecycle). SDK reference: `buildProductCatalog`.

## Credit JSON

Save the following input as `credit-token.json`, replace the demo addresses and metadata, then build it with the CLI command below. `tokensPerUnit` is a raw-token integer multiplier. The emitted `credit-scaled` payment leg is one base unit, despite the older parameter comment describing display units. The caller must inspect the emitted exchange rate before creating a priced service.

<!-- sdk-example: buildCreditToken -->
```json
{
  "paymentDenom": "BADGE",
  "recipient": "bb1xvenxvenxvenxvenxvenxvenxvenxvenlrd2nm",
  "symbol": "CREDIT",
  "tokensPerUnit": 100,
  "uri": "https://example.com/metadata.json"
}
```

```bash
bb build credit-token --json credit-token.json \
  --recipient "$(jq -r '.recipient' credit-token.json)" \
  --creator "$CREATOR" --output-file credit-token-proposal.json
```

The repeated required flags are read from the same JSON file because CLI argument validation runs before loading JSON. Review the resulting proposal using the [CLI lifecycle](https://docs.bitbadges.io/standards/lifecycle). SDK reference: `buildCreditToken`.