Create or update a customer
Create or update a customer
Creates a customer. This endpoint upserts by email: if a customer with the same email already exists, that customer is updated with the supplied values instead of a new one being created. A customer.created webhook event is fired only when a new customer is created (not on update). If checkout_session_id is provided, the referenced checkout session is updated to reference this customer.
POST
Create or update a customer
Authorizations
Use a Bearer token to access this API.
Body
application/json
An envelope wrapping a single customer object.
An envelope wrapping a single customer object.
The customer.
Example:
{
"first_name": "John",
"last_name": "Doe",
"email": "joh.doe@example.com",
"phone": "+15555555555",
"employer": "Flex",
"shipping": {
"line1": "123 Main St",
"line2": "Suite 100",
"city": "San Francisco",
"state": "CA",
"postal_code": "94107",
"country": "US"
},
"checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
"metadata": "{\"key\": \"value\"}"
}Response
Success
An envelope wrapping a single customer object.
The customer.
Example:
{
"customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D",
"first_name": "John",
"last_name": "Doe",
"email": "joh.doe@example.com",
"phone": "+15555555555",
"employer": "Flex",
"shipping": {
"shipping_address_id": "fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
"line1": "123 Main St",
"line2": "Suite 100",
"city": "San Francisco",
"state": "CA",
"postal_code": "94107",
"country": "US"
},
"metadata": { "order_id": "8842", "channel": "shopify" },
"created_at": "2026-06-15T14:30:00Z",
"test_mode": false
}