List Customers

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

Endpoint

GET /customers

Query Parameters

integer

default:"15"

Number of records to return per page (max: 100)

string

Cursor for fetching next page of results

string

Cursor for fetching previous page of results

string

Filter customers by email address

string

Filter customers created after this timestamp (ISO 8601)

string

Filter customers created before this timestamp (ISO 8601)

string

default:"created_at:desc"

Sort order for results (created_at:asc|created_at:desc)

Response Format

Customer[]

Array of customer objects. See Customer Object for structure.

object

string

Cursor for the previous page

string

Cursor for the next page

integer

Number of records per page

Examples

Basic List Request

curl -X GET "https://api.spendjuice.com/customers?limit=2" \
  -H "Authorization:  YOUR_API_KEY"

const juice = require('juice-node');
const client = new juice('YOUR_API_KEY');

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

import juice
juice.api_key = 'YOUR_API_KEY'

customers = juice.Customer.list(
  limit=2
)

Response

{
  "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

curl -X GET "https://api.spendjuice.com/customers?email=test@custom.er&created_after=2024-01-01T00:00:00Z" \
  -H "Authorization:  YOUR_API_KEY"

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

customers = juice.Customer.list(
  email='test@custom.er',
  created_after='2024-01-01T00:00:00Z'
)

Pagination

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

Get the after cursor from the pagination object
Pass it as the after parameter in your next request
Repeat until no more after cursor is returned

For optimal performance, we recommend:

Use reasonable page sizes (15-50 records)
Cache results when possible
Implement progressive loading in your UI

Error Responses

error

Invalid query parameters or malformed request

error

Missing or invalid API key

error

Insufficient permissions to list customers

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

Exceeding these limits will result in a 429 Too Many Requests response.

Best Practices

Efficient Filtering: Use filters to reduce response size and improve performance
Cursor Management: Store cursors temporarily for pagination
Bulk Operations: Use higher limit values for bulk data retrieval
Error Handling: Implement proper retry logic for rate limits
Data Freshness: Consider implementing cache invalidation strategies

Customer Object

See the Customer Object documentation for detailed field descriptions.

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Wallet As A Service

Endpoint

Query Parameters

Response Format

Examples

Basic List Request

Filtered List Request

Error Responses

Rate Limits

Best Practices

Customer Object

​Endpoint

​Query Parameters

​Response Format

​Examples

​Basic List Request

​Filtered List Request

​Pagination

​Error Responses

​Rate Limits

​Best Practices

​Customer Object

Endpoint

Query Parameters

Response Format

Examples

Basic List Request

Filtered List Request

Pagination

Error Responses

Rate Limits

Best Practices

Customer Object