Use Cases (QA)

This page mirrors /docs/story/operations.md to keep the QA catalog aligned with the canonical operations and use-case inventory.

This page is the complete, headless-only operating catalog for the G3N Retail Stack. It expands merchant SOPs (routines/playbooks), the full objectives and operations the stack provides, and an exploded use-case catalog. It is contract-only and aligns to the public service surfaces (API Gateway + direct Lambda + CLI). For concrete scenario walkthroughs and QA status, see /story/super-usecases.html.

How to read this page

• SOPs / Playbooks: merchant routines (what gets done, in order, headlessly).
• Operations inventory: all business actions the stack supports (by service/domain).
• Use cases: explicit scenarios, edge cases, and expected outcomes.

For test results validating these operations, see QA Outcomes.

Reference map (public docs)

• Common Contract: Start Here, Headers & Identity, Request Context, Idempotency & Retry, Role Matrix, Performance & SLOs
• Story: Story, Super Use Cases
• Services: UAS, USM, OFM, MRS, PVM, PMC, PPM, PCM, ICS, SCM, CRM, Influencer, Accounting, IPM, RBS, UTL, UCP

Business operating artifacts (inputs before tech)

These are the business‑side artifacts that must exist to run the stack correctly.

• Assortment strategy: seasonal calendar, launch windows, lifecycle gates.
• Vendor governance: onboarding criteria, contract terms, lead times, compliance obligations.
• Pricing policy: base price rules, markdown cadence, approval thresholds, promo windows.
• Channel policy: fulfillment SLAs, return/refund rules, tender acceptance, tax handling.
• Inventory policy: replenishment strategy, transfer approvals, cycle count schedules.
• Customer policy: consent rules, loyalty economics, fraud/hold criteria.
• Finance/attribution: cost‑centre taxonomy, usage attribution rules, export cadence.
• Compliance & retention: legal‑hold triggers, export/purge criteria, audit requirements.

Business governance checkpoints (when decisions must be made)

• Onboarding checkpoint: legal entity verified, owner assigned, initial facility and channel scope approved.
• Assortment checkpoint: vendor/brand eligibility approved; taxonomy coverage complete; lifecycle rules agreed.
• Pricing checkpoint: base price rules + approval thresholds set; markdown cadence approved.
• Channel launch checkpoint: fulfillment SLAs, return policy, tender rules, and tax policy confirmed.
• Procurement checkpoint: supplier terms + budget authorized; PO approval thresholds set.
• Inventory checkpoint: replenishment rules + transfer approvals set; cycle count schedule approved.
• Customer/loyalty checkpoint: consent policy + loyalty liability approved; fraud/hold rules set.
• Integration checkpoint: data‑sharing agreements signed; downstream owners assigned; SLAs in place.
• Offboarding checkpoint: legal/compliance approval for export/purge; retention windows satisfied.

Decision owners (business accountability)

• Merchandising: assortment scope, lifecycle gates, publishability rules.
• Sourcing/Procurement: supplier eligibility, lead times, PO approvals, RTV policy.
• Pricing/Revenue: price lists, markdown cadence, promo approval policy.
• Operations/Inventory: facility hierarchy, transfer approvals, replenishment & count cadence.
• Sales/Omnichannel: channel policy, fulfillment SLAs, return/tender rules.
• Customer/Marketing: consent policy, loyalty economics, gift card rules.
• Finance/Accounting: cost‑centre taxonomy, usage attribution, export cadence.
• Compliance/Legal: retention/legal‑hold rules, export/purge approvals.

Input dependency map (stack-wide)

These are the inputs required by the stack, grouped in dependency order and showing where they originate.

Foundational inputs (must exist before anything else)

• Identity inputs (UAS + USM): email, passcode (or passcode set flow), optional payment metadata.
• Auth artifacts (USM): session_guid and/or x-api-key.
• Org inputs (OFM): orgcode, legal org name, org status (verified/active).

Operational spine inputs (required for most business workflows)

• Facilities (OFM): physical/legal/logical facility codes, time zone, facility status.
• Org governance (OFM): owner/member roles, cost centres, member↔logical assignments.
• Sales channels (OFM): channel_code, market code, locale codes, optional channel config.

Master data inputs (required for catalog and sellability)

• Suppliers (PVM): vendor/manufacturer identity + status.
• Taxonomy (PVM): division/department/category/season.
• Product model (PVM): OGM + options/option groups.
• Product records (PVM): styles/variants + identifiers/aliases/barcodes + compliance attributes.

Downstream operational inputs (depend on the master spine)

• Publish control (PMC): publish profiles and selectors (style/brand/category/all).
• Pricing (PPM): price lists/zones, pricing policy, approvals.
• Procurement (PCM): NPI, worksheets, POs, invoices.
• Inventory (ICS): receipts, adjustments, transfers, counts.
• Sales (SCM): orders, promises, shipments, tenders, returns.
• Customer/loyalty (CRM): customer data, consent, loyalty balances.
• Attribution (Influencer): profiles, campaigns, earnings/payouts.
• Integrations (IPM / RBS): webhook endpoints, CDC subscriptions, bulk imports/exports.
• Platform commerce (UCP): platform credentials, checkout sessions, webhook config, identity links.
• Offboarding (UTL): export/purge requests + verification criteria.

Input sources (headless only)

• Operator CLI / direct Lambda: used for bootstrap and privileged actions.
• API Gateway (service APIs): standard integrations and headless workflows.
• Bulk import/export (IPM): large data migrations, periodic syncs.
• Partner event feeds (RBS): ingest external events with verification.

Business ownership of inputs (who supplies what)

• Merchandising leadership: assortment strategy, seasonal calendar, product lifecycle gates, publishability policies.
• Sourcing/Procurement: vendor onboarding criteria, lead times, cost terms, PO approvals, return-to-vendor rules.
• Pricing/Revenue: price lists/zones, promo windows, approval thresholds, markdown cadence.
• Inventory/Operations: facility definitions, transfer policies, cycle‑count schedules, adjustment reason codes.
• Sales/Omnichannel: channel definitions, fulfillment policies, tender/return rules, SLAs.
• Customer/Marketing: consent policy, loyalty rules, gift card policy, fraud/hold criteria.
• Finance/Accounting: cost‑centre taxonomy, usage attribution rules, retention/legal‑hold policies.
• Compliance/Legal: data retention windows, export/purge criteria, audit trails.

Business operating cadence (headless)

• Daily: sales ingestion, inventory movements, tender settlement, usage rollups.
• Weekly: replenishment runs, promotion scheduling, vendor performance review inputs.
• Monthly: price list refreshes, supplier term updates, loyalty reconciliation, finance exports.
• Seasonal: assortment resets, bulk catalog updates, publish policy revisions.
• Ad‑hoc: incident‑driven offboarding, hotfix imports, emergency price/availability changes.

Business risk controls (inputs that prevent bad operations)

• Contract thresholds: max discount, min margin, tender limits.
• Policy constraints: no‑sale lists, embargoes, compliance exclusions.
• Quality gates: required fields, allowed status transitions, valid effective dates.
• Segregation of duties: approvals by role/cost‑centre; audit trail requirements.

Minimal bootstrap chain (greenfield)

1. Create owner identity (UAS) → verify email → set passcode.
2. Issue session/API key (USM).
3. Create org + verify status (OFM).
4. Create facilities + zones (OFM).
5. Create sales channel(s) (OFM).
6. Create suppliers + taxonomy (PVM).
7. Create OGM → style → variant (PVM).
8. Set pricing + publish (PPM → PMC).
9. Receive inventory + sell (PCM / ICS → SCM).

Input acquisition playbooks (headless)

