Subscriptions
A subscription binds one end customer to one plan and to the card stored at payment time.
Migo creates it automatically when the payment link payment is
approved β there is no POST /api/v1/subscriptions.
Every route on this page uses Authorization: Bearer <your-merchant-token>.
Statesβ
There are exactly four:
| State | Meaning |
|---|---|
active | Up to date β still charged on every renewal |
inactive | Charge retries exhausted; billing stopped |
cancelled | Cancelled by you or by the cardholder |
expired | Fixed-term subscription that reached its end |
ββββββββββββ
β active β
ββββββ¬ββββββ
βββββββββββββββΌββββββββββββββ
βΌ βΌ βΌ
βββββββββββββ ββββββββββββ ββββββββββββ
β cancelled β β inactive β β expired β
βββββββββββββ ββββββββββββ ββββββββββββ
you cancel retries term
exhausted ended
The states are terminal: a cancelled or inactive subscription cannot be reactivated. To
resume billing, generate a new payment link and have the customer pay again.
There is no trialing, past_due, unpaid or paused: the API does not support free trials,
pausing, plan changes or proration.
active and inactive arrive by callbackcancelled and expired are not notified. If you care about them, poll the subscription
(see Subscription callback).
Read a subscriptionβ
curl https://sb-mw.migopayments.com/api/v1/subscriptions/detail/<subUid> \
-H "Authorization: Bearer <token>"
This is how you learn the real state, including the ones the callback never reports.
List subscriptionsβ
Requires both userId and clientId β if either is missing it returns 400:
curl "https://sb-mw.migopayments.com/api/v1/subscriptions?userId=<userId>&clientId=<clientId>" \
-H "Authorization: Bearer <token>"
{
"success": true,
"message": "subscriptions found",
"data": [
{ "planName": "Monthly plan", "uid": "sub_000001", "URL": "https://.../subscriptions/sub_000001" }
]
}
There is no way to fetch "all my merchant's subscriptions": you always need the userId. There are
no filters by state or plan, and no pagination. Keep your own customer index so you can iterate.
Update a subscriptionβ
PUT /api/v1/subscriptions changes only the notification email:
curl -X PUT https://sb-mw.migopayments.com/api/v1/subscriptions \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "subUid": "sub_000001", "email": "billing@example.com" }'
It does not change the plan, the amount, the state or the card. For the card use Payment methods.
Cancel a subscriptionβ
curl -X DELETE https://sb-mw.migopayments.com/api/v1/subscriptions/<subUid> \
-H "Authorization: Bearer <token>"
Cancellation is immediate: the state becomes cancelled and no further charges happen. There is
no end-of-period deferred cancellation and no automatic refund of the current cycle; if you want to
honor the time already paid, control the access cut-off date yourself.
Alternative: create the subscription from your own checkoutβ
If you have PCI scope and charge with your own card form, you can create the subscription without
the webview: POST /api/v1/subscriptions/verify-card with shouldCreateSubscription: true and the
planUid, tied to an existing transaction. It tokenizes the card, pre-authorizes it, reverses that
authorization and creates the subscription in the same step.
For the vast majority of integrations this is not the path: it requires PCI certification and handling card data. See Payment methods.
Relatedβ
- Live spec:
GET /api/v1/subscriptions/detail/{subUid}Β·DELETE /api/v1/subscriptions/{subUid} - Charges β what happens at every renewal