Order source states and safe invitations
API 2026-10 lets an integration report the original order state without deciding whether Revi sends a review request. The merchant configures that policy in Revi.
Sequence
- Obtain both a store grant and a connection grant.
- Replace the full status catalog with a monotonically increasing
catalog_revision. - Send each order transition with a stable
event_id, increasingrevision, source timestamp, state dimensions and tags. - Read the effective policy and privacy-safe eligibility history when needed.
Unknown states are held (wait). Reusing a revision, event ID or idempotency key with different content returns 409; retry the same request unchanged after timeouts.
If the connection becomes unavailable during a catalog or source-state update, the request can return 403 owner_rejected. If it is already inactive when access is checked, it returns 404 connection_not_found. Verify the connection and its grants before retrying; a 403 may also report insufficient_scope.
Tags use exact, case-insensitive matching. They are synchronized by clients but configured as holds only by the merchant in Revi.
Backfills
refresh_state_only backfills return 202 and are structurally unable to create or re-enqueue invitations. They may cancel work that has not been accepted by Mailer. Always send an Idempotency-Key.
Adding this to an existing 2026-10 integration
These resources are an additive part of 2026-10: every other 2026-10 resource, scope and response is unchanged, so a working integration keeps working with no changes at all. There is no version migration to perform.
- Request only the new scopes your integration needs. Existing credentials do not receive them automatically.
- List the store connections and retain the granted
connection_idvalues. - Publish a complete, revisioned order-status catalog for each connection.
- Send monotonic source-state events for each order. Reuse an
event_idonly with the identical payload. - Use
refresh_state_onlybackfills to refresh historical state. - Read the effective policy and audit resources to show operators why an order is waiting, eligible or cancelled.
Keep legacy order writes during the coordinated module handover.
Safety guarantees
- A reused revision or idempotency key with a different payload returns
409, and the stored state is not overwritten. - Unknown source states fail closed as waiting.
- Public API clients cannot modify invitation policies or use a backfill to create invitations.
- Audit and eligibility responses never expose IP, user agent, email or other sensitive personal data.
See the 2026-10 reference.