Skip to main content

Define your product catalog

This guide defines how to model sellable offers with products and prices.

Prereqs​

Step 1: model products as commercial containers​

A catalog product is a commercial package root.

Choose:

  • kind: subscription or credit
  • status: draft, active, or archived
  • default_currency: 3-letter uppercase currency code (for example USD)
  • default_currency is a display/defaulting anchor, not a gate or entitlement rule.

Use stable business keys:

  • product_code: your stable product key
  • provider_product_id: provider-facing id (for example Stripe product id)

Both should be treated as long-lived identifiers.

Step 2: model prices as purchasable entries​

A catalog price is a purchasable option under one product.

Define:

  • price_code: stable business key
  • provider_price_id: provider-facing id
  • currency + unit_amount (minor units)
  • status: active or archived
  • optional recurring shape:
    • recurring_interval: month or year
    • recurring_count: positive integer
  • optional subscription grouping:
    • subscription_group_id
    • subscription_group_key

Recurring prices must belong to a subscription group.

Step 3: decide deterministic storefront ordering​

Catalog lists are ordered deterministically.

For prices within a product, ordering is:

  1. display_priority ascending
  2. unit_amount ascending
  3. deterministic final tiebreaker

This order influences default-price selection in catalog reads.

Step 4: design metadata ownership​

Catalog metadata keys with system behavior:

  • Product metadata:
    • billing_plan_code
    • grants[]
  • Price metadata:
    • billing_plan_code
    • grants[]
    • gating.bundle

Ownership recommendation:

  • pricing/packaging owner: billing_plan_code
  • growth/funding owner: grants[]
  • runtime access owner: gating.bundle
  • UI/presentation owner: presentation_config

Use one owning team per key family.

Step 5: keep presentation config UI-only​

presentation_config is for display/UI configuration only.

Do not encode runtime billing logic in presentation_config.

Verify​

  • You can explain each product's kind and lifecycle status.
  • You can explain each price's recurring/grouping shape.
  • You can explain which team owns each metadata key family.
  • You can predict which price will be selected first by list/default order.

Next​