Manage customers

A customer record ties a person's identity—name, email, phone number—to their order history and saved payment methods. Attaching customers to orders gives you a reliable identity anchor for repeat purchases, fraud signals, customer service lookups, and personalized checkout experiences. This guide shows you how to create customers, look them up, and use customer IDs in orders.

Prerequisites

• A Commerce API key configured in your environment
• Understanding of orders and how customer_data works in order creation

Create a customer

Create a customer record with at minimum a name and one contact method (email or phone). Commerce uses the phone number as the delivery channel for OTP verification during mobile money payments, so include it whenever you expect the customer to pay with mobile money.

curl https://api.zebo.dev/customers/create \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gloria Kesewaa",
    "email_address": "gloria@kesewaa.co",
    "phone_number": "+233544998605"
  }'

Store the returned customer.id (cu_…) in your own database, associated with your user record. You'll pass it in future orders to link purchases to this customer.

Look up a customer

Retrieve a customer record by ID to verify their details, display order history context, or check which payment methods they have saved.

curl https://api.zebo.dev/customers/lookup \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn"}'

Attach customers to orders

Pass the customer ID in customer_data.customer_id when creating an order. Commerce links the order to that customer record and populates the order's customer object with their name, email, and phone—which appears on invoices, in the dashboard, and in order list responses.

{
  "customer_data": {
    "customer_id": "cu_ewoa27qe7aO4GZouasUSmVXILsmxjR0Hc6lCMBkn"
  },
  "line_items": [
    {
      "price_id": "pri_abc123",
      "quantity": 1
    }
  ]
}

Attaching a customer to an order is how repeat-purchase flows work. The customer's saved payment methods become available for selection at checkout—so returning customers don't need to re-enter their mobile money number or card details each time.

See Charge repeat customers for the complete saved-payment-method flow.

Page through customers

Retrieve paginated customer records for reporting, syncing, or building an admin view of your customer base.

curl https://api.zebo.dev/customers/page \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page_number": 1,
    "page_size": 50
  }'

Related resources

• Customers API — Full reference for create, lookup, and page endpoints
• Charge repeat customers — Tokenize payment methods and charge customers without re-entering details
• Accept a payment — Full order creation flow with customer data