Get customers list

📘
API Refs

Staging: Get customers list

Request parameters

Name	Type	Description	Required
limit	number	Maximum number of customers to return (default: 50, max: 100)	no
offset	number	Number of customers to skip for pagination (default: 0)	no
include_subscriptions	boolean	Whether to include subscription data for each customer (default: false)	no

Response body

Success Response (200 OK)

Field	Type	Description
data	array	List of customer objects
pagination	object	Pagination information

Customer Object Structure

Field	Type	Description
id	string	Customer ID
email	string	Customer email
firstName	string	Customer first name
lastName	string	Customer last name
phone	string	Customer phone number
stripeCustomerId	string	Stripe customer ID
hasActiveSubscription	boolean	Whether customer has active subscription
subscriptions	array	Customer subscriptions (only when include_subscriptions=true)
createdAt	string	Customer creation date (ISO 8601)
updatedAt	string	Last update date (ISO 8601)

Subscription Object Structure (when included)

Field	Type	Description
id	string	Subscription ID
status	string	Subscription status (active, past_due, canceled, etc.)
currentPeriodStart	string	Current billing period start (ISO 8601)
currentPeriodEnd	string	Current billing period end (ISO 8601)
plan	object	Plan details (nullable)

Plan Object Structure

Field	Type	Description
stripePriceId	string	Stripe price ID
name	string	Plan name
amount	number	Plan amount in cents
currency	string	Plan currency
interval	string	Billing interval (month, year)

Pagination Object Structure

Field	Type	Description
total	number	Total number of customers
limit	number	Applied limit per page
offset	number	Applied offset for pagination
hasMore	boolean	Whether more results are available

Response

{
  "data": [
    {
      "id": "123",
      "email": "[email protected]",
      "firstName": "John",
      "lastName": "Doe",
      "phone": "+1234567890",
      "stripeCustomerId": "cus_ExampleCustomerID123",
      "hasActiveSubscription": true,
      "subscriptions": [
        {
          "id": "sub_ExampleSubscription123",
          "status": "active",
          "currentPeriodStart": "2024-01-01T00:00:00.000Z",
          "currentPeriodEnd": "2024-02-01T00:00:00.000Z",
          "plan": {
            "stripePriceId": "price_ExamplePriceID456",
            "name": "Premium Plan",
            "amount": 4999,
            "currency": "usd",
            "interval": "month"
          }
        }
      ],
      "createdAt": "2023-12-01T00:00:00.000Z",
      "updatedAt": "2024-01-15T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Pagination Usage

To retrieve the next page of results, increment the offset by the limit value:

GET /api/public/customers?limit=10&offset=10

Important Notes

hasActiveSubscription Field: This field is always included and properly calculated when include_subscriptions=true. It considers subscriptions with status "active" or "trialing" as active.
Performance Consideration: Including subscription data (include_subscriptions=true) may increase response time. Only request subscription data when needed.
Default Pagination:
- Default limit: 50 customers
- Maximum limit: 100 customers
- Default offset: 0
Subscription Data: The subscriptions array is only included when include_subscriptions=true is specified.

Error Responses

400 Bad Request: Invalid limit or offset parameters
401 Unauthorized: Invalid or missing authorization token
403 Forbidden: Insufficient permissions

Use Cases

Customer Dashboard: Use without subscription data for quick customer list display
Subscription Management: Include subscription data to show active/inactive customers
Billing Reports: Use with subscription data to analyze customer billing status