Invoices API — retrieve legally compliant invoices

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

Value	Description
`draft`	Invoice is being assembled and has not been finalized.
`open`	Invoice has been finalized and is awaiting payment.
`paid`	Invoice has been paid in full.
`void`	Invoice has been voided and is no longer collectible.
`uncollectible`	Payment 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

number

Maximum number of invoices to return per page.

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

object[]

required

Array of invoice objects.

Show invoice fields

string

required

Unique invoice identifier.

string

required

ID of the associated customer.

string

ID of the associated subscription, if applicable.

string

required

Current invoice status.

number

required

Total amount due on this invoice.

number

required

Amount that has been paid.

string

required

Three-letter ISO 4217 currency code.

string

required

ISO 8601 timestamp for the start of the billing period.

string

required

ISO 8601 timestamp for the end of the billing period.

string

required

ISO 8601 timestamp of when the invoice was created.

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

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

string

required

Unique invoice identifier.

string

required

ID of the associated customer.

string

ID of the associated subscription, if applicable.

string

required

Current invoice status. One of draft, open, paid, void, or uncollectible.

number

required

Total amount due on this invoice.

number

required

Amount that has been paid.

string

required

Three-letter ISO 4217 currency code.

object[]

required

Array of line items on the invoice.

Show line item fields

string

required

Unique line item identifier.

string

required

Description of the line item.

number

required

Amount for this line item.

number

required

Quantity billed.

string

required

Three-letter ISO 4217 currency code.

string

Start of the period this line item covers.

string

End of the period this line item covers.

string

required

ISO 8601 timestamp for the start of the billing period.

string

required

ISO 8601 timestamp for the end of the billing period.

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

string

required

The ID of the customer to attach this item to.

number

required

Amount for this item.

string

required

Description of the item. Appears on the invoice line.

string

ID of the subscription to associate this item with. If provided, the item will be included on the next invoice for that subscription.

string

Three-letter ISO 4217 currency code. Defaults to the customer’s currency.

number

Quantity of the item. Minimum value is 1. Defaults to 1.

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

string

required

Unique identifier for the invoice item (e.g. ii_xxx).

string

required

ID of the associated customer.

string

ID of the associated subscription, if provided.

number

required

Amount for this item.

string

required

Three-letter ISO 4217 currency code.

string

required

Item description.

number

required

Quantity billed.

object

Key-value pairs attached to the item.

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

string

Filter by customer ID.

string

Filter by subscription ID.

boolean

When true, returns only items not yet attached to an invoice.

string

Cursor for pagination. Pass the id of the last item from the previous page.

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

object[]

required

Array of invoice item objects.

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

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

Overview

Payments

Subscriptions

Billing

Configuration

Invoices API — retrieve legally compliant invoices

List invoices

Query parameters

Response fields

Retrieve an invoice

Path parameters

Response fields

Create an invoice item

Request parameters

Response fields

List invoice items

Query parameters

Response fields

Retrieve an invoice item

Path parameters

Response fields

​List invoices

​Query parameters

​Response fields

​Retrieve an invoice

​Path parameters

​Response fields

​Create an invoice item

​Request parameters

​Response fields

​List invoice items

​Query parameters

​Response fields

​Retrieve an invoice item

​Path parameters

​Response fields

List invoices

Query parameters

Response fields

Retrieve an invoice

Path parameters

Response fields

Create an invoice item

Request parameters

Response fields

List invoice items

Query parameters

Response fields

Retrieve an invoice item

Path parameters

Response fields