A) Greenfield org bootstrap (minimum viable)

Inputs needed: owner email + passcode, orgcode/legal name, facility codes/timezone, channel code/market/locale.
Process: UAS → USM → OFM org → OFM facilities/zones → OFM channels.

B) Catalog ingest pipeline (vendor → taxonomy → model → product)

Inputs needed: suppliers, taxonomy hierarchy, OGM/option definitions, style/variant metadata, identifiers, compliance.
Process: PVM supplier + taxonomy → OGM + options → style → variants → identifiers/barcodes → comments/attachments (MRS).

C) Publish + price pipeline

Inputs needed: publish profile, channel context, price lists/zones, promo policy.
Process: PPM price setup → PMC publish run → online pointer set.

D) Procurement → inventory → sales pipeline

Inputs needed: NPI/worksheet/PO, receiving data, stock movements, orders, tender.
Process: PCM PO + receiving → ICS stock ledger → SCM orders/fulfillment → returns/refunds.

E) Integration + offboarding pipeline

Inputs needed: webhook endpoints, CDC cursor, bulk job manifests, export/purge requests.
Process: IPM webhooks/CDC/bulk → RBS subscriptions → UTL export/freeze/purge.

F) Legacy migration + continuous sync (bulk + CDC)

Inputs needed: legacy export files, mapping spec, canonical IDs, delta strategy, reconciliation rules.
Process: IPM bulk import dry‑run → validate mapping/constraints → import in slices → run CDC catch‑up until cutover → reconcile counts and keys.
Quality gates: referential integrity checks; error quarantine; post‑import reconciliation (counts + key‑spot checks).

G) Input quality gates (preflight + post‑ingest)

Inputs needed: policy thresholds (duplication, null rates), required‑field matrices, allowed status transitions.
Process: preflight validation on ingest (format/length/status) → idempotency keys → post‑ingest reconciliation (counts + samples).
Quality gates: reject on missing required fields; quarantine on partial failures; verify derived indexes and search planes.

Deep input classes and ingestion processes

These sections enumerate what inputs are required, where they come from, and how they are ingested into the stack.

Cross‑cutting reference inputs (shared across domains)

• Inputs required: org/facility/channel codes, market/locale codes, cost‑centre codes, lifecycle statuses, revision expectations.
• Input sources: governance policies, legal entity registers, localization plans.
• Ingestion path: OFM resolves/creates codes → downstream services accept codes as required fields.
• Validation gates: format/length checks; org status gates; non‑existent codes rejected.

External linkage & identity mapping inputs

• Inputs required: external identifiers, alias tags/values, barcode types, mapping to canonical IDs.
• Input sources: ERP/PLM/WMS exports, supplier master data, barcode registries.
• Ingestion path: PVM identifiers/aliases/barcodes → resolver endpoints for lookup.
• Validation gates: uniqueness among active (non‑doomed) records; type/value formats; cross‑field consistency.

Asset/document inputs (MRS)

• Inputs required: attachment payloads (images/docs), content metadata, tags, optional TTL/doom intent.
• Input sources: content systems, supplier documentation, internal QA.
• Ingestion path: MRS presign → upload → complete → attach reference in PVM/PMC comments or records.
• Validation gates: MD5 checks; gzip requirement; size caps; TTL/doom constraints.

Identity & access inputs (UAS / USM)

• Inputs required: email, passcode (or passcode set flow), optional payment metadata, org-bound service account intent.
• Input sources: org owner/operator, internal onboarding admin tool, or trusted provisioning system.
• Ingestion path: UAS create → UAS verify → USM session create; USM API key create for service accounts.
• Validation gates: email uniqueness; passcode policy/reuse windows; API key org binding; session validity/expiry.

Org + facility spine inputs (OFM)

• Inputs required: orgcode, legal org name; physical/legal/logical facility codes, time zone; member/role assignments; cost-centre codes; sales channel codes and locales.
• Input sources: operator onboarding checklist; facility registry; legal entity records.
• Ingestion path: OFM org create → org status set → facility create → member/role assignments → sales-channel create/config.
• Validation gates: org status gates writes; code format; role/profile constraints; logical assignment validity.

Channel context inputs (OFM)

• Inputs required: channel_code, market_code, locale codes, optional channel config document.
• Input sources: commerce/channel policy; market expansion plan; localization settings.
• Ingestion path: OFM sales-channel create → presign config → upload → complete.
• Validation gates: unique channel_code; locale/market format; config size/type.

Catalog master inputs (PVM + MRS)

• Inputs required: vendors/manufacturers, brands, taxonomy hierarchy, OGM + options, styles/variants, identifiers/aliases/barcodes, compliance and lifecycle attributes, attachments.
• Input sources: vendor master files, product master, merchandising taxonomy, compliance catalog, image/content systems.
• Ingestion path: PVM supplier create → taxonomy create → OGM + options → style/variant create → identifiers/barcodes/aliases → comments/attachments (MRS presign).
• Validation gates: style requires primaries + valid category; brand links must cover suppliers; identifiers/barcodes unique among non‑doomed; status transitions enforced.

Publish control inputs (PMC)

• Inputs required: publishability profile, selector scope (style/brand/category/all), channel/logical context, PVM snapshot readiness.
• Input sources: merchandising policy; channel launch plan; catalog status.
• Ingestion path: publish-profile set → publish run start → publish run step → online pointer set.
• Validation gates: selector eligibility; only one online revision; pointer references valid revision.

Pricing & promotion inputs (PPM)

• Inputs required: base prices, price lists/zones, approval policy, promo definitions, channel/facility assignments.
• Input sources: pricing strategy, promo calendar, tax/compliance policy.
• Ingestion path: price list/zone set → assignments → price set → approval submit/approve → promotion create/end.
• Validation gates: currency/UOM consistency; approval thresholds; promo overlap/stacking policy.

Procurement inputs (PCM)

• Inputs required: NPI metadata, worksheet lines, PO lines, invoice data, RTV reasons, vendor performance inputs.
• Input sources: merchandise planning, supplier contracts, inbound receiving.
• Ingestion path: NPI create/submit/approve → worksheet create/submit → PO create/approve/issue → receipt → invoice match/dispute/resolve.
• Validation gates: approval thresholds; matching/tolerance policy; RTV window policy.

Inventory inputs (ICS)

• Inputs required: receiving records, transfer requests/shipments, adjustment reasons, cycle count plans, consignment states.
• Input sources: warehouse operations, procurement receipts, sales fulfillment.
• Ingestion path: receive/putaway → stock transitions → transfer request/ship/receive → count submit/approve → adjustments.
• Validation gates: facility/logical scoping; negative stock policy; transfer approval gates.

Sales inputs (SCM)

• Inputs required: order lines (variant IDs/identifiers), pricing resolution, tax policy, customer/delivery data, tender details.
• Input sources: POS/ecom/channel apps, customer systems, tax policy systems.
• Ingestion path: order create/place → promise/allocate/commit → fulfillment → tender capture/settle → returns/refunds.
• Validation gates: inventory commitments; tender state; tax policy versioning.

Customer & loyalty inputs (CRM)

• Inputs required: customer identifiers, consent flags, loyalty policy, gift card data, fraud flags/holds.
• Input sources: channel customer capture, marketing opt‑in systems.
• Ingestion path: customer create → consent set → loyalty earn/redeem/adjust → gift card issue/redeem → fraud/hold actions.
• Validation gates: consent prerequisites for certain exports; fraud holds block redeem.

Influencer/affiliate inputs (Influencer)

• Inputs required: profile data, campaign rules, attribution events, payout preferences.
• Input sources: affiliate programs, marketing attribution systems.
• Ingestion path: profile create → campaign create → attribution record → earnings hold/release → payout submit.
• Validation gates: campaign status; payout readiness; clawback policy.

