G3N Retail Stack Story

Appearance

Pricing & Promotions (PPM) ​

Status: Implemented (draft surfaces; ongoing refinement).

Purpose ​

PPM owns temporal pricing, promotions, discount governance, and price resolution inputs across facilities and channels.

Goals ​

  • Provide near-instant price resolution for checkout and quotes.
  • Preserve price history and the effective price snapshot used for each sale.
  • Support as-of price queries by facility and channel for at least 24 months.
  • Support enterprise-grade discounting, coupons, and guardrails.
  • Support unit-of-measure conversions across buy and sell units.
  • Provide price and promotion analytics and recommendations without changing the checkout contract.

Non-goals ​

  • PPM does not define product truth (owned by PVM).
  • PPM does not define sellability (owned by PMC).
  • PPM does not own sales orders or procurement transactions.

Scope and gating ​

  • Pricing is org-scoped with facility and channel overrides.
  • Channel context is required for price resolution and promotion eligibility.
  • Facility context is required when overrides or policy guardrails are facility-specific.
  • Price resolution is required for sales and quotes.

Request context checklist ​

  • Org: required for all pricing operations.
  • Facility: required when override or guardrail is facility-specific.
  • Channel: required for price resolution and promotion eligibility.
  • Customer segment: required when tier/employee/influencer pricing applies.
  • Actor + role: required for approvals and overrides.
  • Cost-centre: optional attribution for billing and audit.
  • Line identifiers: variant_id preferred; sku-only resolution is supported when price entries include SKU.
  • Price lists can be filtered by variant_id or sku when auditing or troubleshooting.

Core business entities and relationships ​

  • Price zones and store clusters to support regional pricing behavior.
  • Price lists and temporal price rules with effective windows.
  • Contract price lists assigned to customer references, with optional channel and facility scope, effective windows, and priority.
  • Pricing policies are versioned and effective-dated; resolutions record the policy version in effect for audit.
  • Promotions, discounts, and coupons (printed and code-based), including BOGO, mix-and-match, bundles, and tiered offers.
  • Overrides by facility, channel, or customer segment.
  • Dynamic pricing rules (surge/markdown) with scoped applicability and explicit adjustments.
  • Customer tiers, employee pricing, and influencer pricing rules.
  • UoM conversion rules (variant defaults and facility overrides).
  • Price recommendations with rationale, inputs, and approval status.

Lifecycle and status model (described in words) ​

  • Price rules become active when their effective window starts and expire when it ends.
  • Overrides can be scheduled or immediate and must retain audit history.
  • Price entries can be submitted for approval, approved/rejected, and activated with audit history.
  • Promotions can be paused, ended, or superseded without breaking historical price truth.

End-to-end workflows ​

Happy paths ​

  • Create base price lists and schedule future changes.
  • Assign contract price lists to customer references (org-wide or scoped by channel/facility).
  • Assign price zones to logical facilities for regional pricing.
  • Apply promotions and discounts with stacking rules.
  • Resolve final price for a sale or quote and preserve it on the transaction.
  • Apply influencer discount codes with embedded referral earnings rules.

Exceptions and edge cases ​

  • Conflicting price rules resolved by defined precedence.
  • Discount stacking blocked by org guardrails.
  • UoM conversions when buying in bulk and selling in eaches or weight.
  • Channel-specific pricing exceptions for the same logical facility.
  • Multiple contract list matches resolved by priority and scope specificity.

Configuration and defaults ​

  • The platform is enterprise-grade by default; applications may hide complexity via defaults.
  • EDLP is represented as long-running base price entries (optionally tagged via pricing_policy_version for audit); markdowns are captured as promotions (amount/percent) and can be tagged via promotion_policy_version.
  • Discount stacking and caps are configured per org and may be facility-specific.
  • Government coupons are deferred; printed coupons and discount codes are supported.
  • Mix-and-match, bundles, tiered discounts, and BOGO promotions are supported.
  • Customer- and employee-specific pricing tiers are supported.
  • Influencer discounts can be channel-specific.
  • Dynamic and surge pricing are allowed only within org guardrails (min/max price, max change, max frequency, and eligibility by channel/product/region).
  • Dynamic pricing is applied only when an explicit dynamic rule is referenced in the price resolve request.
  • Price recommendations are suggestions until approved; approval thresholds are % and $ values set per org with optional facility overrides, and optional no-self-approval rules are policy-driven.
  • Regulated or restricted categories can be excluded from surge/dynamic pricing by policy.

Taxation and compliance (pricing basis) ​

  • Tax basis is explicit per channel: tax-included or tax-added (exclusive).
  • Tax-on-tax rules are applied only when configured by jurisdiction.
  • Luxury and excise thresholds are supported via tax category mapping.
  • DTC exemptions or tax holidays are applied only where jurisdiction rules allow.
  • Price outputs preserve the tax basis used for audit and returns.

