Skip to main content

​
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

FieldTypeRequiredDescription
namestringYesPlan name.
descriptionstringNoPlan description.
amountintegerYesAmount in minor units.
currencystringYesNGN.
intervalenumYesdaily, weekly, bi-weekly, monthly, quarterly, yearly.
intervalCountintegerNoInterval multiplier.
trialPeriodDaysintegerNoTrial length in days.
invoiceLimitintegerNoMaximum 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

ParameterTypeDescription
pageintegerPage number.
limitintegerPage size.
searchstringAccepted pagination query value.
statusenumactive or inactive.
intervalenumPlan interval.
amountintegerExact 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

FieldTypeDescription
namestringNew name.
descriptionstringNew description.
amountintegerNew amount.
intervalenumNew interval.
intervalCountintegerNew interval count.
trialPeriodDaysintegerNew trial length.
invoiceLimitintegerNew invoice limit.
statusenumactive or inactive.
updateExistingSubscriptionsbooleanApply 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
  }
}