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.

Subscriptions let you bill customers on a repeating schedule without writing any scheduling logic yourself. You define the products and prices once, attach them to a subscription, and Borga handles billing on every renewal cycle — generating invoices, collecting payment, and handling proration when plans change mid-cycle.

​
Data model

Borga’s billing model follows a hierarchy from product catalogue down to the individual subscription:
LayerWhat it represents
ProductWhat you sell, e.g. “Pro Plan” or “SMS credits”.
PriceHow you charge for the product — amount, currency, and billing interval.
Subscription itemA price attached to a specific subscription, with an optional quantity.
SubscriptionThe recurring billing agreement for a customer, containing one or more items.
InvoiceThe legally compliant Icelandic invoice generated at each billing cycle.
A single subscription can contain multiple items, each referencing a different price. This lets you bundle base plans with add-ons in one billing agreement.

​
Billing intervals

Billing intervals are defined on the Price object. Borga supports the following recurring intervals:
IntervalUse case
dayDaily billing — useful for short trials or metered pay-as-you-go.
weekWeekly billing.
monthMost common. Monthly SaaS, monthly membership.
yearAnnual billing, typically at a discount.

​
Collection methods

When you create a subscription, you choose how Borga collects payment at each billing cycle:
Borga charges the customer’s default saved payment method on the renewal date. The customer does not need to take any action.Best for: SaaS products, recurring services where the customer expects seamless billing.
{
  "customer": "cus_01HXYZ",
  "collection_method": "charge_automatically",
  "items": [{ "price": "price_01HXYZ" }]
}
To use charge_automatically, the customer must have a default payment method saved. Set one with POST /v1/payment_methods/{id}/set_default before creating the subscription.

​
Trials

Give new subscribers a free trial period by setting trial_period_days on the subscription. Borga does not charge the customer until the trial ends. 
{
  "customer": "cus_01HXYZ",
  "collection_method": "charge_automatically",
  "trial_period_days": 14,
  "items": [{ "price": "price_01HXYZ" }]
}
During the trial, the subscription status is trialing. The first invoice is issued when the trial period ends.

​
Proration

When you add, remove, or change a subscription item mid-billing cycle, Borga calculates a proration — a credit or charge for the partial period. You control this with proration_behavior when updating subscription items:
ValueBehaviour
create_prorationsAdd proration line items to the next invoice. No immediate charge.
always_invoiceGenerate and immediately finalize a prorated invoice for the difference.
noneMake the change without any proration. The customer is billed at full price from the next cycle.
Use always_invoice when a customer upgrades to a higher-tier plan mid-cycle and you want to collect the difference immediately rather than rolling it into the next invoice.

​
Discounts

Apply a one-time discount to a subscription at creation using the discount field: 
{
  "customer": "cus_01HXYZ",
  "items": [{ "price": "price_01HXYZ" }],
  "discount": {
    "percent_off": 20,
    "duration": "once"
  }
}
The duration field currently only supports "once", meaning the discount applies to the first invoice only. Subsequent invoices are billed at the standard price.

​
Subscription lifecycle

A subscription passes through the following states:
StatusMeaning
trialingThe subscription is within its trial period. No charges yet.
activeThe subscription is billing normally.
past_dueThe latest invoice is unpaid past its due date.
pausedBilling is suspended. No invoices are generated.
cancelingA cancellation is scheduled for the end of the current period.
canceledThe subscription has ended. No further invoices will be generated.

​
Managing subscription state

Send POST /v1/subscriptions/{id}/cancel. Set at_period_end: true to let the current billing period complete before canceling, or false to cancel immediately.
{ "at_period_end": true }
An at_period_end cancellation moves the subscription to canceling status. Call POST /v1/subscriptions/{id}/uncancel to reverse it before the period ends.
POST /v1/subscriptions/{id}/pause — stops invoicing without ending the subscription. The status moves to paused.POST /v1/subscriptions/{id}/resume — resumes billing from the next scheduled cycle.

​
Credit rollover

For usage-based or credit-based plans, you can configure subscription items with included units and credit rollover:
FieldDescription
included_unitsThe number of units included in the base price each billing period.
credit_rolloverIf true, unused units from the current period carry over to the next period rather than expiring.
{
  "customer": "cus_01HXYZ",
  "items": [
    {
      "price": "price_01HXYZ",
      "included_units": 100,
      "credit_rollover": true
    }
  ]
}
Credit rollover applies per subscription item, not per subscription. Items on the same subscription can have different rollover settings.