Pricing analytics and optimization (best-practice expectations) ​

  • Price elasticity, promo lift, and markdown effectiveness by SKU, category, and channel.
  • Margin impact and GMROI by time bucket, facility, and channel.
  • Inventory age and weeks-of-supply influence on recommended price and promo timing.
  • Price ladder and price gap analysis within categories and across competitors (when available).
  • Returns and fraud signals tied to pricing and promotion strategies.
  • Recommendations include a clear "why" with inputs and expected impact.

BI and KPI expectations ​

  • Realized price vs list, discount depth, and override rate.
  • Promo lift, incremental margin, and markdown effectiveness by category.
  • Price compliance vs min/max and approval latency for overrides.
  • Dynamic/surge activations, guardrail breaches, and exception counts.
  • Coupon redemption and stacking incidence with fraud signals.

KPI readiness checklist ​

  • Price rules and promotions have effective windows and scopes.
  • Overrides and approvals capture actor, reason, and timestamps.
  • List price, net price, and discount values are recorded per sale.
  • Coupon usage is captured with code and eligibility context.
  • Price recommendations capture rationale and approval outcomes.

Rebalancing and recalibration ​

  • Recalibrate price floors, ceilings, and markdown cadence by velocity and inventory age.
  • Rebalance channel-specific overrides to protect margin and availability.
  • Adjust promo guardrails and approval thresholds (% and $) based on campaign performance.
  • Apply change caps and cool-down windows to prevent price oscillation.

Omnichannel requirements ​

  • Support channel-specific pricing overrides without breaking auditability.
  • Preserve the price and promotion context for every channel sale.

Performance requirements ​

  • Price resolution must be near-instant for checkout and quotes.
  • Historical pricing must be fast for at least 24 months and queryable for audits and returns.
  • Analytics and recommendations may be asynchronous but must publish near-real-time outputs for operational use.
  • Approval checks must not slow price resolution or overrides.

Operational resilience checklist ​

  • Operations are idempotent and retry-safe; duplicate submissions do not double-apply.
  • Event emission is non-blocking; operational actions do not wait on analytics pipelines.
  • Out-of-order events are tolerated; reconciliation uses timestamps and rule references.
  • Exceptions generate actionable inbox items and can be retried or reversed with audit trails.
  • Long-running workflows are resumable with explicit state checkpoints.

Training and change management ​

  • Policy and workflow changes include training notes and operational checklists.
  • Critical changes use staged rollout with rollback guidance to reduce operational risk.
  • Support runbooks cover common override disputes, promo failures, and guardrail breaches.

Downstream accounting and integration capture ​

  • Pricing events capture org, facility, channel, SKU, effective price, discounts, tax basis, timestamps, and rule references.
  • Sales transactions store the effective price snapshot for audit and dispute resolution.
  • Events include optional cost-centre attribution for billing and audit.

Comments and inbox ​

  • Price rules and promotions support comments, threads, and attachments with revision history.
  • Price changes can generate inbox notifications for approvals or alerts.
  • Endpoints: POST /ppm/comment|comment/get|comment/list|comment/revise|comment/status|comment/report and POST /ppm/inbox/create|get|list|status|state.

Governance and roles ​

  • Org roles for price governance (ppm_* roles).
  • Price overrides require explicit permissions and policy guardrails.
  • Cost visibility is restricted to cost_view or finance_audit for cost-based pricing use cases.
  • Role grants can be permanent, time-bounded, or scheduled.

Relationships and data flow ​

  • PVM supplies product identity and UoM context.
  • PMC provides sellability constraints; PPM provides price resolution.
  • SCM consumes PPM for quotes and orders.
  • Influencer/Affiliate uses PPM discount rules for attribution.

Example scenarios and acceptance criteria ​

Scenario 1: Scheduled price change ​

  • A base price is scheduled to change next month.
  • Orders before the change use the old price; orders after use the new price.
  • Acceptance: historical orders retain the correct price snapshot.

Scenario 2: Employee pricing with coupon ​

  • An employee attempts to stack an employee discount with a printed coupon.
  • Org policy disallows stacking; only one discount applies.
  • Acceptance: stacking rules enforce policy and are auditable.

Scenario 3: Weight-based conversion ​

  • A product is procured in bulk but sold by weight.
  • Facility-specific conversion rules apply.
  • Acceptance: pricing is accurate and traceable across units.

Scenario 4: Dynamic price recommendation with approval ​

  • A slow-moving item ages past the threshold.
  • PPM recommends a markdown based on inventory age, sales velocity, and margin guardrails.
  • The recommendation is approved and applied within policy limits.
  • Acceptance: the approved price is applied; the rationale and approver are auditable.

Scenario 5: Surge pricing with guardrails ​

  • A high-demand item triggers surge pricing rules for a channel.
  • Policy caps the surge and excludes regulated categories.
  • Approval is required before activation.
  • The checkout flow references the active dynamic rule when resolving price.
  • Acceptance: surge pricing stays within caps, excluded categories are untouched, the rule reference is captured, and the audit trail is complete.

Scenario 6: Below-cost exception with approval ​

  • A promotion would drop a price below the allowed cost threshold.
  • Policy requires approval and records the exception with a reason and policy version.
  • Acceptance: the approved price is applied with a cost-based flag; downstream sales retain the approved price snapshot.