Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

Returns how many billable alerts each merchant of your company had in a billing cycle: the current one, still open, or one already closed. These are counts only; the invoice amounts are in the dashboard, in Settings › Billing.

GET https://api.rapidchargeback.com/api/v1/usage/merchants
Authorization: Basic base64(client_id:client_secret)

All optional. A parameter outside this table is rejected with 422 VALIDATION_ERROR (Unknown field: <name>).

ParamTypeDefaultDescription
cyclestringcurrentcurrent (cycle in progress), previous (last closed cycle) or YYYY-MM (the closed cycle that started in that month)
merchant_idstring (UUID)-Only this merchant
merchant_refstring (up to 100)-Only the merchant with this reference from your system
pageint (≥ 1)1Page
per_pageint (1–100)20Items per page
  • The cycle runs from your company’s closing day until the day before the next closing, counted in UTC.
  • YYYY-MM of the cycle in progress counts as current. Future month: 422 VALIDATION_ERROR “cycle cannot be in the future”. Month with no closed cycle: 404 USAGE_CYCLE_NOT_FOUND.

Terminal window
curl -G "https://api.rapidchargeback.com/api/v1/usage/merchants" \
--data-urlencode "cycle=previous" \
--data-urlencode "per_page=100" \
-H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="

{
"data": [
{ "merchant_id": "00000000-0000-0000-0000-000000000001", "merchant_ref": "PB-1001", "name": "Loja Exemplo", "billable_alerts": 42 },
{ "merchant_id": null, "merchant_ref": null, "name": null, "billable_alerts": 3 }
],
"meta": {
"cycle_start": "2026-11-01",
"cycle_end": "2026-11-30",
"cycle_status": "closed",
"totals": { "billable_alerts": 45 },
"generated_at": "2026-12-02T14:00:00.000Z",
"page": 1,
"per_page": 100,
"total": 2,
"total_pages": 1
}
}
FieldDescription
merchant_id, merchant_ref, nameThe merchant. null in all three on the row of alerts without an identified merchant, which comes last
billable_alertsThe merchant’s billable alerts in the cycle
meta.cycle_start, meta.cycle_endFirst and last day of the cycle (YYYY-MM-DD, the last one included)
meta.cycle_statusopen (cycle in progress: a preview, it changes until the closing) or closed
meta.totals.billable_alertsCycle total, across all pages
meta.generated_atWhen the count was made

The order goes from the merchant with the most alerts to the one with the fewest.

HTTP/1.1 404 Not Found
{
"error": {
"code": "USAGE_CYCLE_NOT_FOUND",
"message": "No closed billing cycle starts in this month"
}
}
HTTPCodeWhen
422VALIDATION_ERRORcycle in another format or in the future, unknown parameter (params.field)
404USAGE_CYCLE_NOT_FOUNDNo closed cycle starts in the requested month (or there is no closed cycle yet, for previous)
429RATE_LIMIT_EXCEEDEDMore than 10 queries per minute
403COMPANY_BLOCKEDBlocked company
503SERVICE_UNAVAILABLETemporarily unavailable: repeat after Retry-After

  • Numbers up to 5 minutes old. The count is redone at most every 5 minutes; generated_at says when it was made, and all pages of the same query come from the same count.
  • An open cycle is a preview: the count of the cycle in progress may change until the closing.
  • 10 queries per minute per company, counted apart from writes.
  • Auth, rate limit, error codes: see Authentication and Response codes.