Create Customer
Create a new customer record. Email is required unless dangerouslyAllowCustomerWithoutEmail is true. Enforces email uniqueness unless dangerouslyAllowSameEmailForDifferentCustomers is true. Automatically links to payment provider if pspCustomerId is provided.
Authorization
bearerAuth Use your secret API key as the bearer token
In: header
Request Body
application/json
Customer name (required)
Customer email (required unless dangerouslyAllowCustomerWithoutEmail is true)
emailCustomer phone number
Your application's user ID (e.g., Supabase user ID)
Existing payment provider customer ID to link (e.g., Stripe cus_*)
Billing address line 1
Billing address line 2
Billing city
Billing state or province
Billing postal/ZIP code
Billing country (ISO 3166-1 alpha-2 code)
Business name for B2B customers
Tax ID / VAT number
Whether customer is exempt from taxes
Reason for tax exemption
URL or reference to tax exemption certificate
Reference to merchant's manual tax rate definition
Tax calculation override: 'auto' or 'manual'
"auto" | "manual"Custom invoice number prefix
length <= 20ISO 639-1 language code
"en"IANA timezone identifier
"UTC"ISO 4217 currency code
"USD"Custom key-value metadata
Bypass email requirement (use with caution)
falseAllow duplicate emails across customers (use with caution)
falseResponse Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.getlumen.dev/v1/customers" \ -H "Content-Type: application/json" \ -d '{ "externalCustomerId": "user_ext_abc123", "name": "Jane Doe", "email": "jane@example.com", "phoneNumber": "+1234567890", "billingAddressLine1": "123 Main St", "billingCity": "San Francisco", "billingStateProvince": "CA", "billingPostalCode": "94102", "billingCountry": "US", "preferredCurrency": "USD", "timezone": "America/Los_Angeles", "metadata": { "internalUserId": "12345" } }'{
"customer": {
"id": "cus_01hrwzqrz4ytkwv07syv8k7g3z",
"merchantId": "mrc_01hptv3p6xj173pfv96pxd5pke",
"externalCustomerId": "user_ext_abc123",
"name": "Jane Doe",
"email": "jane@example.com",
"phoneNumber": "+1234567890",
"pspCustomerId": null,
"billingCountry": "US",
"preferredCurrency": "USD",
"timezone": "America/Los_Angeles",
"createdAt": "2025-02-20T16:05:23.412Z"
}
}{
"error": "Email is required"
}{
"error": "A customer with this email already exists"
}{
"error": "string",
"details": "string"
}