Integration inputs (IPM / RBS)

• Inputs required: webhook endpoints + secrets, CDC cursor params, bulk job manifests, subscription endpoints.
• Input sources: downstream systems, data pipelines, partner integrations.
• Ingestion path: IPM webhook create/replay; CDC list; bulk import/export; RBS subscription register/verify/test.
• Validation gates: endpoint verification; replay window limits; continuation tokens.

Telemetry inputs (Accounting)

• Inputs required: per‑request usage events, storage usage metrics, org/cost‑centre attribution.
• Input sources: service emission; scheduled rollups.
• Ingestion path: usage record → rollup → export batch/schedule.
• Validation gates: org attribution required; cccode format.

Offboarding inputs (UTL)

• Inputs required: export request scope, purge reason, legal‑hold flags, verification checklist.
• Input sources: operator workflows, compliance/legal requests.
• Ingestion path: export request → export complete → offboarding request → freeze → purge → verify.
• Validation gates: legal‑hold blocks purge; export must complete before purge.

Idempotency, ordering, and revision inputs (cross‑cutting)

• Inputs required: idempotency token (write requests), expected_revision (revisioned updates), monotonic timestamps for event ingestion.
• Input sources: client integration layer or operator CLI.
• Ingestion path: include tokens + expected revision on all updates; write surfaces use optimistic concurrency and fail on revision mismatch.
• Validation gates: reject missing/invalid expected_revision on update; idempotency token reused only for safe retries.

Input normalization & canonicalization (cross‑cutting)

• Inputs required: canonical formats for codes (orgcode, facility codes, channel codes), identifiers, and cost centres.
• Input sources: upstream systems or operator provisioning.
• Ingestion path: normalize casing/whitespace before persistence; validate against regex/length constraints.
• Validation gates: enforce code format and reject ambiguous values; reject mixed source of truth (header vs body mismatches).

Bulk import & CDC inputs (IPM/RBS)

• Inputs required: bulk manifests, file checksums, schema version, CDC cursor/partition keys.
• Input sources: legacy exports, upstream change feeds.
• Ingestion path: IPM bulk import (manifest → chunked ingest → continuation) and CDC subscribe (cursor → deliver → ack).
• Validation gates: manifest integrity checks; schema version compatibility; cursor monotonicity.

Error capture, quarantine, and reconciliation inputs

• Inputs required: error buckets/queues, reconciliation thresholds, sampling plan for verification.
• Input sources: system‑generated on ingest failure or drift detection.
• Ingestion path: per‑record errors are quarantined; reconciliation job replays failed subsets; runbooks define acceptance thresholds.
• Validation gates: any unresolved quarantines block cutover; reconciliation requires counts + key sampling.

Search/index propagation inputs (derived planes)

• Inputs required: reindex scopes, index version IDs, index mapping metadata, cutoff timestamps.
• Input sources: operator jobs, schema/index change tickets.
• Ingestion path: emit derived index items on write; reindex jobs for backfill and new index versions.
• Validation gates: alias cutover only after reconciliation; rollback keeps previous index version intact.

Workflow-specific input checklists (deep)

Onboard a new org (minimum viable)

• Required inputs: owner email + passcode, orgcode/legal name, facility codes/timezone, channel code/market/locale.
• Ingestion process: UAS → USM → OFM org → OFM facilities/zones → OFM channels.
• Blocking gates: org must be verified before writes; facilities required before inventory/sales ops.
• Business sign‑off: legal entity verified; operational owner assigned; initial channel policy approved.

Ingest catalog (vendor → taxonomy → model → product)

• Required inputs: vendor/manufacturer, brand, taxonomy tree, OGM/option definitions, style/variant metadata, identifiers/barcodes, compliance.
• Ingestion process: PVM supplier/taxonomy → OGM/options → style/variant → identifiers/aliases/barcodes → comments/attachments (MRS).
• Blocking gates: category must be valid/active; suppliers must include primaries; identifiers unique among non‑doomed.
• Business sign‑off: assortment scope approved; vendor/brand contracts active; compliance attributes provided.

Publish + price

• Required inputs: publish profile, channel/logical context, base prices, price lists/zones, promo policy.
• Ingestion process: PPM price set → PMC publish run → online pointer set → price resolve checks.
• Blocking gates: publishable variant status; approval thresholds; pointer set requires valid revision.
• Business sign‑off: pricing approvals complete; channel launch readiness confirmed; promo windows aligned.

Procure → receive → stock

• Required inputs: NPI/worksheet lines, PO lines, invoices, receiving data.
• Ingestion process: PCM NPI/worksheet/PO → receipt → invoice match → ICS stock transitions.
• Blocking gates: approvals required before issue; receiving required before stock movements.
• Business sign‑off: budget authorized; supplier terms confirmed; receiving schedule agreed.

Sell → fulfill → return

• Required inputs: order lines, pricing/tax policies, customer/tender data, inventory commitments.
• Ingestion process: SCM order create/place → promise/allocate/commit → fulfillment → tender settle → returns/refunds.
• Blocking gates: inventory commit required for shipment; tender capture before settlement; refund requires return state.
• Business sign‑off: channel policy enforced (returns, tender); SLA commitments confirmed.

Customer/loyalty lifecycle

• Required inputs: customer identifiers, consent, loyalty policy, gift card data.
• Ingestion process: CRM customer create → consent set → loyalty earn/redeem → gift card issue/redeem → fraud/hold checks.
• Blocking gates: consent gates exports; fraud holds block redemption.
• Business sign‑off: consent policy approved; loyalty liability accounted; fraud rules set.

Integration & data exchange

• Required inputs: webhook endpoints + secrets, CDC cursor, bulk job manifests, subscription endpoints.
• Ingestion process: IPM webhook + CDC + bulk; RBS subscription register/verify/test.
• Blocking gates: verification required before delivery; replay windows enforced.
• Business sign‑off: data‑sharing agreements in place; downstream owners assigned; SLAs agreed.

Offboarding & export

• Required inputs: export scope + reason; legal‑hold flag; purge verification checklist.
• Ingestion process: UTL export request → verify → freeze → purge → verification.
• Blocking gates: legal‑hold blocks purge; export completion required.
• Business sign‑off: legal/compliance approval for purge; retention requirements satisfied.

Bulk migration cutover (legacy → stack)

• Required inputs: mapping spec, canonical ID list, preflight validation reports, CDC cursor and cutover window.
• Ingestion process: IPM bulk import dry‑run → resolve mapping errors → bulk import in slices → CDC catch‑up → cutover → reconciliation.
• Blocking gates: unresolved mapping errors; reconciliation counts not within thresholds; CDC lag not caught up.

Drift remediation & reconciliation

• Required inputs: drift detector output (counts, samples, missing IDs), replay window, quarantine manifest.
• Ingestion process: reindex/backfill job → replay failed subset → verify counts/sample → close incident.
• Blocking gates: missing IDs persist after replay; index/sample mismatch beyond threshold.

Stack-wide objectives (complete)

