Allowance Periods — Proposed Guide

Planned API — Reference Only

Allowance Periods: Periods define when an allocation applies and how consumption is attributed. Calendar months, rolling windows and employer-specific…

Overview

Periods define when an allocation applies and how consumption is attributed. Calendar months, rolling windows and employer-specific cycles have different boundaries.

Key concepts

Specify timezone, start and end dates, and any rollover policy. Keep closure separate from allocation expiry.

Implementation considerations

No rollover commitment is established here. Late expense submissions require an explicit policy for which period receives the consumption.

Illustrative data model

This local fixture shows a possible representation for the concepts above. It is not an endpoint response, production configuration or a claim that the described capability is implemented.

JSON fixture

Fictional concept fixture

{
  "reference_only": true,
  "topic": "Allowance Periods",
  "period_id": "period_example_123",
  "start_date": "2026-01-15",
  "end_date": "2026-01-31",
  "timezone": "Etc/UTC"
}

Design review checklist

Document which organization owns the allowance periods representation and which actor may view or change it.
Test the boundaries of period id, start date, end date, timezone using synthetic values, including missing or inconsistent references.
Before future implementation, obtain an approved contract and review failure behavior. This documentation does not authorize production activation.

Proposed data types

Illustrative field dictionary
Name	Type	Description
period_id	string	Stable fictional period reference; not a secret and not evidence that a resource exists.
start_date	string (date)	Synthetic calendar date in YYYY-MM-DD form; period inclusivity must be defined by the future contract.
end_date	string (date)	Synthetic calendar date in YYYY-MM-DD form; period inclusivity must be defined by the future contract.
timezone	string	Explicit timezone for interpreting period boundaries.

Allowance Balances

Allowances & Fleet

Allowance Transactions