List Customers

Retrieve a paginated list of customers

GET /v1/customers

cURL

curl -X GET "https://api.flexprice.io/v1/customers?limit=10&offset=0&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 - Success

{
  "items": [
    {
      "id": "cust_abc123xyz789",
      "external_id": "user_12345",
      "name": "Acme Corporation",
      "email": "[e-mail]",
      "address_line1": "123 Main Street",
      "address_line2": "",
      "address_city": "San Francisco",
      "address_state": "CA",
      "address_postal_code": "94105",
      "address_country": "US",
      "parent_customer_id": null,
      "metadata": {
        "plan_tier": "enterprise"
      },
      "environment_id": "env_prod_001",
      "tenant_id": "tenant_001",
      "status": "published",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "cust_def456uvw012",
      "external_id": "user_67890",
      "name": "Tech Startup Inc",
      "email": "[e-mail]",
      "address_line1": "456 Innovation Ave",
      "address_line2": "Suite 200",
      "address_city": "Austin",
      "address_state": "TX",
      "address_postal_code": "78701",
      "address_country": "US",
      "parent_customer_id": null,
      "metadata": {
        "plan_tier": "growth"
      },
      "environment_id": "env_prod_001",
      "tenant_id": "tenant_001",
      "status": "published",
      "created_at": "2024-01-14T09:15:00Z",
      "updated_at": "2024-01-14T09:15:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 10,
    "offset": 0
  }
}

Use this endpoint when listing or searching customers (e.g., admin CRM or reporting). Returns a paginated list with support for filtering and sorting.

Query Parameters

limit · integer · default: 50

The number of customers to return per page. Must be between 1 and 1000.

offset · integer · default: 0

The number of customers to skip before starting to return results. Used for pagination.

sort · string · default: "created_at"

The field to sort by (e.g., created_at, name, email).

order · string · default: "desc"

The sort order. Must be either asc (ascending) or desc (descending).

status · string

Filter by customer status (e.g., published, draft, archived).

customer_ids · array

Filter by specific customer IDs. Provide multiple IDs as comma-separated values.

external_ids · array

Filter by external customer IDs. Provide multiple IDs as comma-separated values.

external_id · string

Filter by a single external customer ID.

email · string

Filter by customer email address.

parent_customer_ids · array

Filter by parent customer IDs to retrieve child customers.

expand · string

Expand related resources in the response (e.g., parent_customer).

Response

items · array

An array of customer objects.

Show Customer Object

id · string

The unique FlexPrice customer ID.

external_id · string

The external identifier from your system.

name · string

The customer’s name or company name.

email · string

The customer’s email address.

address_line1 · string

Primary address line.

address_line2 · string

Secondary address line.

address_city · string

City name.

address_state · string

State or region name.

address_postal_code · string

Postal code.

address_country · string

Two-letter country code.

parent_customer_id · string

The parent customer ID if this is a child customer.

metadata · object

Custom metadata key-value pairs.

environment_id · string

The environment ID.

tenant_id · string

The tenant ID.

status · string

The customer status.

created_at · string

ISO 8601 timestamp of creation.

updated_at · string

ISO 8601 timestamp of last update.

pagination · object

Pagination metadata.

Show Pagination Object

total · integer

The total number of customers matching the filter criteria.

limit · integer

The number of customers returned per page.

offset · integer

The offset for the next page of results.

cURL

curl -X GET "https://api.flexprice.io/v1/customers?limit=10&offset=0&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

200 - Success

{
  "items": [
    {
      "id": "cust_abc123xyz789",
      "external_id": "user_12345",
      "name": "Acme Corporation",
      "email": "[e-mail]",
      "address_line1": "123 Main Street",
      "address_line2": "",
      "address_city": "San Francisco",
      "address_state": "CA",
      "address_postal_code": "94105",
      "address_country": "US",
      "parent_customer_id": null,
      "metadata": {
        "plan_tier": "enterprise"
      },
      "environment_id": "env_prod_001",
      "tenant_id": "tenant_001",
      "status": "published",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "cust_def456uvw012",
      "external_id": "user_67890",
      "name": "Tech Startup Inc",
      "email": "[e-mail]",
      "address_line1": "456 Innovation Ave",
      "address_line2": "Suite 200",
      "address_city": "Austin",
      "address_state": "TX",
      "address_postal_code": "78701",
      "address_country": "US",
      "parent_customer_id": null,
      "metadata": {
        "plan_tier": "growth"
      },
      "environment_id": "env_prod_001",
      "tenant_id": "tenant_001",
      "status": "published",
      "created_at": "2024-01-14T09:15:00Z",
      "updated_at": "2024-01-14T09:15:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 10,
    "offset": 0
  }
}

Pagination

The list endpoint supports cursor-based pagination using limit and offset parameters:

1. First Page: Set limit to the desired page size (default: 50) and offset to 0
2. Next Pages: Increment offset by limit for each subsequent page
3. Check Total: Use pagination.total to determine if more pages exist

Example pagination flow:

# Page 1: Get first 50 customers
curl "https://api.flexprice.io/v1/customers?limit=50&offset=0"

# Page 2: Get next 50 customers
curl "https://api.flexprice.io/v1/customers?limit=50&offset=50"

# Page 3: Get next 50 customers
curl "https://api.flexprice.io/v1/customers?limit=50&offset=100"