• Identity and access governance (users, sessions, API keys, roles).
• Org and facility spine (legal/physical/logical facilities, zones, cost centres, teams, channels).
• Product truth and vendor metadata (catalog, taxonomy, identifiers, compliance, comments).
• Publish control (channel/logical sellability, revisioned snapshots, rollbacks).
• Pricing and promotions (price lists/zones, approvals, promos, policy).
• Procurement lifecycle (NPI, worksheets, POs, receiving, invoice match, RTV).
• Inventory control (stock ledger, reservations, allocations, transfers, counts, adjustments).
• Sales cycle (orders, promises, fulfillment, returns, tenders, tax).
• Customer and loyalty (customer truth, consent, loyalty, gift cards, fraud flags).
• Influencer/affiliate attribution (campaigns, earnings, payouts).
• Integration plane (webhooks, CDC, bulk import/export, KPI signals).
• Event bus ingest/delivery (partner event subscriptions and delivery).
• Accounting telemetry (usage emission, rollups, export pipelines).
• Offboarding (export → freeze → purge with verification).
• Platform commerce (UCP checkout, signed order webhooks, OAuth 2.0 identity linking).
• Auditing and retention (event trails, inbox/comment systems, legal-hold policy alignment).

Merchant SOPs / Playbooks (expanded)

1) Org onboarding and access governance

• Objective: establish a verified org with owner access and security posture.
• Headless flow:
  • Create owner identity + verify email (UAS).
  • Issue session and/or service API key (USM).
  • Create org and set status to verified (OFM).
  • Set initial owner/member roles and optional time-bounded grants (OFM).
• Outputs: active org, owner/member roles, usable session/key.

2) Facility spine buildout

• Objective: define physical/legal/logical facilities for operations.
• Headless flow:
  • Create physical facility + legal entity (OFM).
  • Create logical facilities (warehouse/store/showroom) + zones (OFM).
  • Assign members or service accounts to logicals (OFM).
• Outputs: facility hierarchy and operational scoping.

3) Sales channel declaration

• Objective: declare channels (pos/ecom/marketplace) and config.
• Headless flow:
  • Create channel code + market/locale config (OFM).
  • Upload/persist channel config (OFM presign + complete).
• Outputs: sales channels ready for publish + pricing overrides.

4) Catalog ingest + maintenance

• Objective: build vendor and product truth.
• Headless flow:
  • Create vendors/manufacturers + brands (PVM).
  • Create taxonomy (division/department/category/season) (PVM).
  • Create OGM, styles, variants, and identifiers/aliases/barcodes (PVM).
  • Add compliance metadata + comments/attachments (PVM + MRS).
• Outputs: active catalog with identifiers and compliance.

5) Publish sellable snapshots

• Objective: expose channel-ready sellability for downstream systems.
• Headless flow:
  • Configure publishability profile (PMC).
  • Start publish run (PMC) → snapshot from PVM → revision created.
  • Set online pointer; roll back by switching revisions if needed.
• Outputs: channel/logical sellable products with revision history.

6) Pricing & promotions cadence

• Objective: set base prices and time-bound promos.
• Headless flow:
  • Define price lists/zones and assignments (PPM).
  • Set item-level prices; route approvals if required (PPM).
  • Create/close promotions; resolve prices for channels (PPM).
• Outputs: approved prices/promos effective by channel/facility.

7) Procurement planning & purchase

• Objective: plan buys and receive against POs.
• Headless flow:
  • Create NPI + worksheets (PCM).
  • Create/approve/issue POs (PCM).
  • Receive against PO, record invoices, resolve disputes (PCM).
• Outputs: procurement ledger + receiving records.

8) Inventory movement & reconciliation

• Objective: keep stock accurate across locations.
• Headless flow:
  • Record receipts, putaway, pick/pack/ship, adjustments (ICS).
  • Create transfer requests and shipments; receive at destination (ICS).
  • Cycle count + approve/reject reconciliation (ICS).
• Outputs: accurate stock by location + transfer history.

9) Sales & fulfillment

• Objective: capture sales and fulfill orders end-to-end.
• Headless flow:
  • Create/place order and promise/allocate stock (SCM + ICS).
  • Create shipments and progress pick/pack/ship/deliver (SCM).
  • Handle returns/refunds/tender settlement (SCM).
• Outputs: sales ledger + fulfillment timeline.

10) Customer + loyalty lifecycle

• Objective: manage customer truth and loyalty balances.
• Headless flow:
  • Create customer + capture consent (CRM).
  • Earn/redeem/adjust loyalty; issue gift cards (CRM).
  • Apply fraud or hold flags where needed (CRM).
• Outputs: customer history + loyalty ledger.

11) Integration & data exchange

• Objective: keep external systems in sync.
• Headless flow:
  • Register webhooks and CDC feeds (IPM).
  • Run bulk imports/exports with continuation (IPM).
  • Ingest/emit partner events (RBS).
• Outputs: webhook deliveries, CDC cursors, bulk job manifests.

12) Usage telemetry & operator cost visibility

• Objective: track usage/cost internally (operator-only).
• Headless flow:
  • Emit usage records from services (Accounting).
  • Run daily rollups and export summaries (Accounting).
• Outputs: usage rollups + export batches.

13) Offboarding (export → freeze → purge)

• Objective: safely remove org data.
• Headless flow:
  • Request export, verify manifest (UTL).
  • Freeze org writes, then purge (UTL + per-service hooks).
• Outputs: export manifest + purge verification.

14) Platform commerce (UCP)

• Objective: enable external platforms (AI agents, apps, marketplaces) to transact with the merchant via the Universal Commerce Protocol.
• Headless flow:
  • Register platform credentials (UCP) — admin issues client_id + client_secret.
  • Set capability config: checkout, order (webhooks), identity (UCP).
  • Platform creates checkout sessions, updates cart, completes to SCM order (UCP → SCM).
  • Configure webhook event subscriptions + callback URL; test delivery (UCP).
  • For identity linking: admin issues auth code for a CRM customer, platform exchanges for OAuth tokens (UCP → CRM).
• Outputs: platform credentials, checkout→order flow, signed webhook delivery, identity links with scoped tokens.

---

Operations & use-case catalog (expanded by service)

UAS — User Account Service

Objectives

• Identity onboarding, email verification, passcode policy, payment methods. References: UAS

Inputs & ingestion

• Inputs: user email, passcode (or passcode set flow), optional payment metadata, optional account references.
• How to get them in: create user → verify email → set passcode via UAS flow; add/update payment methods after verification.
• Validation gates: email uniqueness; passcode policy + reuse windows; payment token uniqueness/format.

Operations (business actions)

• Create user and issue verification token.
• Verify email / resend verification.
• Set/reset passcodes and enforce reuse policy.
• Manage payment methods (add/remove/set priority).
• Read-only stat endpoint for health validation.

Use cases (exploded)

• UC-UAS-001: Owner onboarding with verification and passcode set.
• UC-UAS-002: Verification token expiry + resend flow.
• UC-UAS-003: Passcode reset + reuse-block enforcement.
• UC-UAS-004: Payment method add, primary switch, and removal.
• UC-UAS-005: Stat call with valid credentials returns health.

OpenAPI paths

• /stat

USM — User Session Management

Objectives

• Sessions, service accounts, and API key governance. References: USM

Inputs & ingestion

• Inputs: user identity (from UAS), passcode, orgcode binding for service accounts, role grants.
• How to get them in: session create with validated user/passcode; API key create for org-bound service accounts; key validate used by downstream services.
• Validation gates: session revocation/expiry; API key org binding; role gates enforced on validate.

Operations (business actions)

• Create/validate/close sessions; list sessions; logout all devices.
• Create/list/revoke API keys; org-wide revoke.
• Create/list/status service accounts; validate API keys.

Use cases (exploded)

• UC-USM-001: Create session; validate; close; list sessions.
• UC-USM-002: Logout everywhere; validate failure afterward.
• UC-USM-003: API key create → validate → revoke.
• UC-USM-004: Revoke all org keys; ensure fail‑closed.
• UC-USM-005: Service account create + status change.

OpenAPI paths

