Skip to main content
Migo Docs

Bulk Charges (CSV)

Charge many subscriptions at once by uploading a CSV. The upload is accepted synchronously and queued for asynchronous processing.

When to use​

  • Quarterly invoicing where each customer gets a different line item.
  • Reconciliation runs — charge outstanding balances after a period close.
  • Migration from another billing provider.

For routine cadence billing use Scheduled charges instead.

Upload​

POST /v1/subscriptions/charges/upload-csv accepts a multipart file upload. A clientId is required (as a form field or clientId query parameter). The maximum file size is 10 MB.

curl -X POST "https://mw.migopayments.com/v1/subscriptions/charges/upload-csv?clientId=client_abc123" \
  -H "Authorization: Bearer <middleware-jwt>" \
  -F "file=@charges-2026-04.csv"

The upload returns 202 Accepted with a trackingId:

{
  "success": true,
  "message": "File received...",
  "trackingId": "V1StGXR8_Z5jdHi6B-myT"
}

The response contains trackingId only — there is no batchId, rowCount, status, or createdAt.

Needs verification

The CSV column contract, results-CSV columns, per-row outcome reporting, and identical-CSV idempotency are handled by the downstream SQS consumer, which is out of scope for this contract. Confirm these against the consumer before relying on them.

Error handling​

Validation at the intake endpoint (the downstream charge consumer) maps the library error codes IDEMPOTENCY_CONFLICT, PLAN_RULE_VIOLATION, and UNPROCESSABLE to HTTP 405. Specific per-row numeric codes are not part of this intake contract; verify them against the charge consumer and the Error Catalog before presenting them as authoritative.