Usage CSV formats

All files are UTF-8 with a header row, ISO 8601 dates, a decimal point and no thousands separators. period_end is exclusive: September is 2026-09-01 to 2026-10-01.

Monthly aggregate

account_id,metric_name,period_start,period_end,usage_units
2077,api_requests,2026-07-01,2026-08-01,22000
2077,exports,2026-07-01,2026-08-01,200

A row spanning more than one month is assigned to the month it starts in and flagged. With aggregate rows, rollover expiry applies at month granularity, and statements say so.

Line-level events

account_id,metric_name,usage_at,quantity,event_id,status,retry_of
2077,api_requests,2026-07-14T09:31:02Z,1,evt_8f2c,ok,
2077,api_requests,2026-07-14T09:31:05Z,1,evt_8f2d,failed,
2077,api_requests,2026-07-14T09:31:09Z,1,evt_8f2e,ok,evt_8f2d

• event_id is optional. Rows with the same account, metric and event id are counted once, within a file and across files.
• status is ok or failed; retry_of names the event a row retries. Each contract decides whether failed requests and retries count.
• Timestamps are stored in UTC; your workspace's close time zone decides which day an event falls on.

Imports are all-or-nothing and idempotent

• If any row is invalid, nothing is imported, and every invalid row is listed with its line number and reason.
• Uploading a byte-identical file again changes nothing.
• Two different files that cover the same account and month both import, and the overlap is flagged until you void one.
• Usage for an account id with no contract is held. It counts nowhere until you attach it to a contract or ignore it.
• A month with no usage is treated as zero and blocks approval of its period until someone acknowledges it.

Billed amounts

To compare expected with what was actually invoiced, upload account_id,period_start,period_end,billed_amount,note. Once Stripe is connected, finalized invoices are recorded automatically.