Charges
Once the subscription exists, Migo charges on its own. This page explains when it does, what happens when a charge fails, and how to run charges outside the schedule when your business needs to.
Automatic billingβ
You don't have to do anything: the recurring engine periodically checks which subscriptions are due and charges them.
each run βββΊ for every due subscription:
1. take the default card
2. charge through the processor
3. if approved β advance the next renewal date
4. if it fails β enter the retry schedule
Subscriptions are selected when their next renewal falls on the current day in the merchant's
timezone (America/Guatemala by default).
Every successful charge reaches you as a subsCallback with status: active and the new
nextRenewalDate. See Subscription callback.
Retriesβ
Configured per plan, not on a global schedule:
| Plan field | What it controls |
|---|---|
dailyAttempts | How many times it retries |
intervalAttempt | How long it waits between attempts (24 h by default) |
graceDays | Optional grace window before giving the subscription up as failed |
If the charge fails on the default card, Migo tries the other cards registered for that subscription.
Once all attempts are exhausted the subscription becomes inactive and you receive the matching
callback β that's where you revoke access.
3-D Secureβ
Recurring charges run with nobody in front of the screen, so the engine doesn't request a 3DS challenge. One only appears if your merchant or processor configuration forces it.
Variable-amount chargesβ
When the amount isn't fixed β metered usage, add-ons, top-ups β you can charge a subscription outside its schedule. These are batch ingestion endpoints: they accept many charges in one call and process them asynchronously.
By JSONβ
curl -X POST https://sb-mw.migopayments.com/api/v1/subscriptions/charges \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"client": "<your-client-slug>",
"data": [
{ "subscriptionId": "sub_000001", "amount": 15.00, "metadata": { "note": "July usage" } },
{ "subscriptionId": "sub_000002", "amount": 49.99 }
]
}'
| Field | Required | Notes |
|---|---|---|
client | Yes | Your merchant slug |
data | Yes | Non-empty array, max 5000 items |
data[].subscriptionId | Yes | Subscription to charge |
data[].amount | Yes | Number |
data[].metadata | No | Free-form, for your reconciliation |
Returns 202 Accepted with the batch totals:
{
"success": true,
"message": "Batch received",
"data": { "clientId": "<client-id>", "batchId": "<batch-id>", "totals": {}, "errorsSample": [] }
}
202 means received, not chargedThe result of each charge is not in this response: it arrives later by callback. There is no individual charge identifier.
By CSVβ
For large volumes or operational loads, upload the batch as a file (max 10 MB):
curl -X POST "https://sb-mw.migopayments.com/api/v1/subscriptions/charges/upload-csv?clientId=<client-id>" \
-H "Authorization: Bearer <token>" \
-F "file=@charges.csv"
{ "success": true, "message": "File received...", "trackingId": "V1StGXR8_Z5jdHi6B-myT" }
The response carries only the trackingId. Per-row detail is handled by an asynchronous
consumer: confirm the exact column format and the results report with Migo before relying on them.
When NOT to use themβ
- For normal cadence billing β automatic billing already covers that.
- For a one-off charge to someone without a subscription β use a payment link.
Payment historyβ
curl "https://sb-mw.migopayments.com/api/v1/subscriptions/payment-history?subscriptionId=sub_000001" \
-H "Authorization: Bearer <token>"
The subscriptionId parameter is mandatory (400 if missing). The response is a flat array of
transactions, with no pagination and no date filters:
{ "success": true, "message": "Payment history found", "data": [] }
If you need date-range or merchant-wide reports, build them on the callbacks you already received and stored.
Relatedβ
- Subscription callback β the result of every charge
- Payment methods β which card is used and in what order