Skip to main content
Migo Docs

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:

ValueWhat it doesWhen to use it
"interval"Charges every N days from signupThe 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 cycleAnnual subscriptions
"automatic"Delegates the calculation to the processorUncommon

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
}
}'
FieldTypeRequiredNotes
clientstringYesYour merchant slug
plan.namestringYesShown to the cardholder
plan.amountnumberYesDecimal, up to 4 places
plan.currencyISO 4217YesGTQ, USD, …
plan.typeenumNoSee the cadence table
plan.frequency.frequencyintegerYesDays between charges; 0 for fixedDay
plan.frequency.day1–28NoDay of month, only for fixedDay
plan.frequency.shortDescriptionstringYesShort label (e.g. Monthly)
plan.frequency.longDescriptionstringYesFull cadence description
plan.methodsstring[]YesProcessors enabled to charge
plan.installmentsnumber[]YesAllowed installments β€” [1] for single payment
plan.autoRenewalbooleanYesWhether Migo schedules the next charge
plan.dailyAttemptsintegerYesRetries on a failed charge
plan.daysNotifyExpiringCardintegerYesDays 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
}
}'
Two rules that surprise people
  1. Fields go nested under plan, and that object must include name even if you aren't changing it. Sending amount at the top level does nothing β€” and raises no error.
  2. Changing amount or frequency does 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​

There is no plan deletion

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.