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.

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.

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#

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, credit token primitives, coin transfers, and 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.

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

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

{
  "paymentDenom": "BADGE",
  "recipient": "bb1xvenxvenxvenxvenxvenxvenxvenxvenlrd2nm",
  "symbol": "CREDIT",
  "tokensPerUnit": 100,
  "uri": "https://example.com/metadata.json"
}

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. SDK reference: buildCreditToken.