Skip to main content

Self-serve orchestration

This guide documents self-serve purchase orchestration as a product workflow, not API syntax.

Prereqs​

Flow responsibilities​

  1. Product UI presents purchasable choices and constraints.
  2. Backend creates checkout/portal session from catalog selections.
  3. Provider webhook finalizes payment and drives durable state transition.
  4. Product runtime reflects effective plan/funding changes.
  5. Portal session handles subsequent customer-managed changes.

Invariants that must hold​

  • Webhook event processing is idempotent and order-tolerant.
  • Internal subscription state is never finalized from client redirect alone.
  • Provider event identity is deduplicated before state mutation.

Subscription synchronization rules​

  • A provider subscription is expected to map to one subscription group at a time.
  • Subscription items are upserted by (subscription_id, catalog_price_id).
  • Active/trialing conflict rules for non-stackable groups are enforced during checkout and at persistence layer.

Metadata-driven behavior​

Catalog metadata can drive post-purchase behavior:

  • plan assignment mapping (metadata.billing_plan_code)
  • grant-binding mapping (metadata.grants)
  • optional gate bundle candidate (metadata.gating.bundle)

Grant mapping merge rule:

  • product metadata and price metadata are both considered
  • when the same grant_program_code appears in both, price metadata overrides product metadata

Model these in catalog configuration, not in frontend-only logic.

Common failure modes​

  • Redirect succeeded but webhook delayed: keep pending state and poll with timeout policy.
  • Duplicate webhook delivery: dedupe by provider event identity.
  • Conflicting upgrades/downgrades in short window: enforce deterministic precedence and effective-time logic.

Operational signals to monitor​

  • Checkout success to webhook-finalized latency.
  • Duplicate and out-of-order webhook rate.
  • Mismatch count between provider view and internal effective assignment.

Verify​

  • Simulate provider webhook delay and duplicate delivery without double transition.
  • Confirm user-visible entitlement change only after finalization event.
  • Confirm support can trace purchase session to final assignment/funding state.

Next​