Copy page

Subscriptions

Customers

A customer is the entity that owns billing relationships in your account. Customers hold subscriptions, receive invoices, store payment methods, and accumulate wallet balances. Every billing object in Kontorion ultimately ties back to a customer.

Why this matters. A reliable customer model is the foundation of every downstream billing decision: invoicing, dunning, revenue recognition, and reporting all resolve through this object. Kontorion's customer record is designed to absorb the variability of real-world commercial relationships without forcing schema migrations - tax identifiers, billing addresses, verifications, custom fields, and per-customer payment terms all live alongside the core identity. The same model supports a SaaS company billing a single technical contact at a startup, an enterprise vendor invoicing a procurement department through a Leitweg-ID, a marketplace platform tracking thousands of seller accounts, and a regulated provider running KYC checks before activation.

Customer model

Field	Description
id	Kontorion-assigned UUID. Use this everywhere you reference the customer.
external_id	Your internal id for the customer (optional). Free-form string, indexed and unique per organization when set.
email	Primary contact email. Used for invoice delivery and dunning.
name	Display name. Appears on invoices and PDFs.
billing_address	Address used for tax determination and invoice rendering. country is an ISO 3166-1 alpha-2 code; required for tax determination.
tax_identifiers	Map keyed by tax-id type (eu_vat, us_ein, ch_uid, etc.) with the identifier value as the string. Drives reverse-charge and exemption logic.
metadata	Free-form key-value bag for your own use.
custom_fields	Typed values for custom field definitions configured on your organization.
preferred_currency	Preferred billing currency (ISO 4217). Falls back to the workspace default when null.
customer_type	BUSINESS, CONSUMER, or UNKNOWN.
billing_model	Indicates how this customer is billed (postpaid, prepaid, hybrid).
vat_validation_status	UNVALIDATED, PENDING, VALID, INVALID, ERROR, MANUAL, or MAINTENANCE.
status	active, suspended, churned. Suspended customers cannot create new invoices.
mode	Wallet mode (live / prepaid_only / etc.) - drives how usage charges are settled.
payment_terms_days	Optional default Net-N payment window applied to this customer's invoices.
peppol_id, prefer_einvoice, einvoice_email	Peppol delivery preferences for e-invoicing.

Creating a customer

Code
curl -X POST https://api.kontorion.eu/v1/customers \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id":        "acct_42",
    "name":               "Acme GmbH",
    "email":              "billing@acme.example",
    "preferred_currency": "EUR",
    "locale":             "de-DE",
    "billing_address": {
      "country": "DE",
      "city": "Berlin",
      "postal_code": "10115",
      "country":     "DE"
    },
    "tax_identifiers": { "eu_vat": "DE123456789" },
    "preferred_currency": "EUR",
    "customer_type": "BUSINESS"
  }'

name and email are required. Returns 201 Created with the customer object plus the customer's primary wallet.

Verification

Customers can carry verification records (KYC, business documents, payment instrument checks). The verification status gates which payment methods and plan tiers are available.

Merging duplicates

If the same real-world customer ends up with two records (e.g., self-signup followed by sales-assisted enrollment), merge them. The endpoint is at the resource root - it takes both ids in the body, not in the path:

Code
curl -X POST https://api.kontorion.eu/v1/customers/merge \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "source_customer_id": "{duplicate_id}",
    "target_customer_id": "{primary_id}",
    "strategy": "MOVE_ALL"
  }'

Field	Required	Notes
source_customer_id	yes	The duplicate that will be merged in.
target_customer_id	yes	The kept customer; receives subscriptions, invoices, wallets, and payment methods. Must be different from the source.
strategy	yes	PREVIEW (dry-run, returns the proposed plan) or MOVE_ALL (executes the merge).

The merge moves subscriptions, invoices, payment methods, and wallet balances onto the target. Conflicts (overlapping subscriptions on the same plan, or business-rule violations) return 409 MERGE_CONFLICT. Self-merges (same source and target) return 422 MERGE_SELF. A merge against an already-deleted source returns 422 MERGE_SOURCE_DELETED.

Returns 200 OK with the merge result document.

Run PREVIEW first; address conflicts; then run MOVE_ALL.

Per-customer endpoints

• Custom field values - per-customer typed metadata.
• Tax identifiers - drive reverse-charge and exemption logic at invoice time.

VAT verification status (vat_validation_status) is updated automatically by the VIES integration; a manual override can be set via POST /v1/customers/{id}/verifications/vat/manual and cleared with DELETE /v1/customers/{id}/verifications/vat/manual.

Endpoints

All Customers endpoints

Related

• Subscriptions - the entity that attaches a customer to a plan
• Wallets - prepaid / postpaid balance per customer
• Verifications - KYC / VAT / business-doc checks tied to the customer
• Custom fields - per-customer typed metadata
• Tags - polymorphic tags for segmentation
• Taxes - tax_identifiers + customer_type + billing-address country drive the determination flow