• /session/create
• /session/validate
• /session/close
• /session/get
• /session/list
• /session/logout_other_devices
• /session/logout_everywhere
• /service_account/create
• /service_account/list
• /service_account/status
• /api_key/create
• /api_key/list
• /api_key/revoke
• /api_key/revoke_all
• /api_key/revoke_all_org
• /api_key/policy_set
• /api_key/validate

OFM — Org & Facility Management

Objectives

• Org lifecycle, governance, facility spine, membership, sales channels. References: OFM

Inputs & ingestion

• Inputs: orgcode + legal name, owner user_guid, facility codes/timezone, channel codes/markets/locales, cost-centre codes, member assignments.
• How to get them in: create org → set status; create physical/legal/logical facilities; assign members/roles; create sales channels and upload config; set cost centres.
• Validation gates: org status gates writes; code format/length; member role constraints; facility/logical assignment validity.

Operations (business actions)

• Org create/get/list/update/status.
• Owners & members: invite/accept/revoke, role assignments, state changes.
• Facilities: physical/legal/logical create/get/list/update/status.
• Zones and teams; member↔logical assignments.
• Cost centres; sales channel config (presign/complete).
• Resolver surfaces (orgcode/facility/zone/cost-centre/channel).

Use cases (exploded)

• UC-OFM-001: Org create → activate → suspend → restore.
• UC-OFM-002: Invite + accept member; assign logical; revoke invite.
• UC-OFM-003: Create physical/legal/logical facilities + zones.
• UC-OFM-004: Create sales channel + upload config + resolve.
• UC-OFM-005: Cost-centre create/update/status set.
• UC-OFM-006: Owner primary/secondary changes (operator-only).

OpenAPI paths

• /org/create
• /org/get
• /org/list
• /org/update
• /org/status/set
• /cost-centre/create
• /cost-centre/get
• /cost-centre/list
• /cost-centre/update
• /cost-centre/status/set
• /facility/physical/create
• /facility/physical/get
• /facility/physical/list
• /facility/physical/update
• /facility/physical/status
• /facility/legal/create
• /facility/legal/get
• /facility/legal/list
• /facility/legal/update
• /facility/legal/status
• /facility/logical/create
• /facility/logical/get
• /facility/logical/list
• /facility/logical/update
• /facility/logical/status
• /zone/create
• /zone/get
• /zone/list
• /zone/status
• /owner/list
• /owner/primary/set
• /owner/secondary/add
• /owner/secondary/remove
• /owner/state/set
• /member/invite/create
• /member/invite/accept
• /member/invite/list
• /member/invite/revoke
• /member/state/set
• /member/assign-logical
• /member/detach-logical
• /service-account/assign-logical
• /service-account/detach-logical
• /service-account/assignments
• /member/list
• /member/assignments
• /member/resolve
• /team/create
• /team/get
• /team/list
• /team/update
• /team/status
• /team/member/add
• /team/member/remove
• /team/members
• /team/by-member
• /resolve/orgcode
• /resolve/facility
• /resolve/zone
• /resolve/cost-centre
• /sales-channel/create
• /sales-channel/get
• /sales-channel/list
• /sales-channel/update
• /sales-channel/status
• /sales-channel/config/presign
• /sales-channel/config/complete
• /sales-channel/resolve

MRS — Metarecord Service

Objectives

• Opaque payload storage with metadata + tags + lifecycle. References: MRS

Inputs & ingestion

• Inputs: payload (inline JSON or file), content metadata (content_type, size), tags, optional TTL/doom intent.
• How to get them in: create record inline or presign upload → complete; then tag/TTL/doom as needed.
• Validation gates: payload size caps; MD5 checks; gzip requirement for presigned uploads.

Operations (business actions)

• Create inline record or presign + complete.
• Get/head/list records; tag add/remove.
• Doom/TTL set; metadata retrieval.

Use cases (exploded)

• UC-MRS-001: Inline JSON record create + meta read.
• UC-MRS-002: Presign upload → complete → download.
• UC-MRS-003: Tag add/remove + list filtered by tags.
• UC-MRS-004: Doom or TTL set and verify access behavior.

OpenAPI paths

• /record
• /record/complete
• /record/meta
• /list
• /tag/add
• /tag/remove
• /doom
• /ttl/set
• /head

PVM — Product & Vendor Management

Objectives

• Product truth, vendor metadata, taxonomy, identifiers, comments. References: PVM

Inputs & ingestion

• Inputs: vendors/manufacturers, brands, taxonomy hierarchy, OGM definitions, style/variant metadata, identifiers/aliases/barcodes, compliance/lifecycle fields, comment attachments.
• How to get them in: create suppliers + taxonomy → create OGM/option groups → create styles/variants → add identifiers/barcodes/aliases → attach comments/files.
• Validation gates: style requires primaries + valid category; brand links must cover suppliers; identifiers/barcodes unique among non‑doomed; status transitions enforced.

Operations (business actions)

• Vendors/manufacturers CRUD + status.
• Brands CRUD + supplier links + primary set.
• Taxonomy CRUD + status (division/department/category/season).
• OGM/style/variant lifecycle + status + recreate.
• Identifiers/aliases/barcodes add/list/resolve/transfer.
• Comments + attachments; reports; history.
• Kits, alternatives, supplementary links.

Use cases (exploded)

• UC-PVM-001: Create vendor/manufacturer + activate.
• UC-PVM-002: Brand link to suppliers + set primary.
• UC-PVM-003: Create taxonomy (division/department/category) and enforce acyclic rules.
• UC-PVM-004: Create OGM → style → variants with identifiers.
• UC-PVM-005: Resolve by code/barcode/alias and transfer identifier.
• UC-PVM-006: Comment with attachment + retention cleanup behavior.
• UC-PVM-007: Variant recreate to new OGM revision.
• UC-PVM-008: Manage kits/alternatives/supplementary links.

OpenAPI paths

• /division
• /division/get
• /division/update
• /division/status
• /department
• /department/get
• /department/update
• /department/status
• /category
• /category/get
• /category/update
• /category/status
• /season
• /season/get
• /season/update
• /season/status
• /vendor
• /vendor/get
• /vendor/update
• /vendor/status
• /manufacturer
• /manufacturer/get
• /manufacturer/update
• /manufacturer/status
• /brand
• /brand/get
• /brand/update
• /brand/status
• /brand/link/add
• /brand/link/remove
• /brand/link/set_primary
• /brand/link/list
• /option_group
• /option_group/get
• /option_group/update
• /option_group/status
• /option
• /option/get
• /option/update
• /option/status
• /style
• /style/get
• /style/update
• /style/status
• /variant
• /variant/list
• /variant/get
• /variant/update
• /variant/status
• /identifier/add
• /identifier/transfer
• /identifier/history
• /identifier/resolve
• /identifier/list
• /barcode/set_primary
• /barcode/add
• /barcode/status
• /barcode/resolve
• /alias/set
• /alias/remove
• /alias/list
• /comment
• /comment/list
• /comment/status
• /comment/report
• /history/status
• /kit/component/add
• /kit/component/remove
• /kit/component/list
• /alternative/add
• /alternative/status
• /alternative/list
• /supplementary/add
• /supplementary/status
• /supplementary/list
• /resolve/barcode
• /resolve/code
• /resolve/alias
• /ogm
• /ogm/clone
• /ogm/get
• /ogm/list
• /ogm/status
• /style/ogm/set
• /variant/stale/list
• /variant/recreate
• /barcode/list
• /barcode/get

PMC — Product Merchandising Control

Objectives

• Channel/logical sellability snapshots with revision control. References: PMC

Inputs & ingestion

• Inputs: publishability profile, channel/logical context, selector criteria, PVM snapshot availability.
• How to get them in: define publish profile → start publish run → create revisions → set online pointer.
• Validation gates: publish requires eligible variants; pointer set must reference existing revision; only one online revision at a time.

