v1
latestOpenAPI 3.1.02026-07-2684271522.2 KBCustomers
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/v1/customers
Request body
Example request
{
"customer": {
"first_name": "John",
"last_name": "Doe",
"email": "joh.doe@example.com",
"phone": "+15555555555",
"employer": "Flex",
"shipping": {},
"checkout_session_id": "fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
"metadata": "{\"key\": \"value\"}"
}
}Response
An envelope wrapping a single customer object.
Example response
{
"customer": {
"customer_id": "fcus_01HACM7FZ1084XB1GB6053VM0D",
"owner_partner_id": "obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA",
"first_name": "John",
"last_name": "Doe",
"email": "joh.doe@example.com",
"phone": "+15555555555",
"employer": "Flex",
"shipping": {},
"metadata": {
"order_id": "8842",
"channel": "shopify"
},
"created_at": "2026-06-15T14:30:00Z",
"test_mode": false
}
}