Plans

Create, list, retrieve, and update subscription plans.

Plans API

Plans define price, currency, interval, trial length, invoice limits, and status. All plan endpoints require X-Api-Key.

Plan object

{
  "id": "0a7c1f34-9b12-4d6c-8d45-4db61f463678",
  "createdAt": "2026-07-02T09:00:00Z",
  "updatedAt": "2026-07-02T09:00:00Z",
  "name": "Growth Monthly",
  "description": "Monthly subscription for growing teams",
  "code": "PLN_8AbC123x",
  "amount": 500000,
  "currency": "NGN",
  "interval": "monthly",
  "intervalCount": 1,
  "trialPeriodDays": 14,
  "invoiceLimit": null,
  "status": "active",
  "archivedAt": null
}

POST /v1/plan/

Create a plan.

curl -X POST https://nombasub.oluwadunsin.dev/v1/plan/ \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sub_xxx" \
  -d '{
    "name": "Growth Monthly",
    "description": "Monthly subscription for growing teams",
    "amount": 500000,
    "currency": "NGN",
    "interval": "monthly",
    "intervalCount": 1,
    "trialPeriodDays": 14,
    "invoiceLimit": null
  }'

Request body

Field	Type	Required	Description
name	string	Yes	Plan name.
description	string	No	Plan description.
amount	integer	Yes	Amount in minor units.
currency	string	Yes	NGN.
interval	enum	Yes	daily, weekly, bi-weekly, monthly, quarterly, yearly.
intervalCount	integer	No	Interval multiplier.
trialPeriodDays	integer	No	Trial length in days.
invoiceLimit	integer	No	Maximum invoices before completion logic.

Response

{
  "status": "success",
  "message": "Plan created successfully",
  "data": {
    "id": "0a7c1f34-9b12-4d6c-8d45-4db61f463678",
    "createdAt": "2026-07-02T09:00:00Z",
    "updatedAt": "2026-07-02T09:00:00Z",
    "name": "Growth Monthly",
    "description": "Monthly subscription for growing teams",
    "code": "PLN_8AbC123x",
    "amount": 500000,
    "currency": "NGN",
    "interval": "monthly",
    "intervalCount": 1,
    "trialPeriodDays": 14,
    "invoiceLimit": null,
    "status": "active",
    "archivedAt": null
  }
}

GET /v1/plan/

List plans.

curl "https://nombasub.oluwadunsin.dev/v1/plan/?page=1&limit=10&status=active&interval=monthly" \
  -H "X-Api-Key: sub_xxx"

Query parameters

Parameter	Type	Description
page	integer	Page number.
limit	integer	Page size.
search	string	Accepted pagination query value.
status	enum	active or inactive.
interval	enum	Plan interval.
amount	integer	Exact amount filter.

Response

{
  "status": "success",
  "message": "Plans retrieved successfully",
  "data": {
    "data": [
      {
        "id": "0a7c1f34-9b12-4d6c-8d45-4db61f463678",
        "createdAt": "2026-07-02T09:00:00Z",
        "updatedAt": "2026-07-02T09:00:00Z",
        "name": "Growth Monthly",
        "description": "Monthly subscription for growing teams",
        "code": "PLN_8AbC123x",
        "amount": 500000,
        "currency": "NGN",
        "interval": "monthly",
        "intervalCount": 1,
        "trialPeriodDays": 14,
        "invoiceLimit": null,
        "status": "active",
        "archivedAt": null
      }
    ],
    "totalCount": 1,
    "page": 1,
    "limit": 10,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false
  }
}

GET /v1/plan/:planCode

Retrieve one plan.

curl https://nombasub.oluwadunsin.dev/v1/plan/PLN_8AbC123x \
  -H "X-Api-Key: sub_xxx"

Response

{
  "status": "success",
  "message": "Plan retrieved successfully",
  "data": {
    "id": "0a7c1f34-9b12-4d6c-8d45-4db61f463678",
    "createdAt": "2026-07-02T09:00:00Z",
    "updatedAt": "2026-07-02T09:00:00Z",
    "name": "Growth Monthly",
    "description": "Monthly subscription for growing teams",
    "code": "PLN_8AbC123x",
    "amount": 500000,
    "currency": "NGN",
    "interval": "monthly",
    "intervalCount": 1,
    "trialPeriodDays": 14,
    "invoiceLimit": null,
    "status": "active",
    "archivedAt": null
  }
}

PUT /v1/plan/:planCode

Update a plan. The engine creates a new plan version after an update.

curl -X PUT https://nombasub.oluwadunsin.dev/v1/plan/PLN_8AbC123x \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sub_xxx" \
  -d '{
    "amount": 750000,
    "trialPeriodDays": 7,
    "status": "active",
    "updateExistingSubscriptions": true
  }'

Request body

Field	Type	Description
name	string	New name.
description	string	New description.
amount	integer	New amount.
interval	enum	New interval.
intervalCount	integer	New interval count.
trialPeriodDays	integer	New trial length.
invoiceLimit	integer	New invoice limit.
status	enum	active or inactive.
updateExistingSubscriptions	boolean	Apply the new version to existing subscriptions on their next billing cycle.

Response

{
  "status": "success",
  "message": "Plan updated successfully",
  "data": {
    "id": "0a7c1f34-9b12-4d6c-8d45-4db61f463678",
    "createdAt": "2026-07-02T09:00:00Z",
    "updatedAt": "2026-07-02T10:00:00Z",
    "name": "Growth Monthly",
    "description": "Monthly subscription for growing teams",
    "code": "PLN_8AbC123x",
    "amount": 750000,
    "currency": "NGN",
    "interval": "monthly",
    "intervalCount": 1,
    "trialPeriodDays": 7,
    "invoiceLimit": null,
    "status": "active",
    "archivedAt": null
  }
}