Recurring billing with Borga subscriptions

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:

Layer	What it represents
Product	What you sell, e.g. “Pro Plan” or “SMS credits”.
Price	How you charge for the product — amount, currency, and billing interval.
Subscription item	A price attached to a specific subscription, with an optional quantity.
Subscription	The recurring billing agreement for a customer, containing one or more items.
Invoice	The 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:

Interval	Use case
`day`	Daily billing — useful for short trials or metered pay-as-you-go.
`week`	Weekly billing.
`month`	Most common. Monthly SaaS, monthly membership.
`year`	Annual billing, typically at a discount.

Collection methods

When you create a subscription, you choose how Borga collects payment at each billing cycle:

charge_automatically
send_invoice

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" }]
}

Borga generates an invoice and emails it to the customer. The customer pays at their convenience before the due date, which you set with days_until_due.Best for: B2B invoicing where payment terms apply, or customers who prefer bank transfer.

{
  "customer": "cus_01HXYZ",
  "collection_method": "send_invoice",
  "days_until_due": 30,
  "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:

Value	Behaviour
`create_prorations`	Add proration line items to the next invoice. No immediate charge.
`always_invoice`	Generate and immediately finalize a prorated invoice for the difference.
`none`	Make 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"
  }
}

{
  "customer": "cus_01HXYZ",
  "items": [{ "price": "price_01HXYZ" }],
  "discount": {
    "amount_off": 1000,
    "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:

Status	Meaning
`trialing`	The subscription is within its trial period. No charges yet.
`active`	The subscription is billing normally.
`past_due`	The latest invoice is unpaid past its due date.
`paused`	Billing is suspended. No invoices are generated.
`canceling`	A cancellation is scheduled for the end of the current period.
`canceled`	The subscription has ended. No further invoices will be generated.

Managing subscription state

Cancel a subscription

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.

Pause and resume

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:

Field	Description
`included_units`	The number of units included in the base price each billing period.
`credit_rollover`	If `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.

Get Started

Core Concepts

Guides

Recurring billing with Borga subscriptions

Data model

Billing intervals

Collection methods

Trials

Proration

Discounts

Subscription lifecycle

Managing subscription state

Credit rollover

​Data model

​Billing intervals

​Collection methods

​Trials

​Proration

​Discounts

​Subscription lifecycle

​Managing subscription state

​Credit rollover

Data model

Billing intervals

Collection methods

Trials

Proration

Discounts

Subscription lifecycle

Managing subscription state

Credit rollover