Skip to content

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 ​

  1. Obtain both a store grant and a connection grant.
  2. Replace the full status catalog with a monotonically increasing catalog_revision.
  3. Send each order transition with a stable event_id, increasing revision, source timestamp, state dimensions and tags.
  4. 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.

  1. Request only the new scopes your integration needs. Existing credentials do not receive them automatically.
  2. List the store connections and retain the granted connection_id values.
  3. Publish a complete, revisioned order-status catalog for each connection.
  4. Send monotonic source-state events for each order. Reuse an event_id only with the identical payload.
  5. Use refresh_state_only backfills to refresh historical state.
  6. 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.

Public API documentation for Revi.