Usage statement

This page documents the usage statement, the itemized invoice for a period. Where Usage shows the total of the running cycle, the statement breaks it down line by line: each instance that had a billable period in the window, the number that was connected, how many days counted, the unit price and the amount, plus the usage, credit and charge totals.

Itemized statement

GET /api/account/billing/statement?from=<rfc3339>&to=<rfc3339> Returns the statement for a window. Authenticate with the account TokenAccount, or with the global token passing ?account=<account-name>. The from and to parameters are required, in RFC3339 format.

string

required

Start of the window, in RFC3339 (e.g. 2026-08-01T00:00:00Z).

string

required

End of the window, in RFC3339 (e.g. 2026-09-01T00:00:00Z).

string

Account name. Required only when you use the global token. With the TokenAccount, the account already comes from the token itself.

curl "https://ryzeapi.cloud/api/account/billing/statement?from=2026-08-01T00:00:00Z&to=2026-09-01T00:00:00Z" \
  -H "token: $Token_Account"

const params = new URLSearchParams({
  from: "2026-08-01T00:00:00Z",
  to: "2026-09-01T00:00:00Z"
});

await fetch(`https://ryzeapi.cloud/api/account/billing/statement?${params}`, {
  headers: { "token": process.env.Token_Account }
});

import os, requests

requests.get(
    "https://ryzeapi.cloud/api/account/billing/statement",
    headers={"token": os.environ["Token_Account"]},
    params={"from": "2026-08-01T00:00:00Z", "to": "2026-09-01T00:00:00Z"}
)

200 OK

{
  "items": [
    {
      "instanceName": "client-acme",
      "numberJid": "5511999998888@s.whatsapp.net",
      "billableFrom": "2026-08-01T00:00:00Z",
      "billableTo": "2026-09-01T00:00:00Z",
      "days": 31,
      "unitPriceCents": 5000,
      "amountCents": 5000
    },
    {
      "instanceName": "client-beta",
      "numberJid": "5511988887777@s.whatsapp.net",
      "billableFrom": "2026-08-15T00:00:00Z",
      "billableTo": "2026-09-01T00:00:00Z",
      "days": 17,
      "unitPriceCents": 5000,
      "amountCents": 2741
    }
  ],
  "peakInstances": 2,
  "usageCents": 7741,
  "creditCents": 50000,
  "overageCents": 0,
  "totalChargedCents": 50000,
  "cycleStart": "2026-08-01T00:00:00Z",
  "cycleEnd": "2026-09-01T00:00:00Z"
}

Response fields

array

The line items for the period, one row per instance that had a billable period in the window. An instance deleted mid-period still appears, with the name and number it had, because the record survives deletion. See How billing works.

Show fields of each item

string

Instance name in the period.

string

The WhatsApp number that was connected to the instance in the period.

string

Start of the billable period within the window.

string

End of the billable period within the window.

integer

Billable days of the item in the window.

integer

Monthly unit price applied, in cents. Set by your contract’s volume tier at the period’s instance peak.

integer

The item’s amount, in cents, proportional to the days: unitPriceCents times days divided by the days in the period.

integer

Peak of simultaneous billable instances in the window. It is what sets the unit price tier.

integer

The sum of every item’s amountCents, in cents. The usage for the period.

integer

The credit included in your contract for the period, in cents. It is the invoice floor.

integer

How much usage went past the credit, in cents: the greater of 0 and usageCents minus creditCents. It stays 0 when usage fits within the credit.

integer

The total charged for the period, in cents: the greater of creditCents and usageCents. In other words, you never pay below the credit, and you pay the usage when it exceeds the credit.

string

Start of the queried window.

string

End of the queried window.

Need a document ready to send to your customer? In the panel, at /settings, tab Invoices and usage, you can download the period’s statement formatted as a PDF, and your invoices as PDF too.

Connection history

The timeline of when each number was connected.

How billing works

Credit, trial and the committed model in detail.

Getting started

Billing

Audit

Reference

Usage statement

Itemized statement

Response fields

Next

Connection history

How billing works

​Itemized statement

​Response fields

​Next

Connection history

How billing works

Itemized statement

Response fields

Next