v1

latestOpenAPI 3.1.02026-08-042453938.9 KB

Pricing Plans

Create a pricing plan

Create a new pricing plan for a usage type.

Requires a secret key (sk_*) with the ADMIN role. Public keys and lower-role secret keys will receive 403 Forbidden.

Each unitType can only have one active pricing plan. If you need to change prices, update the existing plan or deactivate it first.

Example unit types:

api_call - Per API request
token - Per token processed
compute_second - Per second of compute
gb_storage - Per GB stored

post/v1/pricing-plans

Request body

namestring required

Human-readable name for the plan (required)

unitTypestring required

The usage type to price. Must be unique per business. Examples: "api_call", "token", "compute_second", "gb_storage"

unitPriceUsdnumber required

Default (FLAT) price per unit in USD. Required even for tiered plans as a fallback.

unitPricenumber

Native-currency price per unit. Required when currency is non-USD/USDC. The billing engine uses this as the source of truth and converts to USD via FxRate at charge time.

currency'USD' | 'USDC' | 'EUR' | 'GBP' | 'JPY' | 'CAD' | 'AUD' | 'CHF' | 'SGD' | 'HKD' | 'ILS' | 'NZD' | 'SEK' | 'NOK' | 'DKK' | 'MXN' | 'BRL' | 'INR' | 'ZAR' | 'PLN'

Billing currency for the plan (default: USD). Non-USD plans require unitPrice.

isActiveboolean

Whether to activate the plan immediately (default: true)

pricingModel'FLAT' | 'TIERED' | 'VOLUME' | 'PACKAGE' | 'PER_SEAT'

How quantity maps to charge amount (default: FLAT)

creditsPerUnitnumber

Credits consumed per unit of usage. When set, usage is deducted from the customer's credit wallet instead of charging USD.

productCategoryIdstring

Optional product category id. When Business.strictProducts is true, either this or productCategoryKey is required.

productCategoryKeystring

Optional product category slug (e.g. 'core_api'). Resolved server-side to the matching id. Mutually exclusive with productCategoryId.

Example request

{
  "name": "API Calls",
  "unitType": "api_call",
  "unitPriceUsd": 0.001,
  "unitPrice": 0.0037,
  "currency": "USD",
  "isActive": true,
  "pricingModel": "FLAT",
  "creditsPerUnit": 10,
  "productCategoryId": "cat_core",
  "productCategoryKey": "core_api"
}

Response

Pricing plan created

idstring required

Unique identifier for the pricing plan

businessIdstring

Business this plan belongs to

namestring required

Human-readable name for the plan

unitTypestring required

The usage type this plan prices (e.g., "api_call", "token", "compute_second", "gb_storage")

unitPriceUsdstring required

Default (FLAT) price per unit in USD. For TIERED/VOLUME/PACKAGE plans, consult tiers. For PER_SEAT plans, this is the price per seat per billing period.

unitPricestring nullable

Native-currency price per unit. Populated only for non-USD plans (e.g. EUR, ILS). When set, this is the source of truth: the billing engine reads it directly and converts to USD via FxRate at charge time.

currency'USD' | 'USDC' | 'EUR' | 'GBP' | 'JPY' | 'CAD' | 'AUD' | 'CHF' | 'SGD' | 'HKD' | 'ILS' | 'NZD' | 'SEK' | 'NOK' | 'DKK' | 'MXN' | 'BRL' | 'INR' | 'ZAR' | 'PLN'

Billing currency for the plan. Defaults to USD. For non-USD currencies, supply unitPrice (and tier unitPrice/flatFee); the billing engine uses those as the source of truth and converts to USD via FxRate at charge time.

pricingModel'FLAT' | 'TIERED' | 'VOLUME' | 'PACKAGE' | 'PER_SEAT' required

How quantity maps to charge amount:

FLAT: quantity × unitPrice (default)
TIERED: graduated, first N at price A, next M at price B, etc.
VOLUME: total quantity determines a single rate applied to all units
PACKAGE: charge per package of N units (rounds up partial packages)
PER_SEAT: per-seat/user licensing. quantity is the seat count, charged at unitPrice per seat per billing period (no tiers)

creditsPerUnitstring nullable

Credits consumed per unit of usage. When set, usage is deducted from the customer's credit wallet instead of charging USD.

productCategoryIdstring nullable

Optional product category tag used by 'strict products' mode to roll up reporting by service line. Null when the plan is untagged. When Business.strictProducts is true, this must be populated via the category id or key.

isActiveboolean required

Whether this plan is active. Only active plans are used for new charges.

createdAtstring date-time

When the plan was created

updatedAtstring date-time

When the plan was last updated

Example response

{
  "id": "plan_abc123def456",
  "businessId": "biz_789xyz",
  "name": "API Calls",
  "unitType": "api_call",
  "unitPriceUsd": "0.001000",
  "unitPrice": "0.000920",
  "currency": "USD",
  "pricingModel": "FLAT",
  "tiers": [
    {
      "minQuantity": "0",
      "maxQuantity": "1000",
      "unitPriceUsd": "0.001000",
      "unitPrice": "0.000920",
      "packageSize": 1000
    }
  ],
  "creditsPerUnit": "10",
  "productCategoryId": "cat_core",
  "isActive": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}