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

# List Customers

> Retrieve and filter a paginated list of customers

Retrieve a list of customers with support for pagination, filtering, and sorting.

## Endpoint

```bash theme={null}
GET /customers
```

## Query Parameters

<ParamField query="limit" type="integer" default="15">
  Number of records to return per page (max: 100)
</ParamField>

<ParamField query="after" type="string">
  Cursor for fetching next page of results
</ParamField>

<ParamField query="before" type="string">
  Cursor for fetching previous page of results
</ParamField>

<ParamField query="email" type="string">
  Filter customers by email address
</ParamField>

<ParamField query="created_after" type="string">
  Filter customers created after this timestamp (ISO 8601)
</ParamField>

<ParamField query="created_before" type="string">
  Filter customers created before this timestamp (ISO 8601)
</ParamField>

<ParamField query="sort" type="string" default="created_at:desc">
  Sort order for results (created\_at:asc|created\_at:desc)
</ParamField>

## Response Format

<ResponseField name="data" type="Customer[]">
  Array of customer objects. See [Customer Object](#customer-object) for structure.
</ResponseField>

<ResponseField name="pagination" type="object">
  <ResponseField name="before" type="string">
    Cursor for the previous page
  </ResponseField>

  <ResponseField name="after" type="string">
    Cursor for the next page
  </ResponseField>

  <ResponseField name="limit" type="integer">
    Number of records per page
  </ResponseField>
</ResponseField>

## Examples

### Basic List Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.spendjuice.com/customers?limit=2" \
    -H "Authorization:  YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const juice = require('juice-node');
  const client = new juice('YOUR_API_KEY');

  const customers = await client.customers.list({
    limit: 2
  });
  ```

  ```python Python theme={null}
  import juice
  juice.api_key = 'YOUR_API_KEY'

  customers = juice.Customer.list(
    limit=2
  )
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": [
    {
      "id": "6f7e1e7f-93d1-4fcc-b7a4-738f869615c8",
      "first_name": "Test",
      "last_name": "Customer",
      "email": "test@custom.er",
      "phone_number": "+2348012345678",
      "billing_address": {
        "line1": "123 Test lane",
        "line2": "356 Mike Drive",
        "city": "Anon",
        "state": "Acme",
        "zip_code": "12345",
        "country": "US"
      },
      "created_at": "2024-03-01T12:00:00Z",
      "updated_at": "2024-03-01T12:00:00Z"
    },
    {
      "id": "7a8b9c0d-1e2f-3g4h-5i6j-7k8l9m0n1o2p",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone_number": "+2348012345679",
      "billing_address": {
        "line1": "456 Sample St",
        "line2": null,
        "city": "Lagos",
        "state": "LA",
        "zip_code": "23401",
        "country": "NG"
      },
      "created_at": "2024-03-02T12:00:00Z",
      "updated_at": "2024-03-02T12:00:00Z"
    }
  ],
  "pagination": {
    "before": null,
    "after": "7a8b9c0d-1e2f-3g4h-5i6j-7k8l9m0n1o2p",
    "limit": 2
  }
}
```

### Filtered List Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.spendjuice.com/customers?email=test@custom.er&created_after=2024-01-01T00:00:00Z" \
    -H "Authorization:  YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const customers = await client.customers.list({
    email: 'test@custom.er',
    created_after: '2024-01-01T00:00:00Z'
  });
  ```

  ```python Python theme={null}
  customers = juice.Customer.list(
    email='test@custom.er',
    created_after='2024-01-01T00:00:00Z'
  )
  ```
</CodeGroup>

## Pagination

The API uses cursor-based pagination to handle large collections of customers. To fetch the next page of results:

1. Get the `after` cursor from the pagination object

2. Pass it as the `after` parameter in your next request

3. Repeat until no more `after` cursor is returned

<Note>
  For optimal performance, we recommend:

  * Use reasonable page sizes (15-50 records)

  * Cache results when possible

  * Implement progressive loading in your UI
</Note>

## Error Responses

<ResponseField name="400 Bad Request" type="error">
  Invalid query parameters or malformed request
</ResponseField>

<ResponseField name="401 Unauthorized" type="error">
  Missing or invalid API key
</ResponseField>

<ResponseField name="403 Forbidden" type="error">
  Insufficient permissions to list customers
</ResponseField>

## Rate Limits

List operations are subject to the following rate limits:

* 100 requests per minute per API key

* 1000 requests per hour per API key

<Warning>
  Exceeding these limits will result in a `429 Too Many Requests` response.
</Warning>

## Best Practices

1. **Efficient Filtering**: Use filters to reduce response size and improve performance

2. **Cursor Management**: Store cursors temporarily for pagination

3. **Bulk Operations**: Use higher limit values for bulk data retrieval

4. **Error Handling**: Implement proper retry logic for rate limits

5. **Data Freshness**: Consider implementing cache invalidation strategies

## Customer Object

See the [Customer Object](/snippets/customer-object.mdx) documentation for detailed field descriptions.