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.

Borga automatically generates an invoice for every payment and subscription billing cycle. Invoices are legally compliant documents that include customer details, VAT, and line items. You can retrieve and filter invoices through the API, but you do not create them directly.
Invoices are created automatically by Borga when a payment is collected or a subscription billing cycle closes. You cannot create invoices via the API.
Invoice statuses
ValueDescription
draftInvoice is being assembled and has not been finalized.
openInvoice has been finalized and is awaiting payment.
paidInvoice has been paid in full.
voidInvoice has been voided and is no longer collectible.
uncollectiblePayment attempts have failed and the invoice is marked as uncollectible.

​
List invoices

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

​
Query parameters

​
limit
number
Maximum number of invoices to return per page.
​
status
string
Filter by invoice status. One of draft, open, paid, void, or uncollectible.
curl --request GET \
  --url "https://api.borga.is/v1/invoices?status=paid&limit=20" \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Response fields

​
data
object[]
required
Array of invoice objects.
​
has_more
boolean
required
Whether more invoices exist beyond this page.
{
  "data": [
    {
      "id": "inv_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "customer": "cus_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "subscription": "sub_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "status": "paid",
      "amount_due": 4990,
      "amount_paid": 4990,
      "currency": "ISK",
      "period_start": "2026-04-01T00:00:00Z",
      "period_end": "2026-04-30T23:59:59Z",
      "created_at": "2026-04-29T10:15:00Z"
    }
  ],
  "has_more": false
}

​
Retrieve an invoice

GET /v1/invoices/{id} Retrieves the details of an existing invoice, including all line items.

​
Path parameters

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

​
Response fields

​
id
string
required
Unique invoice identifier.
​
customer
string
required
ID of the associated customer.
​
subscription
string
ID of the associated subscription, if applicable.
​
status
string
required
Current invoice status. One of draft, open, paid, void, or uncollectible.
​
amount_due
number
required
Total amount due on this invoice.
​
amount_paid
number
required
Amount that has been paid.
​
currency
string
required
Three-letter ISO 4217 currency code.
​
lines
object[]
required
Array of line items on the invoice.
​
period_start
string
required
ISO 8601 timestamp for the start of the billing period.
​
period_end
string
required
ISO 8601 timestamp for the end of the billing period.
​
created_at
string
required
ISO 8601 timestamp of when the invoice was created.
{
  "id": "inv_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "customer": "cus_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "subscription": "sub_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "status": "paid",
  "amount_due": 4990,
  "amount_paid": 4990,
  "currency": "ISK",
  "lines": [
    {
      "id": "il_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "description": "Pro Plan — April 2026",
      "amount": 4990,
      "quantity": 1,
      "currency": "ISK",
      "period_start": "2026-04-01T00:00:00Z",
      "period_end": "2026-04-30T23:59:59Z"
    }
  ],
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-04-30T23:59:59Z",
  "created_at": "2026-04-29T10:15:00Z"
}

​
Create an invoice item

POST /v1/invoice_items Creates an invoice item that will be included on the next invoice generated for the customer. Use this to add one-off charges or adjustments to an upcoming invoice.

​
Request parameters

​
customer
string
required
The ID of the customer to attach this item to.
​
amount
number
required
Amount for this item.
​
description
string
required
Description of the item. Appears on the invoice line.
​
subscription
string
ID of the subscription to associate this item with. If provided, the item will be included on the next invoice for that subscription.
​
currency
string
Three-letter ISO 4217 currency code. Defaults to the customer’s currency.
​
quantity
number
Quantity of the item. Minimum value is 1. Defaults to 1.
​
metadata
object
Set of key-value pairs you can attach to this item. Values must be strings.
curl --request POST \
  --url https://api.borga.is/v1/invoice_items \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "customer": "cus_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "amount": 1990,
    "description": "Setup fee",
    "quantity": 1,
    "currency": "ISK"
  }'

​
Response fields

​
id
string
required
Unique identifier for the invoice item (e.g. ii_xxx).
​
customer
string
required
ID of the associated customer.
​
subscription
string
ID of the associated subscription, if provided.
​
amount
number
required
Amount for this item.
​
currency
string
required
Three-letter ISO 4217 currency code.
​
description
string
required
Item description.
​
quantity
number
required
Quantity billed.
​
metadata
object
Key-value pairs attached to the item.
​
created_at
string
required
ISO 8601 timestamp of when the item was created.
{
  "id": "ii_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "customer": "cus_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "subscription": null,
  "amount": 1990,
  "currency": "ISK",
  "description": "Setup fee",
  "quantity": 1,
  "metadata": {},
  "created_at": "2026-04-29T10:15:00Z"
}

​
List invoice items

GET /v1/invoice_items Returns a paginated list of invoice items, ordered by creation date descending.

​
Query parameters

​
customer
string
Filter by customer ID.
​
subscription
string
Filter by subscription ID.
​
pending
boolean
When true, returns only items not yet attached to an invoice.
​
starting_after
string
Cursor for pagination. Pass the id of the last item from the previous page.
​
limit
number
Maximum number of items to return per page.
curl --request GET \
  --url "https://api.borga.is/v1/invoice_items?customer=cus_01hx9z3k2mfq7nbvd4cw8ej5rt&pending=true" \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Response fields

​
data
object[]
required
Array of invoice item objects.
​
has_more
boolean
required
Whether more items exist beyond this page.
{
  "data": [
    {
      "id": "ii_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "customer": "cus_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "subscription": null,
      "amount": 1990,
      "currency": "ISK",
      "description": "Setup fee",
      "quantity": 1,
      "metadata": {},
      "created_at": "2026-04-29T10:15:00Z"
    }
  ],
  "has_more": false
}

​
Retrieve an invoice item

GET /v1/invoice_items/{id} Retrieves the details of an existing invoice item.

​
Path parameters

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

​
Response fields

Returns an invoice item object. See create an invoice item for the full field reference. 
{
  "id": "ii_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "customer": "cus_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "subscription": null,
  "amount": 1990,
  "currency": "ISK",
  "description": "Setup fee",
  "quantity": 1,
  "metadata": {},
  "created_at": "2026-04-29T10:15:00Z"
}