TagPayTagPay

API Reference

Plans

A Plan is a reusable billing template — a fixed `amount` charged on a fixed `interval`. Subscribers attach to a Plan via the Subscriptions API and the recurring-charge cron handles the rest.

Create a plan

POST/v1/plans

amount and interval lock the billing terms for everyone who ever subscribes to this plan. Because changing those after subscribers attach is destructive, both fields are immutable post-create — for term changes, create a new plan and migrate. Use interval: custom with interval_days for non-standard cycles (e.g. 45-day billing).

Body parameters

namestringrequired

Internal name for the plan, 1-200 chars.

amountintegerrequired

Amount in kobo charged each cycle. NGN 5,000 = 500000.

intervalenum<'daily' | 'weekly' | 'monthly' | 'quarterly' | 'biannually' | 'annually' | 'custom'>required

Billing cadence. custom requires interval_days.

interval_daysintegeroptional

Days between charges. **Required when interval = custom**, ignored otherwise. Range 1-730.

descriptionstringoptional

Free-text description, up to 500 chars. Surfaced in dashboard.

metadataobjectoptional

Arbitrary key/value pairs for your own bookkeeping.

Response

201
plan_codestring

TagPay-assigned code, prefixed with `PLN_`. Use this to subscribe customers.

namestring

Plan name.

descriptionstring | null

Free-text description, or null.

amountinteger

Amount in kobo per cycle.

currencystring

Always `NGN` today.

intervalstring

Billing cadence.

interval_daysinteger | null

Custom cycle length in days; null for standard intervals.

activeboolean

`true` by default. Inactive plans cannot accept new subscribers.

metadataobject | null

Echoed metadata, or null.

created_atstring

ISO-8601 timestamp.

updated_atstring

ISO-8601 timestamp.

Errors

VALIDATION_ERROR400`interval_days` is required when `interval = custom`.
INVALID_KEY401API key missing or invalid. Use your secret key.

List plans

GET/v1/plans

Returns plans in reverse-chronological order. Scoped to the current mode (sandbox vs live) based on the key prefix.

Query parameters

activebooleanoptional

Filter by active flag.

pageintegeroptional

Page number, 1-indexed. Defaults to 1.

per_pageintegeroptional

Results per page, max 100. Defaults to 20.

Response

200
dataarray<Plan>

Array of plan objects.

metaobject

Pagination metadata.

totalinteger

Total matching records.

pageinteger

Current page.

per_pageinteger

Per-page count.

page_countinteger

Total number of pages.

Retrieve a plan

GET/v1/plans/:code

Returns the full plan resource. 404 if the code does not belong to your merchant in the current mode.

Path parameters

codestringrequired

Plan code, e.g. PLN_8mFp2Lq9KdR4nXyZ.

Response

200
plan_codestring

Plan code.

namestring

Plan name.

descriptionstring | null

Description, or null.

amountinteger

Amount in kobo per cycle.

currencystring

Always `NGN`.

intervalstring

Billing cadence.

interval_daysinteger | null

Custom cycle length; null for standard intervals.

activeboolean

Active flag.

metadataobject | null

Metadata, or null.

created_atstring

ISO-8601 timestamp.

updated_atstring

ISO-8601 timestamp.

Errors

NOT_FOUND404No plan with that code in your account.

Update a plan

PUT/v1/plans/:code

`amount` and `interval` are immutable. Once subscribers attach, changing billing terms would silently shift their contract. To change the price or cadence, create a new plan and migrate subscribers explicitly. Only name, description, active, and metadata are mutable here. Set active: false to stop the plan from accepting new subscribers (existing subscriptions keep billing).

Path parameters

codestringrequired

Plan code, e.g. PLN_8mFp2Lq9KdR4nXyZ.

Body parameters

namestringoptional

New plan name, 1-200 chars.

descriptionstringoptional

New description, up to 500 chars.

activebooleanoptional

Toggle whether new subscribers may attach.

metadataobjectoptional

Replace metadata.

Response

200
plan_codestring

Plan code.

namestring

Plan name.

descriptionstring | null

Description.

amountinteger

Amount in kobo (unchanged).

currencystring

Always `NGN`.

intervalstring

Interval (unchanged).

interval_daysinteger | null

Custom days (unchanged).

activeboolean

Active flag.

metadataobject | null

Metadata.

created_atstring

ISO-8601 timestamp.

updated_atstring

ISO-8601 timestamp.

Errors

NOT_FOUND404No plan with that code in your account.
VALIDATION_ERROR400Body failed validation.