Create Customer

Creates a new customer for your merchant account.

Endpoint

POST /v1/customers

Authentication

Requires API key authentication via X-API-Key header.

For JWT authentication, use POST /v1/customers/jwt instead.

Request Body

Parameter	Type	Required	Description
email	string	Yes	Customer's email address (must be unique per merchant)
name	string	Yes	Customer's full name
phone	string	No	Customer's phone number
address	object	No	Customer's address
address.line1	string	No	Street address line 1
address.line2	string	No	Street address line 2
address.city	string	No	City
address.state	string	No	State or province
address.postalCode	string	No	Postal or ZIP code
address.country	string	No	Two-letter country code
companyName	string	No	Company name (for B2B)
taxId	string	No	Tax ID or VAT number
description	string	No	Internal description or notes
metadata	object	No	Arbitrary key-value pairs

Example Request

curl -X POST https://api.example.com/v1/customers \
  -H "X-API-Key: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "[phone]",
    "address": {
      "line1": "123 Main St",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US"
    },
    "companyName": "Acme Inc",
    "metadata": {
      "tier": "gold"
    }
  }'

Example Response

{
  "id": "cus_abc123def456",
  "object": "customer",
  "email": "[email protected]",
  "name": "John Doe",
  "phone": "[phone]",
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US"
  },
  "companyName": "Acme Inc",
  "taxId": null,
  "description": null,
  "metadata": {
    "tier": "gold"
  },
  "created": 1706554800,
  "updated": 1706554800
}

Errors

Code	Description
400	Invalid request body or missing required fields
401	Invalid or missing API key
409	Customer with this email already exists for this merchant