Copy page

Sell and get paid

Customers

A customer is the account everything else in Kontier hangs off: subscriptions, invoices, payments, wallets and quotes all point at one. It carries the billing address, the tax identity, the contact who receives mail, and the currency it is billed in.

Two fields on a customer reach much further than they look. Type decides how tax is calculated. Currency is the default that new subscriptions, wallets and invoices inherit, and it decides which of a product's prices apply without conversion. Both are worth getting right at creation rather than discovering later on an invoice — the currency can be changed afterwards, but it does not reach backwards into what already exists.

✕

Business or consumer

customer_type is required at creation, and it is the field with the longest reach.

Business

A company. VAT identification applies, reverse charge becomes possible on cross-border supply, and a VAT number can be validated against VIES.

Use it whenever you are invoicing an organisation, even a one-person one.

Consumer

A private individual. Tax is charged at the rate of the customer's own country under EU distance-selling rules, and no VAT number is expected.

Unknown

You do not know yet. Useful when a signup has not disclosed enough to decide, but it is a placeholder, not a destination: tax treatment cannot be resolved confidently until it becomes BUSINESS or CONSUMER.

Create one in the dashboard

Create one with the API

Changing a customer's billing currency

The field is preferred_currency, and you change it with an ordinary PATCH /v1/customers/{id}:

cURL
curl -X PATCH https://api.kontier.eu/v1/customers/cus_01J9Z… \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "preferred_currency": "USD" }'

There is no currency field on a customer, and no dedicated currency endpoint. A value must be three uppercase letters; "" is refused, because "leave it alone" is already spelled by omitting the field.

It is a preference, not a lock

Kontier deliberately does not freeze a customer's currency once they have a subscription, and there is no state in which the only way to change it is to delete and recreate the customer. You can move it with subscriptions active, cancelled or never created. The only gate is the workspace allow-list.

That is possible because nothing downstream depends on the preference staying still. A subscription pins its own currency at creation; wallets are one per (customer, currency); invoices, credit notes, payments and refunds each pin a currency at write and are never re-denominated.

What it does and does not affect

Affected	Not affected
Subscriptions created after the change, when the request omits currency	Existing subscriptions. Their contract currency is frozen and their next invoice is still billed in it.
Wallets you create afterwards, and the currency reported on the wallet-default amounts	Wallets that already exist. None is created, renamed or converted.
The default currency of a manual invoice when the request omits one	Finalised invoices, credit notes, payments and refunds, which keep their own currency and FX rate

Moving a subscription to another currency

Cancel the old subscription and create a new one with the currency you want:

1. End the old contract
curl -X POST https://api.kontier.eu/v1/subscriptions/sub_01J9Z…/cancel \
  -H "Authorization: Bearer sk_test_…"

2. Sell the same plan again, in the new currency
curl -X POST https://api.kontier.eu/v1/subscriptions \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_01J9Z…",
    "plan_id":     "plan_01J9Z…",
    "currency":    "USD",
    "phases": [ { "phase_kind": "standard", "end_kind": "manual" } ]
  }'

A customer may hold only one live subscription per plan, but a cancelled one no longer occupies that slot, so the replacement can be created immediately and on the same plan. Cancelling mid-period credits the unearned remainder, so do it at a period boundary if you do not want that credit. See Subscriptions.

A wallet in the new currency does not appear by itself

The primary wallet was minted in the customer's currency when the customer was created, and a currency change leaves it exactly where it is. If you need a balance in the new currency, create one:

cURL
curl -X POST https://api.kontier.eu/v1/wallets \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "cus_01J9Z…", "currency": "USD" }'

That is a second wallet, not a replacement — wallets are unique per (customer, currency) and only one of a customer's wallets is the primary. Move the old balance across with POST /v1/wallets/{id}/transfer, which converts at the organisation's FX rate and returns the snapshot it used, or spend it down first. A transfer moves cash only; promotional credit stays with the wallet it was granted to.

Creating the new wallet does not make it primary. Promote it explicitly:

cURL
curl -X POST https://api.kontier.eu/v1/wallets/wal_01JA1…/primary \
  -H "Authorization: Bearer sk_test_…"

That matters more than it looks. The primary wallet is what invoice settlement falls back to when the customer holds no wallet in the invoice's currency, the preferred funding source when cross-currency settlement is enabled, and the wallet the customer portal shows billing settings for. Leave it on the old currency and all three keep pointing at a wallet the customer no longer uses.

The change is recorded

A real change emits customer.currency_changed, carrying from, to, actor_id and changed_at. It is the only place the previous currency survives, so subscribe to it if you reconcile denominations. A PATCH that restates the currency the customer already has emits nothing.

customer.currency_changed
{
  "customer_id":     "cus_01J9Z…",
  "organization_id": "org_01J9Z…",
  "actor_id":        "usr_01J9Z…",
  "from":            "EUR",
  "to":              "USD",
  "changed_at":      "2025-03-15T14:30:00Z"
}

The 400 you will get if the currency is not enabled

The new code must be enabled for billing on the workspace's currency allow-list. If it is not:

Response 400
{
  "type":       "https://api.kontier.com/errors/VALIDATION",
  "title":      "Validation Error",
  "status":     400,
  "detail":     "The request input is invalid.",
  "code":       "VALIDATION",
  "request_id": "01HKZ…",
  "fields": [
    {
      "field":   "preferred_currency",
      "code":    "CURRENCY_NOT_ALLOWED",
      "message": "currency \"USD\" is not enabled for billing in this workspace - enable it in Settings → Currencies"
    }
  ]
}

Fix it with POST /v1/currencies (or Settings → Currencies in the dashboard), then retry.

A safe sequence

1. Enable the new currency for billing, and for catalog too if you are going to author prices in it: POST /v1/currencies.
2. Publish prices in it. A subscription billed in USD against a EUR-only catalog is legal — the catalog price is converted at the prevailing rate — but a real USD price is usually what was meant, and it removes the dependency on an FX rate existing for the pair.
3. Deal with the old wallet. Spend it down, or transfer the balance into a wallet in the new currency once you have created one.
4. Cancel the old subscriptions at a period boundary, and create their replacements with an explicit currency.
5. PATCH the customer, restating any default_* wallet amount in the new currency in the same request.
6. Check what still uses the old code with GET /v1/currencies/{old} before you disable it. The references counts say exactly what is left.

Dashboard and API names

In the dashboard	In the API
Type: Business / Consumer / Unknown	customer_type: "BUSINESS" / "CONSUMER" / "UNKNOWN"
Currency	preferred_currency, the ISO 4217 code new objects for this customer default to. There is no currency field on a customer.
Email	email, the default billing-mail recipient
Status: Active / Suspended / Churned	status
Verifications tab	POST /customers/{id}/verifications/vat
Payment providers tab	provider_settings and disabled_providers

Where customers go next

1. Subscribe them to a plan. That is what turns a customer into revenue.
2. Verify the VAT number if they are a business trading across a border. Reverse charge depends on it.
3. Merge duplicates with POST /v1/customers/merge rather than deleting one, so invoices and payments follow.

Reference

Topic	When you need it
Verifications	VAT validation, its states and what blocks on it
Taxes	How type, country and tax category resolve into a rate
Custom fields	Extending a customer with your own data
Customers API	Every field, plus merge, contacts and portal links