Plans

The Plans API allows you to manage subscription plans for your account. You can list, create, update, and delete plans, as well as perform bulk upserts. Plans include details such as billing frequency, product name, and currency.

List plans

Retrieve all plans for your account. You can optionally filter by data source or limit the number of returned plans.

Endpoint: GET /data/plans

Query parameters:

Example request:

GET /data/plans?source=stripe&limit=5
Authorization: Bearer YOUR_API_KEY

Example response

{
  "result": {
    "count": 5,
    "list": [
      {
        "id": "plan_123",
        "name": "Pro Plan",
        "billing_freq": "month",
        "billing_freq_count": 1,
        "product_name": "Pro Subscription",
        "currency": "USD"
      }
    ]
  }
}

Create or bulk upsert plans

Add a new plan or update existing ones in bulk. Each plan must include id, name, billing_freq, and currency.

Endpoint: POST /data/plans

Request body (single plan example):

{
  "id": "plan_123",
  "name": "Pro Plan",
  "billing_freq": "month",
  "billing_freq_count": 1,
  "currency": "USD",
  "product_name": "Pro Subscription",
  "data_source": "stripe"
}

Request body (bulk example):

[
  {
    "id": "plan_123",
    "name": "Pro Plan",
    "billing_freq": "month",
    "billing_freq_count": 1,
    "currency": "USD",
    "product_name": "Pro Subscription",
    "data_source": "stripe"
  },
  {
    "id": "plan_456",
    "name": "Basic Plan",
    "billing_freq": "month",
    "billing_freq_count": 1,
    "currency": "USD",
    "product_name": "Basic Subscription",
    "data_source": "stripe"
  }
]

Example response:

{
  "result": [
    { "id": "plan_123", "import_status": "inserted" },
    { "id": "plan_456", "import_status": "inserted" }
  ]
}

Validation errors are returned if required fields are missing or invalid:

{
  "result": [
    {
      "id": "plan_789",
      "import_status": "error",
      "import_error": "Missing required fields"
    }
  ]
}

Update a plan

Update an existing plan by its external ID.

Endpoint: PUT /data/plans

Request body:

{
  "id": "plan_123",
  "name": "Pro Plan Updated",
  "billing_freq": "month",
  "billing_freq_count": 1,
  "currency": "USD",
  "product_name": "Pro Subscription"
}

Example response:

{
  "result": "ok",
  "updated": "plan_123"
}

Error response if id is missing:

{
  "error": "Missing external_id"
}

Delete a plan

Delete a plan by its external ID.

Endpoint: DELETE /data/plans

Request body:

{
  "id": "plan_123"
}

Example response:

{
  "result": "ok",
  "deleted": "plan_123"
}

Error response if id is missing:

{
  "error": "Missing external_id"
}