Operations (business actions)

• Publish runs, revision packs, pointer/online switching.
• Query products and revisions; search/group.
• Manage publish profiles and manifests.

Use cases (exploded)

• UC-PMC-001: Publish run for a single variant with reason.
• UC-PMC-002: Publish by brand or category selector.
• UC-PMC-003: Switch online revision (rollback/forward).
• UC-PMC-004: Query online/offline lists and grouped facets.
• UC-PMC-005: Manage publishability profiles.

OpenAPI paths

• /build/stats
• /product/get
• /product/list
• /product/search
• /product/group
• /product/revision/list
• /product/online/set
• /product/online/clear
• /product/pointer/get
• /product/pointer/set
• /product/pointer/clear
• /pack/create
• /pack/complete
• /pack/get
• /pack/list
• /publish-profile/get
• /publish-profile/set
• /publish/run/start
• /publish/run/get
• /publish/run/step
• /publish/run/cancel
• /publish/run/manifest/list
• /publish/run/manifest/presign

PPM — Pricing & Promotions

Objectives

• Price truth, approval gates, promotions, policy. References: PPM

Inputs & ingestion

• Inputs: price lists/zones, currency + UOMs, approval policy, promo definitions, channel/facility assignments.
• How to get them in: create price list/zone → assign → set prices → submit approvals → create promos.
• Validation gates: currency/UOM coherence; approval rules enforced; promo overlap/stacking rules.

Operations (business actions)

• Set/resolve prices and price lists/zones; assignments.
• Submit/approve/reject price changes.
• Create and end promotions; manage dynamic rules.

Use cases (exploded)

• UC-PPM-001: Base price set → resolve by channel.
• UC-PPM-002: Submit price approval and approve/reject.
• UC-PPM-003: Promotion create + end; overlapping rules.
• UC-PPM-004: Price zone overrides + assignments.

OpenAPI paths

• /price/resolve
• /price/set
• /price/get
• /price/list
• /price/approval/submit
• /price/approval/approve
• /price/approval/reject
• /price-list/set
• /price-list/get
• /price-list/list
• /price-list/status/set
• /price-list/assign
• /price-list/assign/clear
• /price-list/resolve
• /price-list/assignments
• /price-zone/set
• /price-zone/get
• /price-zone/list
• /price-zone/status/set
• /price-zone/assign
• /price-zone/assign/clear
• /price-zone/resolve
• /price-zone/assignments
• /dynamic-rule/set
• /dynamic-rule/get
• /dynamic-rule/list
• /dynamic-rule/status/set
• /policy/get
• /policy/set
• /promotion/create
• /promotion/get
• /promotion/list
• /promotion/end
• /uom/set
• /uom/get
• /uom/list
• /comment
• /comment/get
• /comment/list
• /comment/revise
• /comment/status
• /comment/report
• /inbox/create
• /inbox/get
• /inbox/list
• /inbox/status
• /inbox/state

ICS — Inventory Control

Objectives

• Stock ledger, movement, reservations, transfers, counts. References: ICS

Inputs & ingestion

• Inputs: facility/logical context, bins/zones, receipts/shipments, adjustment reasons, count plans.
• How to get them in: record receipts/putaway/picks; create transfers; submit counts/adjustments; integrate from procurement/sales flows.
• Validation gates: facility scoping; stock cannot go negative unless policy allows; transfer approvals enforced.

Operations (business actions)

• Stock get/list/transition; bins/zones.
• Receive, putaway, pick, pack, ship, QC.
• Reservations/allocations/commits; transfer requests + shipments.
• Cycle counts, adjustments, consignment flows.

Use cases (exploded)

• UC-ICS-001: Receive inventory → putaway → stock list.
• UC-ICS-002: Reserve + allocate + commit for order.
• UC-ICS-003: Transfer request → shipment → receive.
• UC-ICS-004: Cycle count submit/approve/reject with adjustments.
• UC-ICS-005: Consignment receive/consume/settle.

OpenAPI paths

• /stock/get
• /stock/list
• /stock/transition
• /bin/create
• /bin/get
• /bin/list
• /bin/status/set
• /replenishment/rule/set
• /replenishment/rule/get
• /replenishment/rule/list
• /replenishment/rule/status/set
• /replenishment/record
• /replenishment/suggest
• /zone/create
• /zone/get
• /zone/list
• /zone/status/set
• /putaway/record
• /pick/record
• /pack/record
• /ship/record
• /receive/record
• /receive/get
• /receive/list
• /qc/complete
• /reservation/create
• /reservation/release
• /reservation/expire
• /allocation/create
• /allocation/release
• /allocation/expire
• /commit/create
• /commit/release
• /transfer/request/create
• /transfer/request/submit
• /transfer/request/approve
• /transfer/request/get
• /transfer/request/list
• /transfer/report
• /transfer/shipment/record
• /transfer/shipment/receive
• /transfer/shipment/get
• /transfer/shipment/list
• /transfer/suggest
• /allocation/suggest
• /count/create
• /count/plan/set
• /count/plan/get
• /count/plan/list
• /count/plan/status/set
• /count/submit
• /count/approve
• /count/reject
• /adjustment/create
• /consignment/receive
• /consignment/consume
• /consignment/settle
• /stock/card/list
• /comment
• /comment/get
• /comment/list
• /comment/revise
• /comment/status
• /comment/report
• /inbox/create
• /inbox/get
• /inbox/list
• /inbox/status
• /inbox/state
• /search/comments
• /search/inbox

SCM — Sales Cycle Management

Objectives

• Orders, promises, fulfillment, returns, tender, tax. References: SCM

Inputs & ingestion

• Inputs: order lines (variant IDs or identifiers), pricing resolution, tax policy, customer + delivery details, tender/payment data.
• How to get them in: create order/quote → promise/allocate stock → create shipments → capture tender → return/refund flows.
• Validation gates: pricing/tax policy required; inventory commitment enforced; tender status gates fulfillment.

Operations (business actions)

• Orders/quotes/backorders/special orders.
• Promise/reserve/allocate/commit/release.
• Fulfillment shipments and exceptions.
• Returns/refunds/tender capture/settle.
• Tax policy, quote, finalize; EDI record.

Use cases (exploded)

• UC-SCM-001: Order create → place → promise/allocate.
• UC-SCM-002: Fulfillment pick/pack/ship/deliver with exceptions.
• UC-SCM-003: Return + refund; tender settlement.
• UC-SCM-004: Quote → approve → convert to order.
• UC-SCM-005: Backorder + special order lifecycle.

OpenAPI paths

