---
title: "Get Billing Catalog"
method: GET
path: "/billing/catalog"
tags: ["accepts-api-key"]
---

# Get Billing Catalog

`GET /billing/catalog`

## Request

- Base URL: `https://api.tellers.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.tellers.ai/billing/catalog`
- Auth: none declared

## Headers

- `If-None-Match` string, nullable

## Response `200`

Successful Response

- BillingCatalog
  - `plans` union[], required
    - union
      - CatalogPlanOneOff: Prepaid token pack.
        - `tier_id` string, required
        - `display_name` string, required: Human-readable plan name for frontend display.
        - `subtitle` string: Optional short subtitle/description displayed under the plan name.
        - `cta_text` string: Optional call-to-action label shown on the plan button.
        - `highlights` CatalogHighlight[]: Up to two compact highlights for frontend display (number + text).
          - `number` number, nullable: Optional numeric value to display prominently.
          - `stripe_price_id` string, nullable: Optional Stripe price id used by UI when refreshing highlight values.
          - `text` string, required: Label displayed under/next to the number.
        - `features` CatalogFeature[]: Human-readable feature bullets for this plan (frontend display).
          - `text` string, required: User-facing feature/highlight text.
          - `icon_key` string, nullable: Optional semantic icon key that frontend maps to an icon.
        - `enabled` boolean
        - `currencies` string[]: Lowercase currencies every price of this plan can be charged in; valid values for the checkout `currency` parameter.
        - `default_items` PlanLineItem[], required: Suggested default cart rows (empty list when not applicable).
          - `price_id` string, required
          - `quantity` integer, required: Default quantity for this price.
          - `quantity_step` integer, required: Checkout quantity step for this item.
          - `units_per_quantity` number: Multiplier to convert checkout quantity into displayed units for this item.
        - `pricing` PlanPricing, required: Pricing-only blob for Rust ``pricing_preview_json`` (``lines`` only). Default starter quantities live on the plan as ``default_items``.
          - `lines` CatalogPricingLine[], required: Priced Stripe lines (one for typical one-off; two for subscription).
            - `stripe_price_id` string, required
            - `display_name` string: Human-readable label for this Stripe price line (frontend display).
            - `unit_amount_cents` number: Effective unit price in cents per displayed unit (e.g. per token). For Stripe prices configured per pack/group, this is normalized using Stripe transform quantity metadata.
            - `min_quantity` integer, nullable: Checkout minimum quantity for this price (one-off packs).
            - `max_quantity` integer, nullable: Checkout maximum quantity for this price (one-off packs).
            - `tier_pricing_from_stripe` boolean: If true, replace this price line with tier bands fetched from Stripe (subscription only).
            - `tiers_mode` 'graduated' | 'volume', nullable: For Stripe tiered prices: `graduated` vs `volume` (Stripe Price `tiers_mode`). Set on each band when `tier_pricing_from_stripe` lines are expanded from Stripe.
            - `user_can_modify_at_checkout` boolean: False when the line is fixed: it must be submitted at its default quantity (e.g. the plan's base price). True when the user picks the quantity within min_quantity/max_quantity.
            - `currency_amounts` CatalogCurrencyAmount[]: The whole Stripe price in each currency it supports (the fields above stay in the price's main currency).
              - …
        - `kind` 'one_off_tokens'
      - CatalogPlanSubscription
        - `tier_id` string, required
        - `display_name` string, required: Human-readable plan name for frontend display.
        - `subtitle` string: Optional short subtitle/description displayed under the plan name.
        - `cta_text` string: Optional call-to-action label shown on the plan button.
        - `highlights` CatalogHighlight[]: Up to two compact highlights for frontend display (number + text).
          - `number` number, nullable: Optional numeric value to display prominently.
          - `stripe_price_id` string, nullable: Optional Stripe price id used by UI when refreshing highlight values.
          - `text` string, required: Label displayed under/next to the number.
        - `features` CatalogFeature[]: Human-readable feature bullets for this plan (frontend display).
          - `text` string, required: User-facing feature/highlight text.
          - `icon_key` string, nullable: Optional semantic icon key that frontend maps to an icon.
        - `enabled` boolean
        - `currencies` string[]: Lowercase currencies every price of this plan can be charged in; valid values for the checkout `currency` parameter.
        - `default_items` PlanLineItem[], required: Suggested default cart rows (empty list when not applicable).
          - `price_id` string, required
          - `quantity` integer, required: Default quantity for this price.
          - `quantity_step` integer, required: Checkout quantity step for this item.
          - `units_per_quantity` number: Multiplier to convert checkout quantity into displayed units for this item.
        - `pricing` PlanPricing, required: Pricing-only blob for Rust ``pricing_preview_json`` (``lines`` only). Default starter quantities live on the plan as ``default_items``.
          - `lines` CatalogPricingLine[], required: Priced Stripe lines (one for typical one-off; two for subscription).
            - `stripe_price_id` string, required
            - `display_name` string: Human-readable label for this Stripe price line (frontend display).
            - `unit_amount_cents` number: Effective unit price in cents per displayed unit (e.g. per token). For Stripe prices configured per pack/group, this is normalized using Stripe transform quantity metadata.
            - `min_quantity` integer, nullable: Checkout minimum quantity for this price (one-off packs).
            - `max_quantity` integer, nullable: Checkout maximum quantity for this price (one-off packs).
            - `tier_pricing_from_stripe` boolean: If true, replace this price line with tier bands fetched from Stripe (subscription only).
            - `tiers_mode` 'graduated' | 'volume', nullable: For Stripe tiered prices: `graduated` vs `volume` (Stripe Price `tiers_mode`). Set on each band when `tier_pricing_from_stripe` lines are expanded from Stripe.
            - `user_can_modify_at_checkout` boolean: False when the line is fixed: it must be submitted at its default quantity (e.g. the plan's base price). True when the user picks the quantity within min_quantity/max_quantity.
            - `currency_amounts` CatalogCurrencyAmount[]: The whole Stripe price in each currency it supports (the fields above stay in the price's main currency).
              - …
        - `kind` 'subscription'
        - `tier` 'basic' | 'pro' | 'expert' | 'enterprise_user': Named subscription offer; subscriptions that predate tiers read as basic. ``enterprise_user`` is granted by hand outside Stripe (see :mod:`tellers_common.enterprise_user_subscription`) and ranks above every paid tier.
        - `legacy_price_ids` string[]: Retired Stripe prices that existing subscribers on this plan are still billed on.
        - `interval` 'month' | 'year', nullable
        - `interval_upgrade_cta` string: Optional call-to-action label for switching subscription interval, e.g. monthly to yearly.
        - `quantity_update_cta` string: Optional call-to-action label for changing subscription item quantities.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/tellers/apis/tellers-api.md) - [All operations](https://skmtc.dev/tellers/apis/tellers-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tellers/apis/tellers-api/revisions/fdaa0fa44a26?raw)