Create usage invoice

Create a usage statement for a calendar month.

POSThttps://api.tried.com.au/billing/invoices/usage

Creates a usage statement for one calendar month (UTC). It does not charge anything, because usage is drawn from prepaid credit. If a statement for that month already exists, it is returned instead of a new one.

Request#

Field	Type	Required	Description
`month`	string	Yes	Month as `YYYY-MM`, for example `2026-09`.

Example request#

curl -X POST https://api.tried.com.au/billing/invoices/usage \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "month": "2026-09"
  }'

const res = await fetch("https://api.tried.com.au/billing/invoices/usage", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRIED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "month": "2026-09"
  }),
});
const invoice = await res.json();

import os, requests

res = requests.post(
    "https://api.tried.com.au/billing/invoices/usage",
    headers={"Authorization": f"Bearer {os.environ['TRIED_API_KEY']}"},
    json={
        "month": "2026-09",
    },
)
invoice = res.json()

Response#

201 Created

{
  "invoice_id": "inv_7f9b1d3a5c7e9b1d3f5a7c9e",
  "number": "TR-202610-5521093",
  "kind": "usage",
  "amount": 182.44,
  "currency": "AUD",
  "status": "paid",
  "lines": [
    {
      "description": "Voice calls (1214)",
      "quantity": 1214,
      "unit_amount": null,
      "amount": 182.44
    },
    {
      "description": "Chats (86)",
      "quantity": 86,
      "unit_amount": null,
      "amount": 0
    }
  ],
  "period_start": 1756684800000,
  "period_end": 1759276800000,
  "provider": "mock",
  "created_timestamp": 1760832000000,
  "html_url": "/billing/invoices/inv_7f9b1d3a5c7e9b1d3f5a7c9e/html"
}

Returns the invoice with kind: "usage" and status: "paid". amount is the month's call, chat and platform spend rounded to cents. The first line counts voice calls and carries the full amount; the second counts chats with an amount of 0. Fields are as in List invoices.

Errors#

Status	When
`400`	`month: Invalid` when the value is not `YYYY-MM`, or `month: Required`.
`401`	Missing or invalid API key.
`403`	The key's IP allowlist or scopes reject the request. This route needs the `agents` scope (the path contains `invoices`, which matches the `voice` scope rule), or a key with `admin`. A dashboard user with the `member` role gets `The member role is read-only`.
`429`	Rate limit exceeded. See Rate limits.

See Errors for the body format.