• /order/create
• /order/place
• /order/cancel
• /order/line/cancel
• /order/promise/reserve
• /order/promise/allocate
• /order/promise/commit
• /order/promise/release
• /order/promise/quote
• /order/get
• /order/list
• /order/search
• /channel/policy/get
• /channel/policy/set
• /tax/policy/get
• /tax/policy/list
• /tax/policy/set
• /tax/quote
• /tax/finalize
• /routing/policy/get
• /routing/policy/list
• /routing/policy/set
• /routing/plan/create
• /routing/plan/get
• /routing/plan/list
• /fulfillment/shipment/create
• /fulfillment/shipment/get
• /fulfillment/shipment/list
• /fulfillment/shipment/pick
• /fulfillment/shipment/pack
• /fulfillment/shipment/ship
• /fulfillment/shipment/deliver
• /fulfillment/shipment/pickup/ready
• /fulfillment/shipment/pickup/complete
• /fulfillment/shipment/pickup/no_show
• /fulfillment/shipment/exception
• /fulfillment/shipment/exception/short-pick
• /fulfillment/shipment/exception/damaged
• /fulfillment/shipment/exception/carrier-failure
• /fulfillment/shipment/exception/partial
• /fulfillment/shipment/exception/resolve
• /fulfillment/shipment/cancel
• /fulfillment/shipment/substitution/apply
• /quote/create
• /quote/approve
• /quote/convert
• /quote/get
• /quote/list
• /backorder/create
• /backorder/approve
• /backorder/fulfill
• /backorder/cancel
• /backorder/get
• /backorder/list
• /special-order/create
• /special-order/approve
• /special-order/submit
• /special-order/cancel
• /special-order/get
• /special-order/list
• /return/request
• /return/receive
• /return/get
• /return/list
• /refund/issue
• /tender/capture
• /tender/void
• /tender/settle
• /tender/get
• /tender/list
• /comment
• /comment/get
• /comment/list
• /comment/revise
• /comment/status
• /comment/report
• /inbox/create
• /inbox/get
• /inbox/list
• /inbox/status
• /inbox/state
• /edi/record
• /edi/status/set
• /edi/get
• /edi/list

PCM — Procurement Cycle Management

Objectives

• NPI, worksheets, POs, receiving, invoices, RTV. References: PCM

Inputs & ingestion

• Inputs: vendor terms, NPI metadata, worksheet lines, PO lines, invoices, RTV reasons.
• How to get them in: create NPI/worksheet → create/approve PO → record receipts → invoice match → dispute/resolve.
• Validation gates: approval thresholds; invoice/receipt matching rules; RTV windows.

Operations (business actions)

• NPI create/submit/approve.
• Worksheets create/submit.
• POs create/approve/issue and list.
• Receipts, vendor performance, invoices + disputes.
• Consignment settle, RTV, credit apply.

Use cases (exploded)

• UC-PCM-001: NPI create → submit → approve.
• UC-PCM-002: PO create → approve → issue → receive.
• UC-PCM-003: Invoice match → dispute → resolve.
• UC-PCM-004: RTV create → receive; credit apply.

OpenAPI paths

• /npi/create
• /npi/submit
• /npi/approve
• /npi/get
• /npi/list
• /worksheet/create
• /worksheet/submit
• /worksheet/get
• /worksheet/list
• /po/create
• /po/approve
• /po/issue
• /po/get
• /po/list
• /receipt/record
• /receipt/get
• /receipt/list
• /vendor/performance/list
• /invoice/match
• /invoice/get
• /invoice/list
• /invoice/dispute
• /invoice/resolve
• /consignment/settle
• /consignment/get
• /consignment/list
• /rtv/create
• /rtv/receive
• /rtv/get
• /rtv/list
• /credit/apply
• /comment
• /comment/get
• /comment/list
• /comment/revise
• /comment/status
• /comment/report
• /inbox/create
• /inbox/get
• /inbox/list
• /inbox/state
• /inbox/status

CRM & Loyalty

Objectives

• Customer truth, consent, loyalty/gift card ledgers, fraud flags. References: CRM

Inputs & ingestion

• Inputs: customer identifiers (email/phone), consent flags, loyalty policy, gift card data, fraud flags.
• How to get them in: create customer → capture consent → earn/redeem loyalty → issue/redeem gift cards → manage holds/flags.
• Validation gates: consent required for certain exports; loyalty policy versioning; fraud/hold gates on redemptions.

Operations (business actions)

• Customer create/get/list/search; dedupe/merge.
• Consent set/get; fraud assessments.
• Loyalty earn/redeem/adjust/expire.
• Giftcard issue/redeem.

Use cases (exploded)

• UC-CRM-001: Customer create + consent capture.
• UC-CRM-002: Dedupe + merge customer records.
• UC-CRM-003: Loyalty earn → redeem → reverse.
• UC-CRM-004: Giftcard issue + redeem.
• UC-CRM-005: Fraud assess + hold resolution.

OpenAPI paths

• /customer/create
• /customer/get
• /customer/list
• /account/create
• /account/get
• /account/list
• /account/status/set
• /account/update
• /account/contact/create
• /account/contact/get
• /account/contact/list
• /account/contact/status/set
• /account/contact/update
• /customer/search
• /customer/dedupe/list
• /customer/consent/set
• /customer/consent/get
• /exemption/certificate/create
• /exemption/certificate/get
• /exemption/certificate/list
• /exemption/certificate/status/set
• /customer/merge
• /customer/merge/list
• /customer/flag/set
• /customer/flag/list
• /customer/fraud/assess
• /customer/fraud/list
• /customer/hold/list
• /customer/hold/resolve
• /loyalty/earn
• /loyalty/redeem
• /loyalty/adjust
• /loyalty/reverse
• /loyalty/restore
• /loyalty/expire
• /loyalty/policy/get
• /loyalty/policy/set
• /giftcard/issue
• /giftcard/redeem
• /comment
• /comment/get
• /comment/list
• /comment/revise
• /comment/status
• /comment/report
• /inbox/create
• /inbox/get
• /inbox/list
• /inbox/status
• /inbox/state

Influencer / Affiliate

Objectives

• Attribution, earnings, payout, and statement workflows. References: Influencer

Inputs & ingestion

• Inputs: influencer profiles, campaign rules, attribution events, payout preferences.
• How to get them in: create profile/campaign → record attribution → compute earnings → hold/release/clawback → submit payouts.
• Validation gates: campaign status; payout readiness; clawback rules on returns.

Operations (business actions)

• Profile + campaign creation.
• Attribution records; earnings list/hold/release/clawback.
• Payout submit and readiness; statements.

Use cases (exploded)

• UC-INF-001: Profile create + campaign launch.
• UC-INF-002: Attribution record + earnings list.
• UC-INF-003: Hold/release/clawback earnings; payout submit.

OpenAPI paths

• /profile/create
• /profile/get
• /campaign/create
• /campaign/get
• /campaign/list
• /campaign/status/set
• /discount-tier/set
• /discount-tier/get
• /discount-tier/list
• /attribution/record
• /earnings/list
• /earnings/hold
• /earnings/release
• /earnings/clawback
• /payout/submit
• /payout/ready/set
• /payout/ready/get
• /statement/create
• /statement/get
• /statement/list
• /comment
• /comment/get
• /comment/list
• /comment/revise
• /comment/status
• /comment/report
• /inbox/create
• /inbox/get
• /inbox/list
• /inbox/status
• /inbox/state

Accounting (operator-only)

Objectives

• Usage telemetry, rollups, export pipelines, lineage. References: Accounting

Inputs & ingestion

• Inputs: per‑request usage events, storage usage events, org/cost‑centre codes, export schedule configs.
• How to get them in: services emit usage events → accounting rollups run daily → exports created/scheduled.
• Validation gates: org attribution required; cost‑centre optional but validated; export status transitions enforced.

Operations (business actions)

• Record/list/get events and lineage.
• Record storage usage and reconcile usage.
• Usage rollup get/list.
• Export creation and schedules; batch repair.
• Comment/inbox workflows for audits.

Use cases (exploded)

• UC-ACC-001: Record usage events and run rollup.
• UC-ACC-002: Export batch create + repair; status set.
• UC-ACC-003: Record storage usage and reconcile.

OpenAPI paths

• /event/list
• /event/record
• /event/get
• /lineage/list
• /reconcile/report
• /storage/usage/record
• /storage/usage/get
• /storage/usage/list
• /storage/usage/reconcile
• /usage/rollup/get
• /usage/rollup/list
• /export/create
• /export/get
• /export/list
• /export/batch/create
• /export/batch/repair
• /export/batch/get
• /export/batch/list
• /export/batch/status/set
• /export/schedule/create
• /export/schedule/get
• /export/schedule/list
• /export/schedule/status/set
• /comment
• /comment/get
• /comment/list
• /comment/revise
• /comment/status
• /comment/report
• /inbox/create
• /inbox/get
• /inbox/list
• /inbox/status
• /inbox/state

