Merchants
Create Merchant
Create a new merchant during onboarding. This endpoint is only available via session authentication, not API keys. Rejects requests when a merchant already exists for the user.
Authorization
bearerAuth AuthorizationBearer <token>
Use your secret API key as the bearer token
In: header
Request Body
application/json
legalName*string
Legal business name
displayName?string
Display name
taxId?string|null
Tax identifier
websiteUrl?string|null
Business website URL
supportEmail?string|null
Support contact email
Format
emailbillingEmail?string|null
Billing contact email
Format
emailphoneNumber?string|null
Contact phone number
addressLine1*string
Address line 1
addressLine2?string|null
Address line 2
city*string
stateProvince?string|null
postalCode*string
country*string
ISO 2-letter country code
defaultCurrency?string
Default currency code
Default
"USD"timezone?string
Default timezone
Default
"UTC"isDemo?boolean
Whether this is a demo merchant
Default
falseResponse Body
application/json
application/json
application/json
application/json
curl -X POST "https://api.getlumen.dev/v1/merchants/onboarding-create-merchant" \ -H "Content-Type: application/json" \ -d '{ "legalName": "Acme Inc.", "displayName": "Acme", "websiteUrl": "https://acme.com", "supportEmail": "support@acme.com", "billingEmail": "billing@acme.com", "phoneNumber": "+1-415-555-1234", "addressLine1": "123 Market St", "city": "San Francisco", "stateProvince": "CA", "postalCode": "94105", "country": "US", "defaultCurrency": "USD", "timezone": "America/Los_Angeles", "isDemo": false }'{
"id": "mer_7X2FxYk1zv3p4LqB0sDn",
"legalName": "Acme Inc.",
"displayName": "Acme",
"organizationId": "org_3c8a9f7b",
"userId": "user_9d5f2e1c",
"addressLine1": "123 Market St",
"city": "San Francisco",
"postalCode": "94105",
"country": "US",
"defaultCurrency": "USD",
"createdAt": "2025-02-20T18:12:11.123Z"
}{
"error": "Merchant already exists"
}{
"error": "Merchant creation is not allowed via API keys"
}{
"error": "Internal server error"
}