Skip to main content
POST
/
customers
Create customer
curl --request POST \
  --url https://api.lava.so/v1/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reference_id": "usr_abc123",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+14155552671",
  "metadata": {
    "tier": "premium",
    "source": "api"
  }
}
'
{
  "customer_id": "con_test_01EXAMPLE00000000000000001",
  "reference_id": "usr_abc123",
  "contact": {
    "phone": "+14155552671",
    "email": "user@example.com",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "subscription": {
    "subscription_id": "<string>",
    "plan_id": "<string>",
    "name": "<string>",
    "status": "active"
  },
  "metadata": {
    "plan_tier": "enterprise",
    "internal_id": "12345"
  },
  "created_at": "2023-05-15T08:35:42Z"
}

Authorizations

​
Authorization
string
header
required

Bearer token authentication used for standard API calls. Format: 'Bearer YOUR_API_KEY'

Body

application/json
​
reference_id
string

Your external identifier for this customer (strongly recommended). When provided, acts as an idempotency key — creating a customer with the same reference_id returns the existing one. Cannot start with "con_" (reserved prefix). Can be used interchangeably with customer_id in all API endpoints.

Maximum string length: 255
Example:

"usr_abc123"

​
name
string

Display name. Used as contact hint until the customer authenticates.

Maximum string length: 255
Example:

"Jane Smith"

​
email
string<email>

Email address. Used as contact hint and for checkout pre-population.

Example:

"jane@example.com"

​
phone
string

Phone number in E.164 format. Used as contact hint and for checkout pre-population.

Example:

"+14155552671"

​
metadata
object

Arbitrary key-value metadata (max 16KB serialized).

Example:
{ "tier": "premium", "source": "api" }

Response

Customer created

​
customer_id
string
required

Unique identifier for the customer

Example:

"con_test_01EXAMPLE00000000000000001"

​
reference_id
string | null
required

Merchant's external identifier for this customer. Used for idempotent creation — POST with the same reference_id returns the existing customer.

Example:

"usr_abc123"

​
contact
object
required
​
subscription
object
required

Active subscription summary, or null if none

​
metadata
object
required

Arbitrary key-value metadata stored on the customer. Set via PATCH.

Example:
{
  "plan_tier": "enterprise",
  "internal_id": "12345"
}
​
created_at
string<date-time>
required

ISO 8601 timestamp when the customer was created

Example:

"2023-05-15T08:35:42Z"