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 subscription item represents a single price on a subscription. Each item links a price to the subscription and tracks its quantity and billing settings. You can add, update, or remove items at any time — proration ensures the customer is charged or credited fairly for changes mid-cycle.
When you add a new item or change an existing item’s quantity mid-billing-cycle, Borga can automatically create proration invoice items. These adjust the customer’s next invoice to account for the partial period already used. Control this behavior with the proration_behavior parameter.

​
Add a subscription item

POST /v1/subscription_items Adds a new item to an existing subscription.

​
Request parameters

​
subscription
string
required
ID of the subscription to add this item to.
​
price
string
required
ID of the price to bill on this item.
​
quantity
number
Quantity of the price to bill. Defaults to 1.
​
proration_behavior
string
How to handle proration when adding this item mid-cycle. One of:
  • create_prorations — Create proration invoice items to adjust the next invoice.
  • always_invoice — Create proration invoice items and immediately invoice the customer.
  • none — Do not create any proration items.
​
credit_rollover
boolean
When true, unused credits from the current period roll over to the next period.
​
included_units
number
Number of units included in the base price before metered charges apply.
​
metadata
object
Key-value pairs to attach to this item. Values must be strings.
curl --request POST \
  --url https://api.borga.is/v1/subscription_items \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "subscription": "sub_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "price": "pri_addon_storage",
    "quantity": 2,
    "proration_behavior": "create_prorations",
    "metadata": {
      "add_on": "storage"
    }
  }'

​
Response fields

​
id
string
required
Unique identifier for the subscription item (e.g. si_xxx).
​
subscription
string
required
ID of the subscription this item belongs to.
​
price
string
required
ID of the price being billed.
​
quantity
number
required
Quantity being billed.
​
credit_rollover
boolean
Whether unused credits roll over to the next period.
​
included_units
number
Units included in the base price before metered charges apply.
​
metadata
object
Key-value pairs attached to this item.
{
  "id": "si_01hx9z3k2mfq7nbvd4cw8ej002",
  "subscription": "sub_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "price": "pri_addon_storage",
  "quantity": 2,
  "credit_rollover": false,
  "included_units": null,
  "metadata": {
    "add_on": "storage"
  }
}

​
Retrieve a subscription item

GET /v1/subscription_items/{id} Retrieves the details of a single subscription item.

​
Path parameters

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

​
Update a subscription item

POST /v1/subscription_items/{id} Updates an existing subscription item. Only the fields you include are changed.

​
Path parameters

​
id
string
required
The ID of the subscription item to update.

​
Request parameters

​
quantity
number
New quantity to bill.
​
proration_behavior
string
How to handle proration for this change. One of create_prorations, always_invoice, or none.
​
credit_rollover
boolean
Whether unused credits roll over to the next period.
​
included_units
number
Units included in the base price before metered charges apply.
​
metadata
object
Replace the item’s metadata. Pass null values to remove specific keys.
curl --request POST \
  --url https://api.borga.is/v1/subscription_items/si_01hx9z3k2mfq7nbvd4cw8ej002 \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "quantity": 5,
    "proration_behavior": "always_invoice"
  }'

​
Remove a subscription item

DELETE /v1/subscription_items/{id} Removes an item from a subscription. The item is deleted immediately.

​
Path parameters

​
id
string
required
The ID of the subscription item to remove.

​
Query parameters

​
proration_behavior
string
How to handle proration for the removal. One of create_prorations, always_invoice, or none. Defaults to none.
curl --request DELETE \
  --url "https://api.borga.is/v1/subscription_items/si_01hx9z3k2mfq7nbvd4cw8ej002?proration_behavior=create_prorations" \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"