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: Bearer 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: Bearer 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.