Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.borga.is/llms.txt

Use this file to discover all available pages before exploring further.

A price defines how much and how often you charge for a product. Each price belongs to a product and specifies a type of either one_time or recurring. Recurring prices support flexible intervals, tiered pricing structures, and metered usage billing. Once a price is created, its core monetary fields are immutable — create a new price if you need to change the amount.

​
Create a price

POST /v1/prices Creates a new price for an existing product.

​
Request parameters

​
product
string
required
The ID of the product this price belongs to (e.g. prod_xxx).
​
currency
string
Three-letter ISO 4217 currency code (e.g. ISK, EUR, USD). Defaults to the merchant’s default currency.
​
type
string
required
Pricing type. One of one_time or recurring.
​
unit_amount
number
Price per unit in the currency’s smallest unit. Minimum value is 0. Required when tiers_mode is not set.
​
recurring
object
Required when type is recurring. Defines the billing interval.
​
tiers_mode
string
Enables tiered pricing. One of graduated (each tier applies to usage within that range) or volume (the tier price applies to the entire quantity based on total usage).
​
tiers
object[]
Array of tier objects. Required when tiers_mode is set.
​
meter
string
ID of the meter to use for metered usage billing. Required when recurring.usage_type is metered.
​
included_units
number
Number of units included in the base price before metered usage billing begins.
​
accounting_code
string
GL account code to associate with this price for accounting export.
​
metadata
object
Set of key-value pairs you can attach to the price. Values must be strings.
curl --request POST \
  --url https://api.borga.is/v1/prices \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "product": "prod_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "currency": "ISK",
    "type": "one_time",
    "unit_amount": 9900,
    "accounting_code": "4000"
  }'

​
Response fields

​
id
string
required
Unique identifier for the price (e.g. price_xxx).
​
product
string
required
ID of the associated product.
​
currency
string
required
Three-letter ISO 4217 currency code.
​
type
string
required
Pricing type. One of one_time or recurring.
​
unit_amount
number
Price per unit. null when tiers_mode is set.
​
recurring
object
Recurring billing configuration. null for one-time prices.
​
tiers_mode
string
Tier mode: graduated or volume. null if not using tiered pricing.
​
tiers
object[]
Array of tier configuration objects. null if not using tiered pricing.
​
meter
string
ID of the associated meter, if applicable.
​
active
boolean
required
Whether the price is currently active.
​
metadata
object
Key-value pairs attached to the price.
{
  "id": "price_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "product": "prod_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "currency": "ISK",
  "type": "recurring",
  "unit_amount": 4990,
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "usage_type": "licensed",
    "aggregate_usage": null
  },
  "tiers_mode": null,
  "tiers": null,
  "meter": null,
  "active": true,
  "metadata": {},
  "created_at": "2026-04-29T10:15:00Z"
}

​
List prices

GET /v1/prices Returns a paginated list of prices, ordered by creation date descending.

​
Query parameters

​
product
string
Filter prices by product ID.
​
starting_after
string
Cursor for pagination. Pass the id of the last price from the previous page to retrieve the next page.
​
limit
number
Maximum number of prices to return per page.
curl --request GET \
  --url "https://api.borga.is/v1/prices?product=prod_01hx9z3k2mfq7nbvd4cw8ej5rt&limit=20" \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Response fields

​
data
object[]
required
Array of price objects.
​
has_more
boolean
required
Whether more prices exist beyond this page.
{
  "data": [
    {
      "id": "price_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "product": "prod_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "currency": "ISK",
      "type": "recurring",
      "unit_amount": 4990,
      "recurring": {
        "interval": "month",
        "interval_count": 1,
        "usage_type": "licensed",
        "aggregate_usage": null
      },
      "active": true,
      "metadata": {}
    }
  ],
  "has_more": false
}

​
Retrieve a price

GET /v1/prices/{id} Retrieves the details of an existing price.

​
Path parameters

​
id
string
required
The ID of the price to retrieve.
curl --request GET \
  --url https://api.borga.is/v1/prices/price_01hx9z3k2mfq7nbvd4cw8ej5rt \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Response fields

Returns a price object. See create a price for the full field reference. 
{
  "id": "price_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "product": "prod_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "currency": "ISK",
  "type": "recurring",
  "unit_amount": 4990,
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "usage_type": "licensed",
    "aggregate_usage": null
  },
  "tiers_mode": null,
  "tiers": null,
  "meter": null,
  "active": true,
  "metadata": {},
  "created_at": "2026-04-29T10:15:00Z"
}

​
Update a price

PATCH /v1/prices/{id} Updates a price. Only active, accounting_code, and metadata can be modified after creation. To change the amount, currency, or interval, create a new price.

​
Path parameters

​
id
string
required
The ID of the price to update.

​
Request parameters

​
active
boolean
Set to false to deactivate this price. Deactivating does not affect subscriptions already using it.
​
accounting_code
string
Updated GL account code.
​
metadata
object
Updated metadata. Replaces the existing metadata object entirely.
curl --request PATCH \
  --url https://api.borga.is/v1/prices/price_01hx9z3k2mfq7nbvd4cw8ej5rt \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "active": false,
    "accounting_code": "4001"
  }'

​
Response fields

Returns the updated price object. See retrieve a price for the full field reference. 
{
  "id": "price_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "product": "prod_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "currency": "ISK",
  "type": "recurring",
  "unit_amount": 4990,
  "recurring": {
    "interval": "month",
    "interval_count": 1,
    "usage_type": "licensed",
    "aggregate_usage": null
  },
  "tiers_mode": null,
  "tiers": null,
  "meter": null,
  "active": false,
  "metadata": {},
  "created_at": "2026-04-29T10:15:00Z"
}