comecerodocs
Usage rate plans

Create a rate plan version

POST
/usage/rate_plans

Prices a metric. A saved version never changes: to change a price, save a new version with the same rate_plan_id. Tiers and package sizes price only the units above the included allowance. Secret and trusted tokens may call it; a limited token may not (403). The plan is not checked against an agreement's currency here: use a plan in the agreement's currency, or its billing run fails with currency_mismatch.

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Request Body

A rate plan version.

application/json
  1. body
rate_plan_id?string

Defaults to a new id. Send an existing id with a new version to change a price.

version?integer

Defaults to 1.

metric_id*string

Required.

currency*string

Required. Three letters.

pricing_model*string

Required.

Value in"flat_per_unit""package""tiered_volume""tiered_graduated"
included_allowance?number

Units included each period before anything is charged. When left out, the entitlement's capacity is used. At most 1,000,000,000,000.

overage_price?number

For flat_per_unit: the price per billable unit. For package: the price per package. At most 1,000,000.

tiers?array<>

Required for tiered_volume and tiered_graduated. Tiers count billable units, the units above included_allowance.

billing_region?string

Billing region. Defaults to us.

Value in"us""uk""eu"
package_size?number

Only for package: units in one package. Billable units are rounded up to whole packages. Defaults to 1.

effective_from?string

When the version was published. Defaults to now. Billing does not use it: an entitlement pins the exact version it is billed with.

Formatdate-time

Response Body

Success.

application/json
  1. response

The price of one metric in one currency. Each version is fixed once saved.

object?string

Always rate_plan.

rate_plan_id?string

Your id, or rate_ plus 32 characters.

version?integer

1 or more. Never changes once saved.

metric_id?string

The metric it prices.

currency?string

Three letters. Must be the currency of the agreements that use it.

pricing_model?string

How billable units are priced.

Value in"flat_per_unit""package""tiered_volume""tiered_graduated"
included_allowance?number

Units included in each period before any charge.

overage_price?number

Price per billable unit for flat_per_unit and package.

tiers?array<>

Required for the tiered models.

effective_from?string

Kept with the plan.

Formatdate-time
effective_to?string

Kept with the plan.

Formatdate-time
billing_region?string

Billing region. Defaults to us.

Value in"us""uk""eu"
test?boolean

Test or live.

Example Request
curl -X POST 'https://api.comecero.com/api/v1/usage/rate_plans' \  -H 'Content-Type: application/json' \  -d '{  "rate_plan_id": "ai_tokens_standard",  "version": 1,  "metric_id": "met_ai_tokens",  "currency": "USD",  "pricing_model": "flat_per_unit",  "included_allowance": 100000,  "overage_price": 0.00002}'
Example Response
{  "object": "rate_plan",  "rate_plan_id": "ai_tokens_standard",  "version": 1,  "metric_id": "met_ai_tokens",  "currency": "USD",  "pricing_model": "flat_per_unit",  "included_allowance": 100000,  "overage_price": 0.00002,  "tiers": [],  "billing_region": "us",  "test": false}

List rate plans GET

Every saved version of every rate plan, newest `effective_from` first, up to 500. There is no paging. Secret and trusted tokens may call it; a limited token may not (`403`).

Get a rate plan version GET

One version of a rate plan. Secret and trusted tokens may call it; a limited token may not (`403`).