Closed billing periods

curl 'https://api.example.struq/v1/usage/periods' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Once a calendar month has fully ended, it is closed into a permanent entry per contract, which is never changed afterwards. Its billed_amount is the month’s charge, minimums included. A correction to a closed month — a credit, or usage that reached us late — is never written into the entry; it is recorded beside it, and adjustments is the sum of those corrections, negative for a credit and zero when there are none. amount_due is billed_amount plus adjustments: this is what an invoice or a dispute should be checked against. Each entry lists its lines: one usage line per price rule and rate, with the successes billed at it and the amount, rounded once. A contract with a minimum also shows how the minimum was applied: minimum_included (the requests the minimum’s fee covers), minimum_excess (successes beyond them, at their rate) or minimum_top_up (what brings the month up to the minimum). Every line of a minimum carries its minimum_id, the id of that minimum of your contract; it is null on usage no minimum covers. When a minimum covered only part of the month — it started or ended inside it — its lines carry active_days and period_days, and the minimum was charged for those days only; both are null otherwise. The response lists the closed months among the 12 before the current one, newest first:

{
  "customer_id": "cus_...",
  "periods": [
    {
      "contract_id": "con_...",
      "month": "2026-08",
      "requests": 12345,
      "successes": 12000,
      "failures": 345,
      "billed_amount": { "currency": "USD", "micros": "5400000", "amount": "5.4" },
      "adjustments": { "currency": "USD", "micros": "-400000", "amount": "-0.4" },
      "amount_due": { "currency": "USD", "micros": "5000000", "amount": "5" },
      "lines": [
        {
          "line_no": 1,
          "kind": "usage",
          "price_rule_id": null,
          "price_per_thousand": { "currency": "USD", "micros": "450000", "amount": "0.45" },
          "quantity": 12000,
          "amount": { "currency": "USD", "micros": "5400000", "amount": "5.4" },
          "minimum_id": null,
          "active_days": null,
          "period_days": null
        }
      ],
      "closed_at": "2026-09-01T00:05:00.000Z"
    }
  ]
}

price_rule_id is null on usage at your contract’s own rate; on the top-up of a minimum counted in money, whatever it covers; and on the top-up of a minimum counted in requests in a month with no successes it covers. Every other line names a price rule of your contract.

A month is only listed here after it closes; the current, still-open month is only visible through GET /v1/usage, as usage before minimums.