Skip to main content

​
Catalog model

Ledger has three item types in each environment’s catalog. Your API key selects the environment; Sandbox and Live items are separate:
  • Features define the credit cost of an application action. A feature ID such as api_call is passed to check and track.
  • Plans grant a positive number of credits each month. A price of 0 defines a free plan that activates without Checkout; paid plans sync to the Stripe account connected to that environment.
  • Add-ons are one-time credit_pack purchases that grant a fixed number of credits after payment.
IDs use letters, numbers, _, and -, with a maximum length of 100 characters. Names are 1–120 characters. Credit amounts are positive integers. Prices are integer cents; add-on prices must be positive.

​
Create items independently

The dashboard has a form and list for each item under Catalog → Plans, Features, and Add-ons. The API creates each one with POST /v1/features, POST /v1/plans, or POST /v1/add-ons. Each response contains an item and changed: true. A duplicate active ID returns 409 already_exists.
For each resource, GET /v1/{resource} lists active items, GET /v1/{resource}/{id} reads one, PUT /v1/{resource}/{id} updates one, and DELETE /v1/{resource}/{id} archives one. The API reference includes cURL and labeled Python and TypeScript SDK source examples for every operation.

​
Update a plan

PUT /v1/plans/{id} requires the complete editable plan body. When price, allowance, or name changes, Ledger archives the current row and inserts a new version. Existing subscriptions keep their referenced version, while new Checkouts use the current version. An unchanged update returns changed: false. Paid versions report stripeSync as synced, pending, failed, or awaiting_connection.
Feature and add-on updates also use complete editable bodies but update their existing rows. Archiving hides an item from active lists and new purchases. Historical usage, subscriptions, and purchases remain visible.

​
Whole-catalog publishing

PUT /v1/catalog remains available for declarative sync from a config file. It replaces the desired active catalog: items omitted from its lists are archived. Use item APIs for dashboard onboarding and incremental setup so one creation does not affect unrelated items. The whole-catalog input requires at least one plan and one feature.