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

Endpoint

GET /customers

Query Parameters

limit
integer
default:"15"
Number of records to return per page (max: 100)
after
string
Cursor for fetching next page of results
before
string
Cursor for fetching previous page of results
email
string
Filter customers by email address
created_after
string
Filter customers created after this timestamp (ISO 8601)
created_before
string
Filter customers created before this timestamp (ISO 8601)
sort
string
default:"created_at:desc"
Sort order for results (created_at:asc|created_at:desc)

Response Format

data
Customer[]
Array of customer objects. See Customer Object for structure.
pagination
object
before
string
Cursor for the previous page
after
string
Cursor for the next page
limit
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"
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"

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
For optimal performance, we recommend:
  • Use reasonable page sizes (15-50 records)
  • Cache results when possible
  • Implement progressive loading in your UI

Error Responses

400 Bad Request
error
Invalid query parameters or malformed request
401 Unauthorized
error
Missing or invalid API key
403 Forbidden
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

  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 documentation for detailed field descriptions.