Skip to main content
Migo Docs

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:

StateMeaning
activeUp to date β€” still charged on every renewal
inactiveCharge retries exhausted; billing stopped
cancelledCancelled by you or by the cardholder
expiredFixed-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.

Only active and inactive arrive by callback

cancelled 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" }
]
}
It's a per-customer listing, not a global one

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.