# Customers

> The people and companies you bill. Customers own saved cards, subscriptions and invoices.

Source: https://docs.borga.is/api/customers

**The customer object**

- `id` (string): Prefixed `cus_`.
- `email` (string): - `name` (string | null) - `phone` (string | null) <Param name="kennitala" type="string | null">Icelandic national or company id. Needed for bank-invoice collection.
- `external_id` (string | null): Your own id. Usage events can reference it as `external_customer_id`.
- `vat_number` (string | null): <Param name="billing_address" type="object | null">`line1`, `line2`, `city`, `postal_code`, `country`.
- `default_payment_method` (string | null): The `pm_` charged by subscriptions.
- `metadata` (object): - `created_at` (timestamp) - `updated_at` (timestamp) ## Create a customer `POST /v1/customers` **Body** - `email` (string) - `name` (string) - `phone` (string) - `kennitala` (string) <Param name="external_id" type="string">Your own identifier, unique per customer.
- `vat_number` (string): - `billing_address_line1` (string) - `billing_address_line2` (string) - `billing_city` (string) - `billing_postal_code` (string) <Param name="billing_country" type="string">ISO 3166-1 alpha-2, for example `IS`.
- `metadata` (object): ```bash curl https://api.borga.is/v1/customers \ -H "Authorization: Bearer sk_test_…" \ -H "Content-Type: application/json" \ -d '{ "email": "anna@example.is", "name": "Anna Jónsdóttir", "kennitala": "0101302989", "external_id": "user_12345", "billing_address_line1": "Laugavegur 1", "billing_postal_code": "101", "billing_city": "Reykjavík", "billing_country": "IS" }' ``` ```json title="Response" { "id": "cus_8Jk2Lm4Np6Qr8St0Uv2Wx4Yz", "email": "anna@example.is", "name": "Anna Jónsdóttir", "phone": null, "kennitala": "0101302989", "external_id": "user_12345", "vat_number": null, "billing_address": { "line1": "Laugavegur 1", "line2": null, "city": "Reykjavík", "postal_code": "101", "country": "IS" }, "metadata": {}, "default_payment_method": null, "created_at": "2026-09-07T10:00:00.000Z", "updated_at": "2026-09-07T10:00:00.000Z" } ``` ## Retrieve a customer `GET /v1/customers/:id` ## Update a customer `PATCH /v1/customers/:id` Accepts the same fields as create, all optional. Only the fields you send are changed. **Body** - `email` (string) - `name` (string) - `phone` (string) - `kennitala` (string) <Param name="external_id" type="string">Send an empty string to clear.
- `vat_number` (string): - `billing_address_line1` (string) - `billing_address_line2` (string) - `billing_city` (string) - `billing_postal_code` (string) - `billing_country` (string) - `metadata` (object) ## List customers `GET /v1/customers` **Query parameters** <Param name="email" type="string">Exact match, case-insensitive.
- `limit` (integer)
- `starting_after` (string)