Rate Usage Period

Legacy supplied-facts rating is rejected at commit. Use DRAFT_BILLING_CYCLE with a stored sealed period and independent Finance review.

POST/api/v1/billing/dispatch

Request

curl -X POST "<BASE_URL>/api/v1/billing/dispatch" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "X-CQRS-Action: RATE_USAGE_PERIOD" \
  -H "Content-Type: application/json" \
  -d '{
    "current_status": "OPEN",
    "meters": [
      {
        "meter": {
          "aggregation": "SUM",
          "code": "string",
          "created_at": "2026-01-15T09:30:00Z",
          "display_name": "string",
          "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "status": "ACTIVE",
          "tenant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "unit": "string"
        },
        "price": {
          "billing_cycle": "MONTHLY",
          "currency": "USD",
          "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "is_active": true,
          "model": "FLAT",
          "product_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
          "unit_amount": "string"
        },
        "records": [
          {
            "idempotency_key": "string",
            "quantity": "string"
          }
        ]
      }
    ],
    "period_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  }'

Authorization

Minimum role: FinanceThe caller must hold this role or a higher one.
Action: RATE_USAGE_PERIOD

Headers

AuthorizationstringRequired
Access token of the signed-in user, as a Bearer token. It identifies the user, their role and the workspace.
X-CQRS-ActionstringRequired
Names the command to run. Must be RATE_USAGE_PERIOD for this endpoint.
Content-TypestringRequired
Always application/json.
X-Idempotency-KeystringOptional
A key you choose that is unique to this attempt. A command repeated with the same key is not applied a second time.
X-Correlation-IdstringOptional
Your own identifier for the request. Returned in the x-correlation-id response header; generated when you leave it out.

Request body

current_statusenumRequired
A metering period's progress from open to invoiced.
Allowed values
- OPEN
- CLOSING
- CLOSED
- INVOICED
- NO_CHARGE
- CARRIED_FORWARD
OPEN
Accepting usage events.
CLOSING
Boundary passed; inside the late-arrival grace window.
CLOSED
Sealed. Late events go to the next open period.
INVOICED
Rated onto an invoice.
NO_CHARGE
Independently reviewed zero-charge period.
CARRIED_FORWARD
Positive charges retained for a subsequent invoice.
metersarray of objectRequired
RAW events per meter, not pre-computed totals.
3 child fields
- meterobjectRequired
  A tenant-defined meter.
  9 child fields
  aggregationenumRequired
  How a period's events collapse to one number.
  Allowed values
  SUM
  MAX
  LAST
  UNIQUE_COUNT
  SUM
  Total consumption over the period.
  MAX
  Highest value seen — peak provisioning.
  LAST
  Value at period close — current state, e.g. storage.
  UNIQUE_COUNT
  Distinct subjects — monthly active users.
  codestringRequired
  Stable identifier used by producers and printed on invoices. Immutable once events reference it — renaming a meter orphans its history.
  minimum length 1
  maximum length 64
  created_atdate-timeRequired
  No description yet.
  display_namestringRequired
  No description yet.
  minimum length 1
  iduuidRequired
  No description yet.
  statusenumRequired
  Lifecycle of a meter definition. Meters are archived, never deleted: usage events reference them and an invoice must stay explicable years later.
  Allowed values
  ACTIVE
  ARCHIVED
  tenant_iduuidRequired
  No description yet.
  unitstringRequired
  No description yet.
  system_metricenum or nullOptional
  Set when this meter is one of the built-ins, so system-emitted usage and tenant-defined usage share one pipeline.
  Allowed values
  API_CALL
  AGENT_TASK
  MEETING_MINUTES
  EMAIL_SENT
  CONTRACT_GENERATED
  ACTIVE_SEATS
