Skip to main content
Migo Docs

On-Demand Charges

Charge subscriptions outside of the scheduled cadence. POST /v1/subscriptions/charges is a batch intake endpoint: you submit many charges in one request and they are processed asynchronously.

Endpoint​

curl -X POST https://mw.migopayments.com/v1/subscriptions/charges \
  -H "Authorization: Bearer <middleware-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "client": "client_abc123",
    "data": [
      { "subscriptionId": "sub_01HAAA", "amount": 15.00, "metadata": { "note": "Metered usage" } },
      { "subscriptionId": "sub_01HBBB", "amount": 49.99 }
    ]
  }'
FieldRequiredNotes
client✅Client / tenant id (string)
data✅Non-empty array, max 5000 items
data[].subscriptionId✅Target subscription (string)
data[].amount✅Number
data[].metadata—Free-form

There is no subUid, currency, description, externalId, mode, or cardId field, and no Idempotency-Key header.

Response​

The endpoint returns 202 Accepted with batch totals:

{
  "success": true,
  "message": "Batch received",
  "data": {
    "clientId": "client_abc123",
    "batchId": "bat_01HDDD",
    "totals": { },
    "errorsSample": [ ]
  }
}

There is no single-charge response (chg_..., paymentId, state).

When to use on-demand​

  • Usage billing — bill for metered consumption.
  • Add-ons — charge for upgrades or extra items.
  • Top-ups — charge to replenish a balance.
  • Dunning recovery — attempt a charge on a failing subscription.

When NOT to use on-demand​

Notifications​

On-demand charges feed the same email-notification mechanism as scheduled charges. There is no public outbound webhook contract — see Subscriptions → Notifications.