Skip to main content

Ingest

Scope​

This page defines direct ingest behavior for /gate/ingest.

It does not define the events API or event-to-ratings policy pipeline. Those are documented in Events and ratings.

Ingest endpoint role​

Direct ingest (/gate/ingest) is a service-to-service usage write path that writes priced commit facts without requiring a lease from authorize.

Required inputs​

  • Idempotency-Key is required.
  • feature_code is required and must be valid.
  • At least one of:
    • quantity_minor
    • meters[]
  • If budget_id is provided, it must be a valid UUID.

Quantity semantics​

  • meters[] omitted:
    • ingest selects one allowed meter for the expected semantic kind (prefers primary).
  • quantity_minor omitted:
    • canonical feature quantity becomes sum(meters[].quantity_minor).
  • quantity_minor and meters[] both present:
    • feature-level canonical quantity uses quantity_minor.
    • meter-level quantities drive pricing line breakdown.

Meter validation semantics​

  • Every meter line must be allowlisted for the feature in the expected semantic kind.
  • If auto-registry is enabled, unknown meters may be auto-created and mapped, then revalidated.
  • If no valid mapping remains, ingest rejects with 422 meter_not_allowed_for_feature.
  • Entitlement is still enforced for ingest.

Pricing and write semantics​

  • Pricing is computed at ingest time and written as authoritative snapshots.
  • Missing meter prices do not reject ingest:
    • line pricing for those meters uses missing-pricing snapshots with zero amount
    • commit remains applied
    • reason code includes pricing_not_configured

Semantic-kind expectation for direct ingest​

Direct ingest expects activity.

Idempotency behavior​

  • Ingest idempotency is account-scoped.
  • Same key + same request hash returns stored commit response snapshot.
  • Same key + different request hash returns conflict.

Hint semantics at ingest​

Ingest may emit:

  • pricing.meter_price_missing
  • pricing.contract_term_invalid
  • pricing.changed (when client pricing fingerprint/unit price differs from server result)

Verify checklist​

  • Replay with same idempotency key returns the same commit response.
  • Invalid feature-meter mapping returns 422.
  • Missing pricing produces zero-priced lines and corresponding reason code.
  • Canonical feature quantity matches documented derivation rules.