Customers API — create and manage customer records

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

string

required

Email address of the customer. Must be a valid email format.

string

Full name of the customer.

string

Phone number of the customer.

string

Icelandic national ID (kennitala). Ten-digit identifier used for individuals and legal entities in Iceland.

string

Your own identifier for this customer — an ID from your database or CRM. Stored as-is and returned in all responses.

string

VAT registration number for the customer. Included on invoices when present.

object

Set of key-value pairs you can attach to the customer. Values must be strings.

string

Primary billing address line.

string

Secondary billing address line (apartment, suite, etc.).

string

City for the billing address.

string

Postal code for the billing address.

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

string

required

Unique identifier for the customer (e.g. cus_xxx).

string

required

Customer email address.

string

Customer full name.

string

Customer phone number.

string

Icelandic national ID.

string

Your reference identifier for this customer.

string

VAT registration number.

object

Key-value pairs attached to the customer.

object

Structured billing address.

Show properties

string

Primary address line.

string

Secondary address line.

string

City.

string

Postal code.

string

Two-letter ISO country code.

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

string

Cursor for pagination. Pass the id of the last customer from the previous page to retrieve the next page.

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

object[]

required

Array of customer objects.

Show customer fields

string

required

Unique customer identifier.

string

required

Customer email address.

string

Customer full name.

string

Icelandic national ID.

object

Structured billing address.

string

required

ISO 8601 creation timestamp.

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

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

string

required

Unique customer identifier.

string

required

Customer email address.

string

Customer full name.

string

Customer phone number.

string

Icelandic national ID.

string

Your reference identifier for this customer.

string

VAT registration number.

object

Key-value pairs attached to the customer.

object

Structured billing address.

Show properties

string

Primary address line.

string

Secondary address line.

string

City.

string

Postal code.

string

Two-letter ISO country code.

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

string

required

The ID of the customer to update.

Request parameters

string

Updated email address.

string

Updated full name.

string

Updated phone number.

string

Updated Icelandic national ID.

string

Updated external reference identifier.

string

Updated VAT registration number.

object

Updated metadata. Replaces the existing metadata object entirely.

string

Updated primary billing address line.

string

Updated secondary billing address line.

string

Updated billing city.

string

Updated billing postal code.

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

Overview

Payments

Subscriptions

Billing

Configuration

Customers API — create and manage customer records

Create a customer

Request parameters

Response fields

List customers

Query parameters

Response fields

Retrieve a customer

Path parameters

Response fields

Update a customer

Path parameters

Request parameters

Response fields

​Create a customer

​Request parameters

​Response fields

​List customers

​Query parameters

​Response fields

​Retrieve a customer

​Path parameters

​Response fields

​Update a customer

​Path parameters

​Request parameters

​Response fields

Create a customer

Request parameters

Response fields

List customers

Query parameters

Response fields

Retrieve a customer

Path parameters

Response fields

Update a customer

Path parameters

Request parameters

Response fields