IPM — Integration Plane Management

Objectives

• Webhooks, CDC, bulk import/export, KPI signals. References: IPM

Inputs & ingestion

• Inputs: webhook endpoints + secret, CDC cursor params, bulk import/export manifests, KPI records/alerts.
• How to get them in: create webhooks → replay as needed; create bulk job → upload/continue → commit; record KPIs.
• Validation gates: endpoint verification; replay window limits; bulk job continuation tokens.

Operations (business actions)

• Webhook create/list/status/replay.
• CDC list; bulk job create/continue/commit.
• KPI record/query/alert.

Use cases (exploded)

• UC-IPM-001: Create webhook + replay; verify delivery logs.
• UC-IPM-002: CDC list with cursor continuation.
• UC-IPM-003: Bulk export/import with continuation.
• UC-IPM-004: KPI record + alert configuration.

OpenAPI paths

• /stat
• /event/catalog/list
• /export/contract/list
• /kpi/query
• /kpi/record
• /kpi/alert
• /lifecycle/list
• /specimen/get
• /pagination/get
• /webhook/create
• /webhook/get
• /webhook/list
• /webhook/status/set
• /webhook/replay
• /cdc/list
• /bulk/import/create
• /bulk/import/continue
• /bulk/import/commit
• /bulk/export/create
• /bulk/export/continue
• /bulk/job/get
• /bulk/job/list

RBS — Retail Bus Service

Objectives

• Partner event subscriptions and delivery. References: RBS

Inputs & ingestion

• Inputs: subscription endpoint, verification token/secret, event filters.
• How to get them in: register subscription → verify → test delivery → update/status set.
• Validation gates: verification required before delivery; endpoint reachability; status gates.

Operations (business actions)

• Subscription register/verify/update/status/test.

Use cases (exploded)

• UC-RBS-001: Register subscription → verify → test delivery.
• UC-RBS-002: Update subscription + status set.

OpenAPI paths

• /stat
• /subscription/register
• /subscription/verify
• /subscription/update
• /subscription/status/set
• /subscription/unregister
• /subscription/test
• /subscription/get
• /subscription/list

UTL — Utility (offboarding/export)

Objectives

• Export/freeze/purge workflows. References: UTL

Inputs & ingestion

• Inputs: orgcode, request context, export scope, purge reason, legal‑hold policy flags.
• How to get them in: request export → verify manifest → request offboarding → freeze → purge → verify.
• Validation gates: org status; legal‑hold blocks purge; export completion required before purge.

Operations (business actions)

• Offboarding request/cancel/status.
• Export request/status/download.

Use cases (exploded)

• UC-UTL-001: Offboarding request → status progression → purge verification.
• UC-UTL-002: Export request → download manifest.

OpenAPI paths

• /stat
• /offboarding/request
• /offboarding/cancel
• /offboarding/status
• /export/request
• /export/status
• /export/download/start

UCP — Universal Commerce Protocol Adapter

Objectives

• Platform onboarding, checkout sessions, signed order webhooks, OAuth 2.0 identity linking. References: UCP

Inputs & ingestion

• Inputs: platform caption/scopes, capability config (checkout/order/identity), checkout line items + buyer, webhook callback URL + event types, authorization code request (platform_guid + customer_guid), PKCE code_challenge.
• How to get them in: admin registers platform → sets capabilities → platform creates checkouts; admin configures webhooks → tests delivery; admin authorizes identity link → platform exchanges code for tokens.
• Validation gates: platform must be active; checkout session FSM enforced; webhook HMAC-SHA256 signed; auth codes single-use with 10min TTL; PKCE S256 verified; bearer tokens SHA-256 hashed for DDB lookup.

Operations (business actions)

• Platform register/get/list/rotate/revoke.
• Config set/get (capabilities: checkout, order, identity).
• Capability profile discovery (GET /.well-known/ucp).
• Checkout create/get/update/complete/cancel.
• Webhook config set/get/test; delivery + retry + auto-pause.
• OAuth discovery (GET /identity/.well-known/oauth-authorization-server).
• Identity authorize (admin → auth code); token exchange (platform → access + refresh); userinfo (bearer → CRM customer data).
• Token revoke (RFC 7009); link list/revoke (admin).

Use cases (exploded)

• UC-UCP-001: Platform register → rotate secret → revoke.
• UC-UCP-002: Config set (checkout+order+identity) → profile reflects enabled capabilities.
• UC-UCP-003: Checkout create → update → complete → SCM order created.
• UC-UCP-004: Checkout cancel from any non-terminal state.
• UC-UCP-005: Webhook config set → test delivery → verify signed payload.
• UC-UCP-006: Webhook retry with exponential backoff; auto-pause after 10 failures; re-enable.
• UC-UCP-007: Identity authorize → token exchange → userinfo returns CRM customer.
• UC-UCP-008: PKCE S256 challenge/verifier validation.
• UC-UCP-009: Token refresh (new access, old invalidated) + revoke (RFC 7009).
• UC-UCP-010: Admin link list + link revoke (status → revoked).

Webhook event types (20)

Category	Events
Order	order.created, order.placed, order.fulfilled, order.cancelled, order.closed, order.line_cancelled
Fulfillment	fulfillment.shipment_created, fulfillment.shipment_updated, fulfillment.shipment_cancelled, fulfillment.delivered
Return	return.requested, return.authorized, return.received, return.inspected, return.resolved
Adjustment	adjustment.refund
Promise	promise.quoted, promise.reserved, promise.allocated, promise.committed

Identity scopes

Scope	Grants
ucp:checkout_session	Checkout session data for linked customer
ucp:order_read	Order data for linked customer
ucp:customer_read	Customer profile (email, phone, name, code)

OpenAPI paths

• /stat
• /.well-known/ucp
• /identity/.well-known/oauth-authorization-server
• /platform/register
• /platform/get
• /platform/list
• /platform/rotate
• /platform/revoke
• /config/set
• /config/get
• /checkout/create
• /checkout/get
• /checkout/update
• /checkout/complete
• /checkout/cancel
• /webhook/config/set
• /webhook/config/get
• /webhook/test
• /identity/authorize
• /identity/token
• /identity/revoke
• /identity/userinfo
• /identity/link/list
• /identity/link/revoke

Cross-cutting: Comments, Inbox, and Search

Objectives

• Standardized comment and inbox workflows across services.

Inputs & ingestion

• Inputs: comment text, optional attachments, inbox item metadata, status/state transitions, redaction flags.
• How to get them in: create comment/inbox items via service surfaces; revise/status change via standard comment/inbox endpoints; search where enabled.
• Validation gates: attachment size/type; redaction rules; inbox state machine enforcement.

Operations (business actions)

• Comment add/get/list/revise/status/report.
• Inbox create/get/list/status/state transitions.
• Comments/inbox search plane (where implemented).

Use cases (exploded)

• UC-CIE-001: Add comment with attachment → revise/status change.
• UC-CIE-002: Create inbox item → status/state transitions.
• UC-CIE-003: Search comments/inbox with redaction rules.

---

MCP guidance (LLM training intent)

This catalog is meant to be machine‑readable and LLM‑friendly. When using MCP, the recommended approach is:

• Read this page for stack‑wide SOPs and the full operations/use‑case inventory.
• Use per‑service PROTOCOL.md for exact request/response shapes and constraints.
• Use /story/super-usecases.html for scenario‑based flows and QA status.