> ## 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.
# Recurring billing with Borga subscriptions
> Understand how Borga subscriptions work — products, prices, subscription items, billing intervals, trials, proration, discounts, and collection methods.
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:
```mermaid theme={null}
flowchart TD
A[Product] --> B[Price]
B --> C[Subscription item]
C --> D[Subscription]
D --> E[Invoice]
```
| 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:
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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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:
```json Percentage discount theme={null}
{
"customer": "cus_01HXYZ",
"items": [{ "price": "price_01HXYZ" }],
"discount": {
"percent_off": 20,
"duration": "once"
}
}
```
```json Fixed amount discount theme={null}
{
"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:
```mermaid theme={null}
flowchart LR
A[trialing] --> B[active]
B --> C[past_due]
B --> D[paused]
D --> B
B --> E[canceling]
E --> F[canceled]
C --> F
```
| 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
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.
```json theme={null}
{ "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:
| 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. |
```json theme={null}
{
"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.