LogoZebo Studio

Customers

Customers represent the buyers you identify and reuse across Commerce flows. A customer record gives you a stable customer ID for orders, saved payment methods, receipts, and your own internal reconciliation.

Create supports idempotency: a successful response can be replayed with the same idempotency key and request body for 24 hours. Lookup and page do not opt in to idempotent replay.

The customer object

A customer object stores the profile data Commerce knows about a buyer. Optional fields are omitted when they have no value.

Properties

  • billing_addressobjectBilling address saved on the customer when available.Click or tap to expand
    • Name
      city
      Type
      string
      Description
      City or town.
    • Name
      country
      Type
      string
      Description
      Two-letter ISO country code.
    • Name
      line1
      Type
      string
      Description
      Street address line 1.
    • Name
      line2
      Type
      string
      Description
      Street address line 2.
    • Name
      name
      Type
      string
      Description
      Recipient name for this address.
    • Name
      phone_number
      Type
      string
      Description
      Contact phone number for this address.
    • Name
      post_code
      Type
      string
      Description
      Postal or ZIP code.
    • Name
      region
      Type
      string
      Description
      State, province, or region.
  • Name
    created_at
    Type
    timestamp
    Description

    When the customer record was created.

  • Name
    custom_data
    Type
    object
    Description

    Your own key-value metadata for the customer.

  • Name
    email_address
    Type
    string
    Description

    Customer email address when one has been provided.

  • Name
    guest
    Type
    boolean
    Description

    Whether this customer was created as a guest through checkout.

  • Name
    id
    Type
    string
    Description

    Unique identifier for this customer.

  • Name
    name
    Type
    string
    Description

    Customer full name.

  • Name
    phone_number
    Type
    string
    Description

    Customer phone number when one has been provided.

  • Name
    reference
    Type
    string
    Description

    Your own external reference for the customer.

  • shipping_addressobjectShipping address saved on the customer when available.Click or tap to expand
    • Name
      city
      Type
      string
      Description
      City or town.
    • Name
      country
      Type
      string
      Description
      Two-letter ISO country code.
    • Name
      line1
      Type
      string
      Description
      Street address line 1.
    • Name
      line2
      Type
      string
      Description
      Street address line 2.
    • Name
      name
      Type
      string
      Description
      Recipient name for this address.
    • Name
      phone_number
      Type
      string
      Description
      Contact phone number for this address.
    • Name
      post_code
      Type
      string
      Description
      Postal or ZIP code.
    • Name
      region
      Type
      string
      Description
      State, province, or region.
  • Name
    suffix
    Type
    string
    Description

    Name suffix such as Jr. or III.

  • Name
    title
    Type
    string
    Description

    Title or honorific such as Dr. or Ms..

  • Name
    updated_at
    Type
    timestamp
    Description

    When the customer was last updated.

Create customer

Create a reusable customer record. Use this when you want a stable customer ID before you create orders, save payment methods, or attach your own customer reference.

Required attributes

  • Name
    name
    Type
    string
    Description

    Required customer name field. The current parser trims the value and accepts up to 200 characters.

Optional attributes

  • billing_addressobjectBilling address. country is required when the object is provided.Click or tap to expand
    • Name
      city
      Type
      string
      Description
      City or town.
    • Name
      country
      Type
      string
      Description
      Country; required within the address.
    • Name
      line1
      Type
      string
      Description
      Street address line 1.
    • Name
      line2
      Type
      string
      Description
      Street address line 2.
    • Name
      name
      Type
      string
      Description
      Recipient name.
    • Name
      phone_number
      Type
      string
      Description
      Contact phone number.
    • Name
      post_code
      Type
      string
      Description
      Postal or ZIP code.
    • Name
      region
      Type
      string
      Description
      State, province, or region.
  • Name
    custom_data
    Type
    object
    Description

    Key-value metadata for your own internal use. Both keys and values must be strings.

  • Name
    email_address
    Type
    string
    Description

    Customer email address. Must be between 3 and 254 characters when provided.

  • Name
    phone_number
    Type
    string
    Description

    Customer phone number. Must be between 7 and 20 characters when provided.

  • Name
    reference
    Type
    string
    Description

    Your external reference for this customer. Must be between 1 and 100 characters when provided.

  • shipping_addressobjectShipping address. country is required when the object is provided.Click or tap to expand
    • Name
      city
      Type
      string
      Description
      City or town.
    • Name
      country
      Type
      string
      Description
      Country; required within the address.
    • Name
      line1
      Type
      string
      Description
      Street address line 1.
    • Name
      line2
      Type
      string
      Description
      Street address line 2.
    • Name
      name
      Type
      string
      Description
      Recipient name.
    • Name
      phone_number
      Type
      string
      Description
      Contact phone number.
    • Name
      post_code
      Type
      string
      Description
      Postal or ZIP code.
    • Name
      region
      Type
      string
      Description
      State, province, or region.
  • Name
    suffix
    Type
    string
    Description

    Name suffix such as Jr.. Must be between 1 and 10 characters when provided.

  • Name
    title
    Type
    string
    Description

    Title or honorific such as Dr.. Must be between 1 and 20 characters when provided.

