Appearance
Customers
A Customer represents a person or company that purchases articles from your service. Each customer belongs to exactly one service and has a country for tax purposes.
A customer is not the end user themselves - it is the billing entity. Users are linked to customers and can place orders on their behalf, but the order, balance, and payment data always belongs to the customer. Think of the customer as the account that gets invoiced, while users are the people who interact with your service.
Example
Company A signs up for your SaaS product. You create one customer for Company A in TiruPay. Three employees each have their own user account and are linked to that customer. All three can place orders, but every order, subscription, and invoice runs through the single Company A customer. One balance, one invoice address, one billing history.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
first_name | string | yes | Customer's first name |
last_name | string | yes | Customer's last name |
email | string | yes | Must contain @. Unique across all customers in a service. |
street | string | yes | Street address |
city | string | yes | City |
postal_code | string | yes | Postal/ZIP code |
country_code | string | yes | Reference to a country |
service_id | string | yes | The service this customer belongs to |
ext_invoicing_id | string | yes | External ID in your invoicing provider (see Invoicing) |
phone | string | no | Phone number |
is_company | boolean | no | Whether the customer is a company (default: false) |
company_name | string | conditional | Required if is_company is true |
company_vat_id | string | no | VAT ID of the company. Not required, but needed to claim tax exemption (see below). |
company_tax_exempt | boolean | no | Whether the company is tax-exempt (default: false) |
trust_score | float | no | Trust score from 0.0 to 100.0 (default: 50.0). Can be used for risk assessment. |
internal_note | string | no | Admin-only free text, at most 10,000 characters. Never returned to services or customers and never sent in webhooks. |
import_execution_id | string | read-only | Admin-only. The data import execution that created the customer, empty otherwise. |
Company Customers
When is_company is set to true, company_name becomes required. This is enforced on both create and update operations. company_vat_id is optional and can be added or changed independently.
A company customer can optionally be marked as company_tax_exempt, which affects tax calculations on orders. Setting company_tax_exempt to true through the normal create/update endpoints requires a company_vat_id that passes VAT validation for the customer's country - if validation fails or no VAT ID is set, the request is rejected.
Tax Exemption Override
An Admin can grant tax exemption without a validated VAT ID via POST /customers/{customer_id}/tax-exempt-override, by providing a reason. This bypasses VAT validation and is recorded in an audit log together with who granted it, when, and why. The customer is notified by email that their account was marked tax-exempt. This endpoint cannot be called with a Service account.
The full history of tax exemption checks for a customer - both automated VAT validation attempts and manual overrides - can be retrieved via GET /customers/{customer_id}/tax-exempt-checks (list) and GET /customers/{customer_id}/tax-exempt-checks/{check_id} (single entry). These are also Admin-only.
Good to know
Email Uniqueness
Email addresses are unique per service, not globally. The same email can exist as a customer in multiple services.
Credit Balance
When a customer is created, a Credit Balance with 0.00 is automatically set up.
External Sync
When you update a customer, TiruPay automatically syncs the changes to your configured invoicing provider and payment processor. No need to update them separately.
Deleting a Customer
Deleting a customer also deletes their Credit Balance. Make sure the customer has no active orders or subscriptions before deleting.
Linking Customers to Users
Customers can (and should) be linked to user accounts so that end users can view their own customer data through the User API. A user and customer must belong to the same service to be linked.
Unlinking a customer from a user only removes the relationship - it does not delete the customer.
Relationships
A customer is connected to several other parts of TiruPay:
- Orders - A customer can have multiple orders and subscriptions.
- Balances - Each customer can have multiple service-specific balances and always has a global Credit Balance.
- Payments - Customers can have payment mandates for recurring payments (e.g. SEPA, PayPal).
- Users - End-user accounts can be linked to customers for self-service access.