- priceobjectRequired
  A resolved price for a product — Salesforce's PricebookEntry, Stripe's Price. Split out from the product because ONE product legitimately has many prices: per currency, per billing cycle, per pricing model. Holding a single base_price on the product is what forces every tiered plan to bill as flat.
  12 child fields
  billing_cycleenumRequired
  No description yet.
  Allowed values
  MONTHLY
  QUARTERLY
  ANNUAL
  SEMI_ANNUAL
  currencystringRequired
  No description yet.
  iduuidRequired
  No description yet.
  is_activebooleanRequired
  No description yet.
  modelenumRequired
  No description yet.
  Allowed values
  FLAT
  TIERED
  VOLUME
  SEAT_BASED
  product_iduuidRequired
  No description yet.
  unit_amountstringRequired
  Flat and seat-based prices use this. Tiered/volume prices ignore it.
  included_unitsstringOptional
  Units included before metering starts.
  Default
  0
  meter_iduuid or nullOptional
  The meter this price rates. Required for metered prices and the link that was missing: without it nothing can answer "which price applies to this meter's usage", and a period cannot be rated at all.
  tier_modeenumOptional
  No description yet.
  Allowed values
  GRADUATED
  VOLUME
  Default
  GRADUATED
  GRADUATED
  Bracketed — each tier prices only its own slice (income-tax style).
  VOLUME
  Landed — the tier the total reaches prices every unit.
  tiersarray of objectOptional
  No description yet.
  3 child fields
  unit_pricestringRequired
  No description yet.
  flat_feestringOptional
  Charged once when this tier is used at all.
  Default
  0
  limitstring or nullOptional
  Inclusive upper bound. None marks the final, unbounded tier.
  usage_aggregationenum or nullOptional
  Set for metered prices: how the period's events collapse to one number. Falls back to the meter's own aggregation when absent.
  Allowed values
  SUM
  MAX
  LAST
  UNIQUE_COUNT
  SUM
  Total consumption over the period.
  MAX
  Highest value seen — peak provisioning.
  LAST
  Value at period close — current state, e.g. storage.
  UNIQUE_COUNT
  Distinct subjects — monthly active users.
- recordsarray of objectRequired
  No description yet.
  4 child fields
  idempotency_keystringRequired
  No description yet.
  quantitystringRequired
  No description yet.
  sequenceintegerOptional
  Orders events within the period; decides LAST aggregation.
  Default
  0
  at least 0
  subjectstring or nullOptional
  No description yet.
period_iduuidRequired
No description yet.
commitmentobject or nullOptional
Prepaid balance to draw against, when the account holds one.
11 child fields
- account_iduuidRequired
  No description yet.
- balancestringRequired
  committed - drawn. Stored so entitlement checks can read it without re-summing the whole draw history on every request.
- committed_amountstringRequired
  No description yet.
- currencystringRequired
  No description yet.
- drawn_amountstringRequired
  No description yet.
- iduuidRequired
  No description yet.
- tenant_iduuidRequired
  No description yet.
- term_enddate-timeRequired
  No description yet.
- term_startdate-timeRequired
  No description yet.
- treatmentenumRequired
  What happens to whatever is left at term_end.
  Allowed values
  FORFEIT
  ROLLOVER
  TAKE_OR_PAY
  FORFEIT
  Unused balance is lost — the customer bought capacity, not units.
  ROLLOVER
  Unused balance carries into the next term.
  TAKE_OR_PAY
  The customer owes the difference between commitment and consumption.
- trued_up_atdate-time or nullOptional
  No description yet.

Response

Status 202. The command was applied. The body reports the outcome and, where the command changes a record, that record's new state.

successbooleanRequired
true when the command was applied.
error_messagestringRequired
Empty when the command was applied.
projected_stateobjectOptional
The record as it stands after the command.
event_payloadobjectOptional
The event the command recorded.
insightsarray of objectOptional
Advisory notes about the result. Each has a code, a message and an impact number.

Errors

Every error carries an HTTP status. Where it also carries a code, branch on the code, not on the message.

400X-CQRS-Action is missing or names a command this route does not accept. Send RATE_USAGE_PERIOD.
400DOMAIN_ROUTINGThe body is not a valid command. Check the required fields and their types.
401The access token is missing, expired or not valid.
401L1_AUTHThe caller's role is below finance or the caller has no access to this record.
403L1_POLICYA business rule refused the command. The message names the rule.
409L1_IDEMPOTENCYA command with this idempotency key was already applied.
409CONFLICTThe command would duplicate a record that must be unique.
500L3_COMMITThe command was valid but could not be saved.