Customers

Customers are created automatically when they check out in your store, including through the Checkout API. Each customer is specific to your store and has their own profile with contact information, purchase history, and product access.

Your store has one customer per email address. Emails are stored in lowercase and compared case-insensitively, so a buyer who types John@Example.com and later john@example.com is the same customer. Each new checkout with that email updates the customer’s first name, last name and phone number. Customers that had been duplicated in the past were merged into the oldest record: its ID is kept, the sales of the duplicates now belong to it, and the IDs of the merged duplicates return 404.

Customer Object

A customer object contains the following information:

{
  "id": "cus_abc123xyz",
  "name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "avatar_url": "https://cdn.chariow.com/avatars/abc123.jpg",
  "phone": {
    "number": "+1 234 567 890",
    "country": {
      "name": "United States",
      "code": "US",
      "alpha_3_code": "USA",
      "dial_code": "+1",
      "currency": "USD",
      "flag": "🇺🇸"
    }
  },
  "store": {
    "id": "str_xyz789",
    "name": "My Digital Store",
    "logo_url": "https://cdn.chariow.com/stores/xyz789/logo.png",
    "url": "https://mystore.chariow.link"
  },
  "created_at": "2025-01-15T10:30:00+00:00",
  "updated_at": "2025-01-20T14:45:00+00:00"
}

Customer Properties

Property	Type	Description
`id`	string	Unique customer identifier with `cus_` prefix
`name`	string	Full name (combination of first and last name)
`first_name`	string	Customer’s first name
`last_name`	string	Customer’s last name
`email`	string	Customer’s email address
`avatar_url`	string	URL to the customer’s avatar image
`phone`	object	Phone number with country information
`store`	object	Store the customer belongs to
`created_at`	string	ISO 8601 timestamp of when the customer was created
`updated_at`	string	ISO 8601 timestamp of when the customer was last updated

Listing Customers

Retrieve all customers for your store:

curl -X GET "https://api.chariow.com/v1/customers" \
  -H "Authorization: Bearer sk_live_your_api_key"

const response = await fetch('https://api.chariow.com/v1/customers', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

const result = await response.json();

import requests

response = requests.get(
    'https://api.chariow.com/v1/customers',
    headers={'Authorization': 'Bearer sk_live_your_api_key'}
)

result = response.json()
customers = result['data']

Query Parameters

Parameter	Type	Description
`per_page`	integer	Number of customers per page (default: 10, from 1 to 100)
`cursor`	string	Cursor for pagination (use `next_cursor` from previous response)
`search`	string	Search by first name, last name, email or phone number
`from`	string	Customers created on or after this date (Y-m-d format)
`to`	string	Customers created on or before this date (Y-m-d format)
`period`	string	Date range shortcut used instead of `from` and `to`: `today`, `yesterday`, `last7days`, `last30days`, `thisWeek`, `lastWeek`, `thisMonth`, `lastMonth`, `thisYear`, `lastYear`

start_date and end_date are not supported and are silently ignored, which returns customers of every date. Use from and to.

Searching Customers

Search for customers by first name, last name, email or phone number:

curl -X GET "https://api.chariow.com/v1/customers?search=john" \
  -H "Authorization: Bearer sk_live_your_api_key"

Filtering by Date Range

Retrieve customers created within a specific date range:

curl -X GET "https://api.chariow.com/v1/customers?from=2025-01-01&to=2025-01-31" \
  -H "Authorization: Bearer sk_live_your_api_key"

Example Response

{
  "data": [
    {
      "id": "cus_abc123xyz",
      "name": "John Doe",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "avatar_url": "https://cdn.chariow.com/avatars/abc123.jpg",
      "phone": {
        "number": "+1 234 567 890",
        "country": {
          "name": "United States",
          "code": "US",
          "alpha_3_code": "USA",
          "dial_code": "+1",
          "currency": "USD",
          "flag": "🇺🇸"
        }
      },
      "store": {
        "id": "str_xyz789",
        "name": "My Digital Store",
        "logo_url": "https://cdn.chariow.com/stores/xyz789/logo.png",
        "url": "https://mystore.chariow.link"
      },
      "created_at": "2025-01-15T10:30:00+00:00",
      "updated_at": "2025-01-20T14:45:00+00:00"
    }
  ],
  "pagination": {
    "per_page": 10,
    "next_cursor": "eyJpZCI6NTB9",
    "prev_cursor": null,
    "has_more_pages": true
  }
}

Getting a Single Customer

Retrieve a specific customer by their public ID:

curl -X GET "https://api.chariow.com/v1/customers/cus_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"

const response = await fetch('https://api.chariow.com/v1/customers/cus_abc123', {
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key'
  }
});

const result = await response.json();

Customer Lifecycle

Customer Created

A customer record is created at their first checkout, before the payment is confirmed. A buyer who abandons the payment is therefore still listed as a customer.

Purchase Recorded

Each purchase is linked to the customer’s profile.

Access Granted

The customer receives access to their purchased products (downloads, courses, licenses).

Portal Access

Customers can access the customer portal to view their purchases and downloads.

Common Use Cases

CRM Integration

Sync customers to your CRM by fetching new customers using date filters:

// Fetch customers created in the last 24 hours
const today = new Date().toISOString().split('T')[0];
const yesterday = new Date(Date.now() - 86400000).toISOString().split('T')[0];

const response = await fetch(
  `https://api.chariow.com/v1/customers?from=${yesterday}&to=${today}`,
  { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
);

const result = await response.json();
// Sync result.data to your CRM

Email Marketing

Add customers to your email lists based on their purchases:

// Get customer details for email list
const response = await fetch(
  'https://api.chariow.com/v1/customers/cus_abc123xyz',
  { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
);

const result = await response.json();

await addToMailingList({
  email: result.data.email,
  firstName: result.data.first_name,
  lastName: result.data.last_name,
  tags: ['customer', 'purchased']
});

Customer Lookup

Look up a customer by email when they contact support:

curl -X GET "https://api.chariow.com/v1/customers?search=customer@example.com" \
  -H "Authorization: Bearer sk_live_your_api_key"

The search parameter matches against the first name, last name, email and phone number fields.

Monthly Reports

Generate monthly customer acquisition reports using date filters:

curl -X GET "https://api.chariow.com/v1/customers?from=2025-01-01&to=2025-01-31&per_page=100" \
  -H "Authorization: Bearer sk_live_your_api_key"

This retrieves all customers created in January 2025.

Sales Guide

View customer purchase history

Licenses Guide

Manage customer licenses

Customers API

View the complete Customers API reference

Introduction

Guides

MCP Integration

n8n Integration

Resources

Customer Object

Customer Properties

Listing Customers

Query Parameters

Searching Customers

Filtering by Date Range

Example Response

Getting a Single Customer

Customer Lifecycle

Common Use Cases

Sales Guide

Licenses Guide

Customers API

​Customer Object

​Customer Properties

​Listing Customers

​Query Parameters

​Searching Customers

​Filtering by Date Range

​Example Response

​Getting a Single Customer

​Customer Lifecycle

​Common Use Cases

​Related Resources

Sales Guide

Licenses Guide

Customers API

Customer Object

Customer Properties

Listing Customers

Query Parameters

Searching Customers

Filtering by Date Range

Example Response

Getting a Single Customer

Customer Lifecycle

Common Use Cases

Related Resources