# Usage by merchant

> How many billable alerts each merchant of your company had in the current billing cycle or in a closed one. Counts only.

Página: https://doc.rapidchargeback.com/en/canais/uso/uso-por-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

```
GET https://api.rapidchargeback.com/api/v1/usage/merchants
```

## Authentication

```
Authorization: Basic base64(client_id:client_secret)
```

---

## 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-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`.

---

## Request example

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

---

## Response

### Success

```json
{
  "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

```
HTTP/1.1 404 Not Found
```

```json
{
  "error": {
    "code": "USAGE_CYCLE_NOT_FOUND",
    "message": "No closed billing cycle starts in this month"
  }
}
```

### 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` |

---

## Notes

- **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](https://doc.rapidchargeback.com/en/referencia/autenticacao/) and [Response codes](https://doc.rapidchargeback.com/en/referencia/codigos-de-resposta/).
