Plans
A plan defines how much is charged and how often. You create it once and reuse it across as many subscriptions as you want.
Every route on this page uses Authorization: Bearer <your-merchant-token>.
Cadence β the four typesβ
The type field decides how Migo computes the next charge date. Send the value in
lowercase/camelCase, exactly as shown in the "Value" column:
| Value | What it does | When to use it |
|---|---|---|
"interval" | Charges every N days from signup | The most common β weekly, every 30 days, every 90 days |
"fixedDay" | Charges on a fixed day of the month | "The 1st" or "the 15th" billing |
"anniversary" | Charges the same calendar day every cycle | Annual subscriptions |
"automatic" | Delegates the calculation to the processor | Uncommon |
Create a planβ
curl -X POST https://sb-mw.migopayments.com/api/v1/plans \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"client": "<your-client-slug>",
"plan": {
"name": "Monthly plan",
"amount": 99.00,
"currency": "GTQ",
"type": "interval",
"frequency": {
"frequency": 30,
"day": 1,
"shortDescription": "Monthly",
"longDescription": "Charged every 30 days"
},
"methods": ["<processor-slug>"],
"installments": [1],
"autoRenewal": true,
"dailyAttempts": 3,
"daysNotifyExpiringCard": 7
}
}'
| Field | Type | Required | Notes |
|---|---|---|---|
client | string | Yes | Your merchant slug |
plan.name | string | Yes | Shown to the cardholder |
plan.amount | number | Yes | Decimal, up to 4 places |
plan.currency | ISO 4217 | Yes | GTQ, USD, β¦ |
plan.type | enum | No | See the cadence table |
plan.frequency.frequency | integer | Yes | Days between charges; 0 for fixedDay |
plan.frequency.day | 1β28 | No | Day of month, only for fixedDay |
plan.frequency.shortDescription | string | Yes | Short label (e.g. Monthly) |
plan.frequency.longDescription | string | Yes | Full cadence description |
plan.methods | string[] | Yes | Processors enabled to charge |
plan.installments | number[] | Yes | Allowed installments β [1] for single payment |
plan.autoRenewal | boolean | Yes | Whether Migo schedules the next charge |
plan.dailyAttempts | integer | Yes | Retries on a failed charge |
plan.daysNotifyExpiringCard | integer | Yes | Days of advance notice before the card expires |
Store the plan uid returned in the response: it's what later goes into customKeys.plan.uid when
you generate the payment link.
List plansβ
curl "https://sb-mw.migopayments.com/api/v1/plans/list?client=<your-client-slug>" \
-H "Authorization: Bearer <token>"
Read a planβ
curl "https://sb-mw.migopayments.com/api/v1/plans/<planId>/client/<client>/detail" \
-H "Authorization: Bearer <token>"
Returns the plan plus that merchant's specific adjustments (currency conversion, localized name) and the next charge date computed in their timezone.
Update a planβ
curl -X PUT https://sb-mw.migopayments.com/api/v1/plans \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"client": "<your-client-slug>",
"planId": "<plan-id>",
"plan": {
"name": "Monthly plan",
"amount": 119.00
}
}'
- Fields go nested under
plan, and that object must includenameeven if you aren't changing it. Sendingamountat the top level does nothing β and raises no error. - Changing
amountorfrequencydoes not affect existing subscriptions: they keep their original price and cadence.
To raise the price for current customers you have to create a new plan and re-subscribe them: the API does not allow moving a subscription between plans.
Delete a planβ
The API exposes create, list, read and update β there is no DELETE /api/v1/plans and no archive
field. A plan you no longer offer stays in your list.
In the meantime, the recommended practice is to mark it in the name (e.g. prefix
[Discontinued]) and filter it out on your application side. Deleting wouldn't be desirable anyway:
it would break the historical traceability of the subscriptions created from it.
Relatedβ
- Live spec:
POST /api/v1/plansΒ·GET /api/v1/plans/listΒ·PUT /api/v1/plans - Subscription payment link β the next step