> ## Documentation Index
> Fetch the complete documentation index at: https://chariow.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Customers

> Learn how to manage and retrieve customer data via the Chariow API

Customers are created automatically when they make a purchase in your store. Each customer is specific to your store and has their own profile with contact information, purchase history, and product access.

## Customer Object

A customer object contains the following information:

```json theme={null}
{
  "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:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/customers" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

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

  const result = await response.json();
  ```

  ```python Python theme={null}
  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']
  ```
</CodeGroup>

### Query Parameters

| Parameter    | Type    | Description                                                      |
| ------------ | ------- | ---------------------------------------------------------------- |
| `per_page`   | integer | Number of customers per page (default: 15, max: 100)             |
| `cursor`     | string  | Cursor for pagination (use `next_cursor` from previous response) |
| `search`     | string  | Search by name, email, or phone number                           |
| `start_date` | string  | Filter customers created from this date (Y-m-d format)           |
| `end_date`   | string  | Filter customers created until this date (Y-m-d format)          |

### Searching Customers

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

```bash theme={null}
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:

```bash theme={null}
curl -X GET "https://api.chariow.com/v1/customers?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer sk_live_your_api_key"
```

### Example Response

```json theme={null}
{
  "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": {
    "next_cursor": "eyJpZCI6NTB9",
    "prev_cursor": null,
    "has_more": true
  }
}
```

## Getting a Single Customer

Retrieve a specific customer by their public ID:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.chariow.com/v1/customers/cus_abc123" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```
</CodeGroup>

## Customer Lifecycle

<Steps>
  <Step title="Customer Created">
    A new customer record is created when they make their first purchase.
  </Step>

  <Step title="Purchase Recorded">
    Each purchase is linked to the customer's profile.
  </Step>

  <Step title="Access Granted">
    The customer receives access to their purchased products (downloads, courses, licenses).
  </Step>

  <Step title="Portal Access">
    Customers can access the customer portal to view their purchases and downloads.
  </Step>
</Steps>

## Common Use Cases

<AccordionGroup>
  <Accordion title="CRM Integration" icon="address-book">
    Sync customers to your CRM by fetching new customers using date filters:

    ```javascript theme={null}
    // 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?start_date=${yesterday}&end_date=${today}`,
      { headers: { 'Authorization': 'Bearer sk_live_your_api_key' }}
    );

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

  <Accordion title="Email Marketing" icon="envelope">
    Add customers to your email lists based on their purchases:

    ```javascript theme={null}
    // 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']
    });
    ```
  </Accordion>

  <Accordion title="Customer Lookup" icon="magnifying-glass">
    Look up a customer by email when they contact support:

    ```bash theme={null}
    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 name, email, and phone number fields.
  </Accordion>

  <Accordion title="Monthly Reports" icon="chart-line">
    Generate monthly customer acquisition reports using date filters:

    ```bash theme={null}
    curl -X GET "https://api.chariow.com/v1/customers?start_date=2025-01-01&end_date=2025-01-31&per_page=100" \
      -H "Authorization: Bearer sk_live_your_api_key"
    ```

    This retrieves all customers who made their first purchase in January 2025.
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Sales Guide" icon="receipt" href="/en/guides/sales">
    View customer purchase history
  </Card>

  <Card title="Licenses Guide" icon="key" href="/en/guides/licenses">
    Manage customer licenses
  </Card>

  <Card title="Customers API" icon="code" href="/api-reference/customers/list-customers">
    View the complete Customers API reference
  </Card>
</CardGroup>