Record a billing event (fact only)

POST 
/events

Accepts one event and writes it synchronously. Events are fact records only (e.g., outcomes) and do not carry pricing/cost semantics. Idempotency is server-side via the resolved billing_user_id and request_hash.

Request

Responses

200

Idempotent replay

201

Created

401

Unauthorized

403

Forbidden (realm/account mismatch, billing account not derived from your session/principal, or insufficient role)

409

Conflict (idempotency body mismatch, duplicate adjustment, or an unsupported provider capability). Unsupported mutations return BILLING.PAYMENT_PROVIDER_CAPABILITY_UNSUPPORTED before Customer creation, provider I/O, or local state mutation. Concurrent use of the same Idempotency-Key returns WRITE.IDEMPOTENCY_IN_PROGRESS; different keys are independent requests whose final ordering is owned by the PSP. A subscription Checkout with mixed group, currency, or recurrence facts is rejected before Customer lookup or provider I/O. Missing or inconsistent selected Customer bindings return BILLING.PAYMENT_PROVIDER_CUSTOMER_REQUIRED or BILLING.PAYMENT_PROVIDER_CUSTOMER_CONFLICT without silently replacing the binding.

422

Unprocessable Entity (validation, visibility, or binding/meter unresolved)

429

Rate limited

Response Headers

Retry-After

Seconds to wait before retry.

503

Provider unavailable, transient failure, or an ambiguous provider mutation reported as BILLING.PAYMENT_PROVIDER_OUTCOME_UNKNOWN.