Skip to main content
Migo Docs

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 fieldWhat it controls
dailyAttemptsHow many times it retries
intervalAttemptHow long it waits between attempts (24 h by default)
graceDaysOptional 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 }
]
}'
FieldRequiredNotes
clientYesYour merchant slug
dataYesNon-empty array, max 5000 items
data[].subscriptionIdYesSubscription to charge
data[].amountYesNumber
data[].metadataNoFree-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 charged

The 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.