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.

A customer represents a person or business you bill through Borga. Use POST /v1/customers to create a record, attach billing address and tax details, and then reference the customer id when creating subscriptions or payments.

​
Create a customer

POST /v1/customers Creates a new customer object.

​
Request parameters

​
email
string
required
Email address of the customer. Must be a valid email format.
​
name
string
Full name of the customer.
​
phone
string
Phone number of the customer.
​
kennitala
string
Icelandic national ID (kennitala). Ten-digit identifier used for individuals and legal entities in Iceland.
​
external_id
string
Your own identifier for this customer — an ID from your database or CRM. Stored as-is and returned in all responses.
​
vat_number
string
VAT registration number for the customer. Included on invoices when present.
​
metadata
object
Set of key-value pairs you can attach to the customer. Values must be strings.
​
billing_address_line1
string
Primary billing address line.
​
billing_address_line2
string
Secondary billing address line (apartment, suite, etc.).
​
billing_city
string
City for the billing address.
​
billing_postal_code
string
Postal code for the billing address.
​
billing_country
string
Two-letter ISO 3166-1 alpha-2 country code (e.g. IS, GB, DE).
curl --request POST \
  --url https://api.borga.is/v1/customers \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "sigrid@example.is",
    "name": "Sigríður Jónsdóttir",
    "phone": "+354 555 1234",
    "kennitala": "1234567890",
    "external_id": "usr_9982",
    "vat_number": "IS12345",
    "billing_address_line1": "Laugavegur 12",
    "billing_city": "Reykjavík",
    "billing_postal_code": "101",
    "billing_country": "IS",
    "metadata": {
      "plan": "enterprise"
    }
  }'

​
Response fields

​
id
string
required
Unique identifier for the customer (e.g. cus_xxx).
​
email
string
required
Customer email address.
​
name
string
Customer full name.
​
phone
string
Customer phone number.
​
kennitala
string
Icelandic national ID.
​
external_id
string
Your reference identifier for this customer.
​
vat_number
string
VAT registration number.
​
metadata
object
Key-value pairs attached to the customer.
​
billing_address
object
Structured billing address.
​
created_at
string
required
ISO 8601 timestamp of when the customer was created.
{
  "id": "cus_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "email": "sigrid@example.is",
  "name": "Sigríður Jónsdóttir",
  "phone": "+354 555 1234",
  "kennitala": "1234567890",
  "external_id": "usr_9982",
  "vat_number": "IS12345",
  "metadata": {
    "plan": "enterprise"
  },
  "billing_address": {
    "line1": "Laugavegur 12",
    "line2": null,
    "city": "Reykjavík",
    "postal_code": "101",
    "country": "IS"
  },
  "created_at": "2026-04-29T10:15:00Z"
}

​
List customers

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

​
Query parameters

​
starting_after
string
Cursor for pagination. Pass the id of the last customer from the previous page to retrieve the next page.
​
limit
number
Maximum number of customers to return per page.
curl --request GET \
  --url "https://api.borga.is/v1/customers?limit=20" \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx"

​
Response fields

​
data
object[]
required
Array of customer objects.
​
has_more
boolean
required
Whether more customers exist beyond this page.
{
  "data": [
    {
      "id": "cus_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "email": "sigrid@example.is",
      "name": "Sigríður Jónsdóttir",
      "kennitala": "1234567890",
      "billing_address": {
        "line1": "Laugavegur 12",
        "line2": null,
        "city": "Reykjavík",
        "postal_code": "101",
        "country": "IS"
      },
      "created_at": "2026-04-29T10:15:00Z"
    }
  ],
  "has_more": false
}

​
Retrieve a customer

GET /v1/customers/{id} Retrieves the details of an existing customer.

​
Path parameters

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

​
Response fields

​
id
string
required
Unique customer identifier.
​
email
string
required
Customer email address.
​
name
string
Customer full name.
​
phone
string
Customer phone number.
​
kennitala
string
Icelandic national ID.
​
external_id
string
Your reference identifier for this customer.
​
vat_number
string
VAT registration number.
​
metadata
object
Key-value pairs attached to the customer.
​
billing_address
object
Structured billing address.
​
created_at
string
required
ISO 8601 timestamp of when the customer was created.
{
  "id": "cus_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "email": "sigrid@example.is",
  "name": "Sigríður Jónsdóttir",
  "phone": "+354 555 1234",
  "kennitala": "1234567890",
  "external_id": "usr_9982",
  "vat_number": "IS12345",
  "metadata": {
    "plan": "enterprise"
  },
  "billing_address": {
    "line1": "Laugavegur 12",
    "line2": null,
    "city": "Reykjavík",
    "postal_code": "101",
    "country": "IS"
  },
  "created_at": "2026-04-29T10:15:00Z"
}

​
Update a customer

PATCH /v1/customers/{id} Updates an existing customer. Only the fields you provide are changed — all other fields remain unchanged.

​
Path parameters

​
id
string
required
The ID of the customer to update.

​
Request parameters

​
email
string
Updated email address.
​
name
string
Updated full name.
​
phone
string
Updated phone number.
​
kennitala
string
Updated Icelandic national ID.
​
external_id
string
Updated external reference identifier.
​
vat_number
string
Updated VAT registration number.
​
metadata
object
Updated metadata. Replaces the existing metadata object entirely.
​
billing_address_line1
string
Updated primary billing address line.
​
billing_address_line2
string
Updated secondary billing address line.
​
billing_city
string
Updated billing city.
​
billing_postal_code
string
Updated billing postal code.
​
billing_country
string
Updated two-letter ISO country code.
curl --request PATCH \
  --url https://api.borga.is/v1/customers/cus_01hx9z3k2mfq7nbvd4cw8ej5rt \
  --header "Authorization: Bearer sk_live_..." \
  --header "X-Merchant-Id: mer_xxx" \
  --header "Content-Type: application/json" \
  --data '{
    "email": "sigrid.new@example.is",
    "billing_city": "Akureyri",
    "billing_postal_code": "600"
  }'

​
Response fields

Returns the updated customer object. See retrieve a customer for the full field reference. 
{
  "id": "cus_01hx9z3k2mfq7nbvd4cw8ej5rt",
  "email": "sigrid.new@example.is",
  "name": "Sigríður Jónsdóttir",
  "phone": "+354 555 1234",
  "kennitala": "1234567890",
  "external_id": "usr_9982",
  "vat_number": "IS12345",
  "metadata": {
    "plan": "enterprise"
  },
  "billing_address": {
    "line1": "Laugavegur 12",
    "line2": null,
    "city": "Akureyri",
    "postal_code": "600",
    "country": "IS"
  },
  "created_at": "2026-04-29T10:15:00Z"
}