Customers
Customers represent your buyers—the people who place orders and make payments. Each customer has a unique identifier, contact details, and optional metadata you control. Once created, you can reference customers when creating orders, tokenizing payment methods, and tracking purchase history.
The customer object
A customer object stores profile information tied to a buyer in your application. You can create customers inline during order creation or save them independently for repeat transactions and subscription flows.
All text fields have character limits to ensure consistent display across invoices, receipts, and payment confirmations. The limits balance practical needs—accommodating most real-world names and contact details—with constraints from payment networks, banking systems, and user interface layouts. Email addresses follow RFC 5321 standards (254 characters maximum), while phone numbers accommodate international formats without excessive padding. Reference fields are sized for typical internal identifiers and external system IDs.
Properties
Create customer
Create a new customer profile. Save customers before order creation to enable faster checkouts, subscription billing, and order history tracking. Once created, reference the customer ID when creating orders or tokenizing payment methods.
Use cases
- Account creation: Save customer during signup or registration
- Guest checkout conversion: Create profile after first purchase to enable saved payment methods
- Subscription onboarding: Create customer before collecting payment details
- CRM integration: Sync customers from external systems using the
referencefield
Required attributes
Optional attributes
Request
curl https://api.zebo.dev/customers/create \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Mensah",
"email_address": "jane@example.com",
"phone_number": "+233242057831",
"reference": "user_123456",
"custom_data": {
"loyalty_tier": "gold",
"account_manager": "am_789"
}
}'
Response
{
"customer": {
"id": "cu_a1b2c3d4e5",
"name": "Jane Mensah",
"email_address": "jane@example.com",
"phone_number": "+233242057831",
"reference": "user_123456",
"custom_data": {
"loyalty_tier": "gold",
"account_manager": "am_789"
},
"created_at": "2025-11-23T14:30:00Z"
}
}
Lookup customer
Retrieve a customer by ID. Use this to fetch profile details, verify customer existence before order creation, or display customer information in your application.
Use cases
- Profile display: Show customer details in account settings or dashboards
- Pre-checkout validation: Verify customer exists before creating an order
- Order history: Retrieve customer data to display alongside past orders
- Webhook processing: Fetch full customer details when handling order or payment events
Required attributes
Request
curl https://api.zebo.dev/customers/lookup \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cu_a1b2c3d4e5"
}'
Response
{
"customer": {
"id": "cu_a1b2c3d4e5",
"name": "Jane Mensah",
"title": "Ms.",
"email_address": "jane@example.com",
"phone_number": "+233242057831",
"reference": "user_123456",
"custom_data": {
"loyalty_tier": "gold",
"account_manager": "am_789"
},
"created_at": "2025-11-23T14:30:00Z"
}
}
Error responses
Customer not found (404)
Returned when the customer ID doesn't exist or has been deleted.
{
"error": {
"message": "customer not found",
"detail": "the customer you're looking for does not exist or has been deleted",
"code": "1234",
"url": "https://commerce.zebo.dev/e/1234"
}
}