Usage by merchant
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.
Endpoint
Section titled “Endpoint”GET
https://api.rapidchargeback.com/api/v1/usage/merchantsAuthentication
Section titled “Authentication”Authorization: Basic base64(client_id:client_secret)Query params
Section titled “Query params”All optional. A parameter outside this table is rejected with 422 VALIDATION_ERROR (Unknown field: <name>).
| Param | Type | Default | Description |
|---|---|---|---|
cycle | string | current | current (cycle in progress), previous (last closed cycle) or YYYY-MM (the closed cycle that started in that month) |
merchant_id | string (UUID) | - | Only this merchant |
merchant_ref | string (up to 100) | - | Only the merchant with this reference from your system |
page | int (≥ 1) | 1 | Page |
per_page | int (1–100) | 20 | Items per page |
- The cycle runs from your company’s closing day until the day before the next closing, counted in UTC.
YYYY-MMof the cycle in progress counts ascurrent. Future month:422 VALIDATION_ERROR“cycle cannot be in the future”. Month with no closed cycle:404 USAGE_CYCLE_NOT_FOUND.
Request example
Section titled “Request example”curl -G "https://api.rapidchargeback.com/api/v1/usage/merchants" \ --data-urlencode "cycle=previous" \ --data-urlencode "per_page=100" \ -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="Response
Section titled “Response”Success
Section titled “Success”{ "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 }}| Field | Description |
|---|---|
merchant_id, merchant_ref, name | The merchant. null in all three on the row of alerts without an identified merchant, which comes last |
billable_alerts | The merchant’s billable alerts in the cycle |
meta.cycle_start, meta.cycle_end | First and last day of the cycle (YYYY-MM-DD, the last one included) |
meta.cycle_status | open (cycle in progress: a preview, it changes until the closing) or closed |
meta.totals.billable_alerts | Cycle total, across all pages |
meta.generated_at | When the count was made |
The order goes from the merchant with the most alerts to the one with the fewest.
Cycle not found
Section titled “Cycle not found”HTTP/1.1 404 Not Found{ "error": { "code": "USAGE_CYCLE_NOT_FOUND", "message": "No closed billing cycle starts in this month" }}Errors
Section titled “Errors”| HTTP | Code | When |
|---|---|---|
| 422 | VALIDATION_ERROR | cycle in another format or in the future, unknown parameter (params.field) |
| 404 | USAGE_CYCLE_NOT_FOUND | No closed cycle starts in the requested month (or there is no closed cycle yet, for previous) |
| 429 | RATE_LIMIT_EXCEEDED | More than 10 queries per minute |
| 403 | COMPANY_BLOCKED | Blocked company |
| 503 | SERVICE_UNAVAILABLE | Temporarily unavailable: repeat after Retry-After |
- Numbers up to 5 minutes old. The count is redone at most every 5 minutes;
generated_atsays 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.