Prices
How much a product costs and how often it is billed. Prices are immutable apart from activation and metadata.
The price object
idstring
Prefixed
price_.productstring
activeboolean
currencystring
typeenum
one_time or recurring.unit_amountinteger | null
Per unit, in the smallest currency unit.
null for tiered prices.recurringobject | null
interval (day, week, month, year), interval_count, usage_type (licensed or metered), aggregate_usage.tiersarray | null
Tier objects with
up_to (number or null for the last tier), unit_amount, flat_amount.tiers_modeenum | null
graduated or volume.meterstring | null
Meter for metered prices.
included_unitsinteger | null
Free units per period for metered prices.
accounting_codestring | null
Revenue account code copied to invoice lines.
metadataobject
created_attimestamp
updated_attimestamp
Create a price
POST/v1/pricesSecret key
Body
productstringrequired
typeenumrequired
one_time or recurring.currencystringdefault: ISK
unit_amountinteger
Per unit. Omit when using tiers.
recurringobject
Required for recurring prices:
{ interval, interval_count?, usage_type?, aggregate_usage? }. interval is day, week, month or year.tiers_modeenum
graduated prices each band separately; volume prices everything at the reached band.tiersarray
[{ up_to, unit_amount?, flat_amount? }], ordered, last tier with up_to: null.meterstring
Required when
recurring.usage_type is metered.included_unitsinteger
Free units per period before tiers apply.
accounting_codestring
Copied to invoice lines for this price.
metadataobject
Fixedts
const product = await borga.products.create({
name: "Pro plan",
description: "Everything in Starter plus priority support",
});
const monthly = await borga.prices.create({
product: product.id,
type: "recurring",
currency: "ISK",
unit_amount: 4990, // 4.990 kr. per seat per month
recurring: { interval: "month", interval_count: 1 },
});
const yearly = await borga.prices.create({
product: product.id,
type: "recurring",
currency: "ISK",
unit_amount: 49900,
recurring: { interval: "year" },
});Meteredts
const price = await borga.prices.create({
product: "prod_4Gh6Ij8Kl0Mn2Op4Qr6St8Uv",
type: "recurring",
currency: "ISK",
recurring: { interval: "month", usage_type: "metered" },
meter: "mtr_1Zx3Cv5Bn7Mq9We1Rt3Yu5Io",
included_units: 10_000, // first 10k requests are free
tiers_mode: "graduated",
tiers: [
{ up_to: 100_000, unit_amount: 2 }, // 2 kr. per request
{ up_to: null, unit_amount: 1 }, // 1 kr. above 100k
],
});Response
{
"id": "price_2Ab4Cd6Ef8Gh0Ij2Kl4Mn6Op",
"product": "prod_4Gh6Ij8Kl0Mn2Op4Qr6St8Uv",
"active": true,
"currency": "ISK",
"type": "recurring",
"unit_amount": 4990,
"recurring": { "interval": "month", "interval_count": 1, "usage_type": "licensed" },
"tiers": null,
"tiers_mode": null,
"meter": null,
"included_units": null,
"accounting_code": null,
"metadata": {},
"created_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z"
}Errors: missing_meter, resource_not_found for product or meter.
Retrieve a price
GET/v1/prices/:idSecret key
Update a price
PATCH/v1/prices/:idSecret key
Amounts and intervals cannot change; create a new price and move subscriptions to it.
Body
activeboolean
Deactivate to stop new subscriptions using it.
accounting_codestring
Empty string clears it.
metadataobject
List prices
GET/v1/pricesSecret key
Query parameters
productstring
limitintegerdefault: 25
starting_afterstring