> ## 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.

# Invoices API — retrieve legally compliant invoices

> Retrieve invoices that Borga auto-generates for each payment or billing cycle. Filter by status, inspect line items, and manage pending invoice items.

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.

<Note>
  Invoices are created automatically by Borga when a payment is collected or a subscription billing cycle closes. You cannot create invoices via the API.
</Note>

**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

<ParamField query="limit" type="number">
  Maximum number of invoices to return per page.
</ParamField>

<ParamField query="status" type="string">
  Filter by invoice status. One of `draft`, `open`, `paid`, `void`, or `uncollectible`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
  ```
</RequestExample>

### Response fields

<ResponseField name="data" type="object[]" required>
  Array of invoice objects.

  <Expandable title="invoice fields">
    <ResponseField name="id" type="string" required>
      Unique invoice identifier.
    </ResponseField>

    <ResponseField name="customer" type="string" required>
      ID of the associated customer.
    </ResponseField>

    <ResponseField name="subscription" type="string">
      ID of the associated subscription, if applicable.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Current invoice status.
    </ResponseField>

    <ResponseField name="amount_due" type="number" required>
      Total amount due on this invoice.
    </ResponseField>

    <ResponseField name="amount_paid" type="number" required>
      Amount that has been paid.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Three-letter ISO 4217 currency code.
    </ResponseField>

    <ResponseField name="period_start" type="string" required>
      ISO 8601 timestamp for the start of the billing period.
    </ResponseField>

    <ResponseField name="period_end" type="string" required>
      ISO 8601 timestamp for the end of the billing period.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 timestamp of when the invoice was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  Whether more invoices exist beyond this page.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
  }
  ```
</ResponseExample>

***

## Retrieve an invoice

`GET /v1/invoices/{id}`

Retrieves the details of an existing invoice, including all line items.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the invoice to retrieve.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.borga.is/v1/invoices/inv_01hx9z3k2mfq7nbvd4cw8ej5rt \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

<ResponseField name="id" type="string" required>
  Unique invoice identifier.
</ResponseField>

<ResponseField name="customer" type="string" required>
  ID of the associated customer.
</ResponseField>

<ResponseField name="subscription" type="string">
  ID of the associated subscription, if applicable.
</ResponseField>

<ResponseField name="status" type="string" required>
  Current invoice status. One of `draft`, `open`, `paid`, `void`, or `uncollectible`.
</ResponseField>

<ResponseField name="amount_due" type="number" required>
  Total amount due on this invoice.
</ResponseField>

<ResponseField name="amount_paid" type="number" required>
  Amount that has been paid.
</ResponseField>

<ResponseField name="currency" type="string" required>
  Three-letter ISO 4217 currency code.
</ResponseField>

<ResponseField name="lines" type="object[]" required>
  Array of line items on the invoice.

  <Expandable title="line item fields">
    <ResponseField name="id" type="string" required>
      Unique line item identifier.
    </ResponseField>

    <ResponseField name="description" type="string" required>
      Description of the line item.
    </ResponseField>

    <ResponseField name="amount" type="number" required>
      Amount for this line item.
    </ResponseField>

    <ResponseField name="quantity" type="number" required>
      Quantity billed.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Three-letter ISO 4217 currency code.
    </ResponseField>

    <ResponseField name="period_start" type="string">
      Start of the period this line item covers.
    </ResponseField>

    <ResponseField name="period_end" type="string">
      End of the period this line item covers.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="period_start" type="string" required>
  ISO 8601 timestamp for the start of the billing period.
</ResponseField>

<ResponseField name="period_end" type="string" required>
  ISO 8601 timestamp for the end of the billing period.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the invoice was created.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

***

## 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

<ParamField body="customer" type="string" required>
  The ID of the customer to attach this item to.
</ParamField>

<ParamField body="amount" type="number" required>
  Amount for this item.
</ParamField>

<ParamField body="description" type="string" required>
  Description of the item. Appears on the invoice line.
</ParamField>

<ParamField body="subscription" type="string">
  ID of the subscription to associate this item with. If provided, the item will be included on the next invoice for that subscription.
</ParamField>

<ParamField body="currency" type="string">
  Three-letter ISO 4217 currency code. Defaults to the customer's currency.
</ParamField>

<ParamField body="quantity" type="number">
  Quantity of the item. Minimum value is `1`. Defaults to `1`.
</ParamField>

<ParamField body="metadata" type="object">
  Set of key-value pairs you can attach to this item. Values must be strings.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
    }'
  ```
</RequestExample>

### Response fields

<ResponseField name="id" type="string" required>
  Unique identifier for the invoice item (e.g. `ii_xxx`).
</ResponseField>

<ResponseField name="customer" type="string" required>
  ID of the associated customer.
</ResponseField>

<ResponseField name="subscription" type="string">
  ID of the associated subscription, if provided.
</ResponseField>

<ResponseField name="amount" type="number" required>
  Amount for this item.
</ResponseField>

<ResponseField name="currency" type="string" required>
  Three-letter ISO 4217 currency code.
</ResponseField>

<ResponseField name="description" type="string" required>
  Item description.
</ResponseField>

<ResponseField name="quantity" type="number" required>
  Quantity billed.
</ResponseField>

<ResponseField name="metadata" type="object">
  Key-value pairs attached to the item.
</ResponseField>

<ResponseField name="created_at" type="string" required>
  ISO 8601 timestamp of when the item was created.
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

***

## List invoice items

`GET /v1/invoice_items`

Returns a paginated list of invoice items, ordered by creation date descending.

### Query parameters

<ParamField query="customer" type="string">
  Filter by customer ID.
</ParamField>

<ParamField query="subscription" type="string">
  Filter by subscription ID.
</ParamField>

<ParamField query="pending" type="boolean">
  When `true`, returns only items not yet attached to an invoice.
</ParamField>

<ParamField query="starting_after" type="string">
  Cursor for pagination. Pass the `id` of the last item from the previous page.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of items to return per page.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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"
  ```
</RequestExample>

### Response fields

<ResponseField name="data" type="object[]" required>
  Array of invoice item objects.
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  Whether more items exist beyond this page.
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
  }
  ```
</ResponseExample>

***

## Retrieve an invoice item

`GET /v1/invoice_items/{id}`

Retrieves the details of an existing invoice item.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the invoice item to retrieve.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.borga.is/v1/invoice_items/ii_01hx9z3k2mfq7nbvd4cw8ej5rt \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

### Response fields

Returns an invoice item object. See [create an invoice item](#create-an-invoice-item) for the full field reference.

<ResponseExample>
  ```json 200 theme={null}
  {
    "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"
  }
  ```
</ResponseExample>