Response shape

  • The response returns a top-level customer object.
  • The created customer includes id, name, and created_at.
  • Billing and shipping addresses are accepted and returned when provided.
  • Optional fields are returned only when they have values.

Request

POST
/customers/create
curl https://api.zebo.dev/customers/create \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Mensah",
    "title": "Ms.",
    "reference": "user_123456",
    "email_address": "[email protected]",
    "phone_number": "+233242057831",
    "custom_data": {
      "loyalty_tier": "gold",
      "account_manager": "am_789"
    }
  }'

{
  "customer": {
    "id": "cu_a1b2c3d4e5",
    "name": "Jane Mensah",
    "title": "Ms.",
    "email_address": "[email protected]",
    "phone_number": "+233242057831",
    "reference": "user_123456",
    "custom_data": {
      "loyalty_tier": "gold",
      "account_manager": "am_789"
    },
    "guest": false,
    "billing_address": {
      "name": "Jane Mensah",
      "phone_number": "+233242057831",
      "line1": "23 Adenta High Street",
      "line2": "East Legon Hills",
      "city": "Accra",
      "region": "Greater Accra",
      "post_code": "GA-422-1134",
      "country": "GH"
    },
    "created_at": "2025-11-23T14:30:00Z",
    "updated_at": null
  }
}

Lookup customer

Fetch one customer by ID. Use this when you need the full customer object before creating an order, showing account details, or reconciling customer activity in your own system.

Required attributes

  • Name
    customer_id
    Type
    string
    Description

    Customer identifier, with or without the cu_ prefix.

Response shape

  • The response returns a top-level customer object.
  • The object can include billing and shipping addresses when they exist on the customer record.
  • Optional fields are omitted when they are not set.

Request

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

{
  "customer": {
    "id": "cu_a1b2c3d4e5",
    "name": "Jane Mensah",
    "title": "Ms.",
    "email_address": "[email protected]",
    "phone_number": "+233242057831",
    "reference": "user_123456",
    "guest": false,
    "billing_address": {
      "name": "Jane Mensah",
      "phone_number": "+233242057831",
      "line1": "23 Adenta High Street",
      "line2": "East Legon Hills",
      "city": "Accra",
      "region": "Greater Accra",
      "post_code": "GA-422-1134",
      "country": "GH"
    },
    "shipping_address": {
      "name": "Jane Mensah",
      "phone_number": "+233242057831",
      "line1": "23 Adenta High Street",
      "line2": "East Legon Hills",
      "city": "Accra",
      "region": "Greater Accra",
      "post_code": "GA-422-1134",
      "country": "GH"
    },
    "custom_data": {
      "loyalty_tier": "gold",
      "account_manager": "am_789"
    },
    "created_at": "2025-11-23T14:30:00Z",
    "updated_at": "2025-11-24T08:00:00Z"
  }
}

Page through customers

List customers for the authenticated application. Results are sorted by created_at in descending order, so page 1 contains the newest customer records.

Request attributes

  • Name
    page_number
    Type
    integer
    Description

    1-based page index to fetch. Must be between 1 and 10.

  • Name
    page_size
    Type
    integer
    Description

    Number of customers to return. Must be between 1 and 256. Defaults to 256 when omitted.

Response shape

  • The top-level page object includes number, size, and customers.
  • Each entry in customers is a full customer object.
  • Optional customer fields appear only when they are set.

Request

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

{
  "page": {
    "number": 1,
    "size": 2,
    "customers": [
      {
        "id": "cu_a1b2c3d4e5",
        "name": "Jane Mensah",
        "email_address": "[email protected]",
        "phone_number": "+233242057831",
        "reference": "user_123456",
        "guest": false,
        "billing_address": {
          "name": "Jane Mensah",
          "phone_number": "+233242057831",
          "line1": "23 Adenta High Street",
          "line2": "East Legon Hills",
          "city": "Accra",
          "region": "Greater Accra",
          "post_code": "GA-422-1134",
          "country": "GH"
        },
        "custom_data": {
          "loyalty_tier": "gold"
        },
        "created_at": "2025-11-23T14:30:00Z"
      },
      {
        "id": "cu_f6g7h8i9j0",
        "name": "Kojo Asante",
        "title": "Mr.",
        "phone_number": "+233201234567",
        "guest": true,
        "created_at": "2025-11-22T09:15:00Z",
        "updated_at": "2025-11-24T11:05:00Z"
      }
    ]
  }
}

Was this page helpful?