A customer represents a person or company that purchases your products and services. Customers are the foundation of your billing relationship - every subscription, invoice, and payment is tied to a customer record.
Each customer has a billing profile including address, preferred currency, tax identifiers, and custom fields. Customers can be tagged for segmentation, merged when duplicates are discovered, and validated through identity verification providers.
Key concepts:
- External ID - your internal identifier for this customer, used for idempotent upserts
- Billing model - controls how charges are calculated (prepaid, postpaid, or hybrid)
- Customer type -
individualorcompany, affects tax treatment and invoice formatting - Metadata - arbitrary key-value pairs for your own bookkeeping
List customers
Returns a paginated list of customers with optional status and tag filters
query Parameters
limitPage size
cursorPagination cursor
statusFilter by status
tagsComma-separated tags for containment filtering
List customers › Responses
Paginated list with data and pagination envelope
billing_modelcreated_atcustomer_typedefault_auto_topup_amountdefault_auto_topup_enableddefault_credit_limitdefault_low_balance_thresholddefault_max_balancedefault_max_single_creditdeleted_atdisabled_providerseinvoice_emailemailexternal_ididlocalemodenameorganization_idpayment_terms_dayspeppol_idprefer_einvoicepreferred_currencypreferred_providerstatusupdated_atvat_validation_disabledvat_validation_disabled_reasonvat_validation_statusCreate a customer
Creates a new customer with an auto-provisioned wallet
Create a customer › Request Body
auto_validate_vatAutoValidateVAT is a per-request hint controlling whether the handler kicks off an async VAT validation after creation. nil = default behavior (auto-validate when otherwise eligible). false = skip the auto-trigger even if eligible (useful for bulk imports / automation). Workspace-level verification.vat.enabled and per-customer VatValidationDisabled both still take precedence - this flag only suppresses the optional handler-side dispatch.
billing_modelcustomer_typedefault_auto_topup_amountdefault_auto_topup_enableddefault_credit_limitdefault_low_balance_thresholddefault_max_balancedefault_max_single_creditdisabled_providerseinvoice_emailemailexternal_idlocalemodenamepayment_terms_dayspeppol_idprefer_einvoicepreferred_currencypreferred_providervat_validation_disabledvat_validation_disabled_reasonCreate a customer › Responses
Wrapped in data envelope
Merge customers
Merges two customers into one
Merge customers › Request Body
source_customer_idstrategytarget_customer_idMerge customers › Responses
Wrapped in data envelope
customer_scoped_prices_countinvoices_countpayment_methods_countpromotion_redemptions_countsource_customer_idsubscriptions_counttarget_customer_idusage_events_countwallets_merged_countwallets_moved_countGet a customer
Returns a single customer by UUID
path Parameters
idCustomer UUID
Get a customer › Responses
Wrapped in data envelope
billing_modelcreated_atcustomer_typedefault_auto_topup_amountdefault_auto_topup_enableddefault_credit_limitdefault_low_balance_thresholddefault_max_balancedefault_max_single_creditdeleted_atdisabled_providerseinvoice_emailemailexternal_ididlocalemodenameorganization_idpayment_terms_dayspeppol_idprefer_einvoicepreferred_currencypreferred_providerstatusupdated_atvat_validation_disabledvat_validation_disabled_reasonvat_validation_statusUpdate a customer
Updates an existing customer by UUID
path Parameters
idCustomer UUID
Update a customer › Request Body
auto_validate_vatAutoValidateVAT - see CreateCustomerRequest.AutoValidateVAT. Same semantics on update: nil = default behavior, false = skip the auto-trigger after update, true = request it (still gated by org and per-customer disable flags).
billing_modelcustomer_typedefault_auto_topup_amountdefault_auto_topup_enableddefault_credit_limitdefault_low_balance_thresholddefault_max_balancedefault_max_single_creditdisabled_providerseinvoice_emailemailexternal_idlocalenamepayment_terms_dayspeppol_idprefer_einvoicepreferred_currencypreferred_providerstatusvat_validation_disabledvat_validation_disabled_reasonUpdate a customer › Responses
Wrapped in data envelope
billing_modelcreated_atcustomer_typedefault_auto_topup_amountdefault_auto_topup_enableddefault_credit_limitdefault_low_balance_thresholddefault_max_balancedefault_max_single_creditdeleted_atdisabled_providerseinvoice_emailemailexternal_ididlocalemodenameorganization_idpayment_terms_dayspeppol_idprefer_einvoicepreferred_currencypreferred_providerstatusupdated_atvat_validation_disabledvat_validation_disabled_reasonvat_validation_statusChange customer billing mode (PREPAID / POSTPAID)
Flips a customer between PREPAID and POSTPAID. Mode lives on the customer; all of the customer's wallets share it. The mode is forward-looking only: the flip performs no balance recompute or movement, and any current cash / held / promo state on each wallet carries over unchanged. PREPAID's "available ≥ amount" guard applies to subsequent debits; POSTPAID's credit_limit guard does the same.
path Parameters
idCustomer UUID
Change customer billing mode (PREPAID / POSTPAID) › Request Body
modereasonChange customer billing mode (PREPAID / POSTPAID) › Responses
Updated customer, wrapped in data envelope
billing_modelcreated_atcustomer_typedefault_auto_topup_amountdefault_auto_topup_enableddefault_credit_limitdefault_low_balance_thresholddefault_max_balancedefault_max_single_creditdeleted_atdisabled_providerseinvoice_emailemailexternal_ididlocalemodenameorganization_idpayment_terms_dayspeppol_idprefer_einvoicepreferred_currencypreferred_providerstatusupdated_atvat_validation_disabledvat_validation_disabled_reasonvat_validation_statusUpdate customer payment-provider settings
Updates only preferred_provider and/or disabled_providers
path Parameters
idCustomer UUID
Update customer payment-provider settings › Request Body
disabled_providerspreferred_providerUpdate customer payment-provider settings › Responses
Wrapped in data envelope
billing_modelcreated_atcustomer_typedefault_auto_topup_amountdefault_auto_topup_enableddefault_credit_limitdefault_low_balance_thresholddefault_max_balancedefault_max_single_creditdeleted_atdisabled_providerseinvoice_emailemailexternal_ididlocalemodenameorganization_idpayment_terms_dayspeppol_idprefer_einvoicepreferred_currencypreferred_providerstatusupdated_atvat_validation_disabledvat_validation_disabled_reasonvat_validation_statusChange customer type (BUSINESS / CONSUMER / UNKNOWN)
Flips the customer's tax-relevant classification. Type drives reverse-charge eligibility, default payment terms, price-display mode, and consumer-protection law applicability - every flip is an accounting decision and must carry a reason. Forward-looking: prior invoices are NOT re-issued. UNKNOWN→BUSINESS in an EU jurisdiction surfaces a "corrective invoice candidate" hint via the customer.type_changed event so operators can review affected invoices through the credit-note service.
path Parameters
idCustomer UUID
Change customer type (BUSINESS / CONSUMER / UNKNOWN) › Request Body
customer_typereasonChange customer type (BUSINESS / CONSUMER / UNKNOWN) › Responses
Updated customer wrapped in data envelope
billing_modelcreated_atcustomer_typedefault_auto_topup_amountdefault_auto_topup_enableddefault_credit_limitdefault_low_balance_thresholddefault_max_balancedefault_max_single_creditdeleted_atdisabled_providerseinvoice_emailemailexternal_ididlocalemodenameorganization_idpayment_terms_dayspeppol_idprefer_einvoicepreferred_currencypreferred_providerstatusupdated_atvat_validation_disabledvat_validation_disabled_reasonvat_validation_statusTrigger a VAT verification (VIES live check)
Runs a synchronous VIES validation against the customer's vat_number and returns the updated customer. Idempotent - safe to call repeatedly. Honours the workspace kill switch (tax.vat_validation_enabled), the per-customer opt-out, and the configured maintenance window.
path Parameters
idCustomer UUID
Trigger a VAT verification (VIES live check) › Responses
Wrapped in data envelope
billing_modelcreated_atcustomer_typedefault_auto_topup_amountdefault_auto_topup_enableddefault_credit_limitdefault_low_balance_thresholddefault_max_balancedefault_max_single_creditdeleted_atdisabled_providerseinvoice_emailemailexternal_ididlocalemodenameorganization_idpayment_terms_dayspeppol_idprefer_einvoicepreferred_currencypreferred_providerstatusupdated_atvat_validation_disabledvat_validation_disabled_reasonvat_validation_statusSet a manual VAT-validation override
Operator override for cases where VIES disagrees with out-of-band evidence. Writes a MANUAL verification row with reason + actor + TTL provenance and promotes customers.vat_validation_status to MANUAL. The recheck job demotes back to PENDING when the TTL elapses.
path Parameters
idCustomer UUID
Set a manual VAT-validation override › Responses
Updated customer wrapped in data envelope
billing_modelcreated_atcustomer_typedefault_auto_topup_amountdefault_auto_topup_enableddefault_credit_limitdefault_low_balance_thresholddefault_max_balancedefault_max_single_creditdeleted_atdisabled_providerseinvoice_emailemailexternal_ididlocalemodenameorganization_idpayment_terms_dayspeppol_idprefer_einvoicepreferred_currencypreferred_providerstatusupdated_atvat_validation_disabledvat_validation_disabled_reasonvat_validation_statusClear a manual VAT-validation override
Removes the operator MANUAL row by transitioning to PENDING. The customer's vat_validation_status returns to UNVALIDATED until the next auto- or manual-trigger lands a fresh VIES result. Idempotent.
path Parameters
idCustomer UUID
Clear a manual VAT-validation override › Responses
Updated customer wrapped in data envelope
billing_modelcreated_atcustomer_typedefault_auto_topup_amountdefault_auto_topup_enableddefault_credit_limitdefault_low_balance_thresholddefault_max_balancedefault_max_single_creditdeleted_atdisabled_providerseinvoice_emailemailexternal_ididlocalemodenameorganization_idpayment_terms_dayspeppol_idprefer_einvoicepreferred_currencypreferred_providerstatusupdated_atvat_validation_disabledvat_validation_disabled_reasonvat_validation_statusGet customer wallet
Returns the primary wallet for a customer
path Parameters
idCustomer UUID
Get customer wallet › Responses
Wrapped in data envelope
auto_topup_enabledcreated_atcurrencycustomer_ididis_primarymodeorganization_idpromotional_balance_expires_atupdated_at