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

# Customers API — create and manage customer records

> Create, list, retrieve, and update customer objects. Supports Icelandic kennitala, VAT numbers, billing address fields, and arbitrary metadata.

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

<ParamField body="email" type="string" required>
  Email address of the customer. Must be a valid email format.
</ParamField>

<ParamField body="name" type="string">
  Full name of the customer.
</ParamField>

<ParamField body="phone" type="string">
  Phone number of the customer.
</ParamField>

<ParamField body="kennitala" type="string">
  Icelandic national ID (kennitala). Ten-digit identifier used for individuals and legal entities in Iceland.
</ParamField>

<ParamField body="external_id" type="string">
  Your own identifier for this customer — an ID from your database or CRM. Stored as-is and returned in all responses.
</ParamField>

<ParamField body="vat_number" type="string">
  VAT registration number for the customer. Included on invoices when present.
</ParamField>

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

<ParamField body="billing_address_line1" type="string">
  Primary billing address line.
</ParamField>

<ParamField body="billing_address_line2" type="string">
  Secondary billing address line (apartment, suite, etc.).
</ParamField>

<ParamField body="billing_city" type="string">
  City for the billing address.
</ParamField>

<ParamField body="billing_postal_code" type="string">
  Postal code for the billing address.
</ParamField>

<ParamField body="billing_country" type="string">
  Two-letter ISO 3166-1 alpha-2 country code (e.g. `IS`, `GB`, `DE`).
</ParamField>

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

### Response fields

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

<ResponseField name="email" type="string" required>
  Customer email address.
</ResponseField>

<ResponseField name="name" type="string">
  Customer full name.
</ResponseField>

<ResponseField name="phone" type="string">
  Customer phone number.
</ResponseField>

<ResponseField name="kennitala" type="string">
  Icelandic national ID.
</ResponseField>

<ResponseField name="external_id" type="string">
  Your reference identifier for this customer.
</ResponseField>

<ResponseField name="vat_number" type="string">
  VAT registration number.
</ResponseField>

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

<ResponseField name="billing_address" type="object">
  Structured billing address.

  <Expandable title="properties">
    <ResponseField name="line1" type="string">
      Primary address line.
    </ResponseField>

    <ResponseField name="line2" type="string">
      Secondary address line.
    </ResponseField>

    <ResponseField name="city" type="string">
      City.
    </ResponseField>

    <ResponseField name="postal_code" type="string">
      Postal code.
    </ResponseField>

    <ResponseField name="country" type="string">
      Two-letter ISO country code.
    </ResponseField>
  </Expandable>
</ResponseField>

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

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

***

## List customers

`GET /v1/customers`

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

### Query parameters

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

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

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

### Response fields

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

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

    <ResponseField name="email" type="string" required>
      Customer email address.
    </ResponseField>

    <ResponseField name="name" type="string">
      Customer full name.
    </ResponseField>

    <ResponseField name="kennitala" type="string">
      Icelandic national ID.
    </ResponseField>

    <ResponseField name="billing_address" type="object">
      Structured billing address.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 creation timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

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

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

***

## Retrieve a customer

`GET /v1/customers/{id}`

Retrieves the details of an existing customer.

### Path parameters

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

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

### Response fields

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

<ResponseField name="email" type="string" required>
  Customer email address.
</ResponseField>

<ResponseField name="name" type="string">
  Customer full name.
</ResponseField>

<ResponseField name="phone" type="string">
  Customer phone number.
</ResponseField>

<ResponseField name="kennitala" type="string">
  Icelandic national ID.
</ResponseField>

<ResponseField name="external_id" type="string">
  Your reference identifier for this customer.
</ResponseField>

<ResponseField name="vat_number" type="string">
  VAT registration number.
</ResponseField>

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

<ResponseField name="billing_address" type="object">
  Structured billing address.

  <Expandable title="properties">
    <ResponseField name="line1" type="string">
      Primary address line.
    </ResponseField>

    <ResponseField name="line2" type="string">
      Secondary address line.
    </ResponseField>

    <ResponseField name="city" type="string">
      City.
    </ResponseField>

    <ResponseField name="postal_code" type="string">
      Postal code.
    </ResponseField>

    <ResponseField name="country" type="string">
      Two-letter ISO country code.
    </ResponseField>
  </Expandable>
</ResponseField>

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

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

***

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

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

### Request parameters

<ParamField body="email" type="string">
  Updated email address.
</ParamField>

<ParamField body="name" type="string">
  Updated full name.
</ParamField>

<ParamField body="phone" type="string">
  Updated phone number.
</ParamField>

<ParamField body="kennitala" type="string">
  Updated Icelandic national ID.
</ParamField>

<ParamField body="external_id" type="string">
  Updated external reference identifier.
</ParamField>

<ParamField body="vat_number" type="string">
  Updated VAT registration number.
</ParamField>

<ParamField body="metadata" type="object">
  Updated metadata. Replaces the existing metadata object entirely.
</ParamField>

<ParamField body="billing_address_line1" type="string">
  Updated primary billing address line.
</ParamField>

<ParamField body="billing_address_line2" type="string">
  Updated secondary billing address line.
</ParamField>

<ParamField body="billing_city" type="string">
  Updated billing city.
</ParamField>

<ParamField body="billing_postal_code" type="string">
  Updated billing postal code.
</ParamField>

<ParamField body="billing_country" type="string">
  Updated two-letter ISO country code.
</ParamField>

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

### Response fields

Returns the updated customer object. See [retrieve a customer](#retrieve-a-customer) for the full field reference.

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