usage.period.closed

POST

A month is invoiced and its usage numbers are final. Carries the application’s totals; the rows per grant come from GET /v1/usage?period=….

Authorizations

• apiKey
• grantToken

Parameters

Header Parameters

x-inboxcnx-signature

required

t=<unix seconds>,v1=<hex HMAC-SHA256>. The MAC covers <t>.<raw body> with the endpoint’s signing secret. During a secret rotation a second v1 carries the previous secret’s MAC. Reject a t older than 5 minutes.

string

Example

t=1761206400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

t=<unix seconds>,v1=<hex HMAC-SHA256>. The MAC covers <t>.<raw body> with the endpoint’s signing secret. During a secret rotation a second v1 carries the previous secret’s MAC. Reject a t older than 5 minutes.

x-inboxcnx-event-id

required

The envelope’s id. Stable across retries: dedupe on it.

string

The envelope’s id. Stable across retries: dedupe on it.

Request Body

Media typeapplication/json

object

id

required

string

>= 1 characters

createdAt

required

string

applicationId

required

string format: uuid

grantId

required

string | null format: uuid

externalUserId

required

string | null

type

required

string

Allowed values: usage.period.closed

data

required

object

period

required

string

/^\d{4}-(0[1-9]|1[0-2])$/

applicationId

required

string format: uuid

totals

required

object

activeGrantsPeak

required

integer

mails

required

integer

backfillMails

required

integer

gbMonths

required

number

Example

{
  "id": "usage.period.closed:9b2f0c4e-6a1d-4f3b-8c55-0d7e2a91b3c4:2026-10",
  "type": "usage.period.closed",
  "createdAt": "2026-10-23T08:00:00.000Z",
  "applicationId": "a3c1e8f2-4b7d-4e9a-9f10-6d2b8c5e7a41",
  "grantId": null,
  "externalUserId": null,
  "data": {
    "period": "2026-10",
    "applicationId": "a3c1e8f2-4b7d-4e9a-9f10-6d2b8c5e7a41",
    "totals": {
      "activeGrantsPeak": 12,
      "mails": 4180,
      "backfillMails": 900,
      "gbMonths": 3.2
    }
  }
}

Responses

2XX

Delivered. The body is ignored.

default

A 408, 429, 5xx, a timeout or a network error is retried with backoff. Any other status, and a redirect (never followed), ends the delivery as failed.