List Plans

Retrieve a paginated list of all plans in your environment. Use when listing or searching plans for a plan picker or admin catalog.

GET /v1/plans

List Plans

cURL

curl --request GET \
  --url https://api.example.com/v1/plans

200

{
  "data": [
    {
      "id": "<string>",
      "name": "<string>",
      "lookup_key": "<string>",
      "description": "<string>",
      "display_order": 123,
      "metadata": {},
      "environment_id": "<string>",
      "tenant_id": "<string>",
      "status": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "prices": [
        {}
      ],
      "entitlements": [
        {}
      ],
      "credit_grants": [
        {}
      ]
    }
  ],
  "total": 123,
  "limit": 123,
  "offset": 123,
  "has_more": true
}

Query Parameters

limit · integer · default: "10"

Maximum number of plans to return.

Example: 20

offset · integer · default: "0"

Number of plans to skip before starting to return results.

Example: 10

cursor · string

Cursor for pagination (alternative to offset).

Response

data · array

Array of plan objects.

Show plan properties

id · string

Unique identifier for the plan.

name · string

Human-readable name for the plan.

lookup_key · string

Unique lookup key.

description · string

Description of the plan.

display_order · integer

Display order for the plan.

metadata · object

Custom metadata.

environment_id · string

Environment ID where the plan exists.

tenant_id · string

Tenant ID that owns this plan.

status · string

Status of the plan.

created_at · string

ISO 8601 timestamp when the plan was created.

updated_at · string

ISO 8601 timestamp when the plan was last updated.

prices · array

Array of prices associated with this plan (if included).

entitlements · array

Array of entitlements associated with this plan (if included).

credit_grants · array

Array of credit grants associated with this plan (if included).

total · integer

Total number of plans matching the query.

limit · integer

Maximum number of results returned.

offset · integer

Number of results skipped.

has_more · boolean

Whether there are more results available.

Example Request

cURL

curl --request GET \
  --url 'https://api.flexprice.io/v1/plans?limit=20&offset=0' \
  --header 'Authorization: Bearer <token>'

Example Response

{
  "data": [
    {
      "id": "plan_a1b2c3d4e5f6g7h8i9j0",
      "name": "Pro Plan",
      "lookup_key": "pro-monthly",
      "description": "Professional tier with advanced features",
      "display_order": 2,
      "metadata": {
        "tier": "professional"
      },
      "environment_id": "env_123",
      "tenant_id": "tenant_123",
      "status": "published",
      "created_at": "2024-03-20T15:04:05Z",
      "updated_at": "2024-03-20T15:04:05Z"
    },
    {
      "id": "plan_k1l2m3n4o5p6q7r8s9t0",
      "name": "Enterprise Plan",
      "lookup_key": "enterprise-annual",
      "description": "Enterprise tier with dedicated support",
      "display_order": 3,
      "metadata": {
        "tier": "enterprise"
      },
      "environment_id": "env_123",
      "tenant_id": "tenant_123",
      "status": "published",
      "created_at": "2024-03-21T10:15:30Z",
      "updated_at": "2024-03-21T10:15:30Z"
    }
  ],
  "total": 2,
  "limit": 20,
  "offset": 0,
  "has_more": false
}