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.

The service uses the provider configured on the Realm when publishing the catalog; catalog create and update requests do not accept provider fields.

Use stable business keys:

  • product_code: your stable product key

provider_product_id is provider mapping state. Leave it unset when defining a product; catalog synchronization populates or repairs it after matching or creating the provider product.

Step 2: model prices as purchasable entries​

A catalog price is a purchasable option under one product.

Define:

  • price_code: stable business key
  • 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

provider_price_id is also synchronization-owned mapping state and remains unset until the provider price has been matched or created.

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 billing-plan and metadata ownership​

Catalog fields with system behavior:

  • Product and Price expose billing_plan_code as an explicit field.
  • A Price-level value overrides the Product-level value; null inherits the Product value.
  • Product and Price metadata.grants[] configure purchase-driven grants.
  • Catalog metadata.gate_bundle_key is optional packaging input.

Ownership recommendation:

  • pricing/packaging owner: billing_plan_code
  • growth/funding owner: grants[]
  • runtime access owner: plan gate_bundle_key
  • 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 billing field and metadata key family.
  • You can predict which price will be selected first by list/default order.

Next​