G3N Common Contract

Appearance

Reason Codes (Outbound) ​

Status: DRAFT (2026-02-06)

This page defines the shared reason_code taxonomy for outbound events, audits, and state transitions. It is intended to be stable, machine-readable, and cross-service. Use it alongside a freeform human reason field.

Definitions ​

  • reason_code: short, stable machine code for analytics, routing, and audit workflows.
  • reason: human-readable context (optional; not stable or enumerable).

Format (canonical) ​

  • Canonical shape: CATEGORY.CODE
  • Recommended case: UPPERCASE
  • Allowed characters: A–Z, a–z, 0–9, _, ., -
  • Hard enforcement: unknown codes are rejected (invalid-input). Use the allowlist below.

Machine-readable schema ​

  • JSON Schema: /schemas/reason-code.schema.json

Categories (starter set) ​

These categories are intentionally broad. Codes should be added under the smallest appropriate category.

  • LIFECYCLE — status changes, suspends, reactivations, dooms.
  • POLICY — policy updates, overrides, exceptions, approvals.
  • PRICING — price overrides, price list changes, pricing approvals.
  • PROMOTION — promo starts/ends, bundle/BOGO rules, promo overrides.
  • INVENTORY — adjustments, counts, transfers, restock/repair.
  • RECEIVING — inbound rejections: damaged, defective, wrong item, quality, packaging.
  • FULFILLMENT — short picks, substitutions, shipments, cancellations.
  • CUSTOMER — merges, consent changes, customer holds.
  • LOYALTY — earn/redeem adjustments, expiry actions.
  • FRAUD — fraud holds, reviews, chargebacks, disputes.
  • ACCOUNTING — reconciliations, export retries, ledger adjustments.
  • COMPLIANCE — legal holds, audit holds, regulatory exceptions.
  • TAX — policy overrides, exemptions, audit corrections.
  • SYSTEM — automated system actions (scheduled sweeps, auto-offline).

Examples ​

  • FULFILLMENT.SHORT_PICK
  • FRAUD.SUSPICIOUS_ACTIVITY
  • INVENTORY.ADJUST
  • SYSTEM.AUTO_OFFLINE
  • LIFECYCLE.ONBOARD_VERIFY

Allowlist (v0) ​

Codes are hard-enforced; use only these values.

  • LIFECYCLE
    • LIFECYCLE.ONBOARD_VERIFY
  • FULFILLMENT
    • FULFILLMENT.SHORT_PICK
    • FULFILLMENT.OUT_OF_STOCK
    • FULFILLMENT.CUSTOMER_REQUEST
    • FULFILLMENT.CUSTOMER_RETURN
    • FULFILLMENT.PARTIAL
    • FULFILLMENT.NO_STOCK
    • FULFILLMENT.SHORT
  • FRAUD
    • FRAUD.ACCOUNT_TAKEOVER
    • FRAUD.CHARGEBACK
    • FRAUD.CONFIRMED
    • FRAUD.MANUAL_REVIEW
    • FRAUD.MISMATCH
    • FRAUD.NEW_ACCOUNT
    • FRAUD.RISK_SIGNAL
    • FRAUD.STOLEN_CARD
    • FRAUD.SUSPICIOUS_ACTIVITY
    • FRAUD.VELOCITY
  • RECEIVING
    • RECEIVING.DAMAGED
    • RECEIVING.DEFECTIVE
    • RECEIVING.EXPIRED
    • RECEIVING.PACKAGING
    • RECEIVING.QUALITY_ISSUE
    • RECEIVING.SHORT_SHIPMENT
    • RECEIVING.WRONG_ITEM
    • RECEIVING.OTHER
  • INVENTORY
    • INVENTORY.ADJUST
    • INVENTORY.ADJUST_FIFO
    • INVENTORY.ADJUST_FEFO
    • INVENTORY.DAMAGE
    • INVENTORY.PUTAWAY
    • INVENTORY.RECALL
    • INVENTORY.SHRINK
    • INVENTORY.TRANSFER_SHIPPED
    • INVENTORY.TRANSFER_RECEIVED
  • SYSTEM
    • SYSTEM.AUTO_OFFLINE
    • SYSTEM.CONTRACT_TEST
    • SYSTEM.MANUAL_OFFLINE
    • SYSTEM.MANUAL_ROLLBACK
    • SYSTEM.REPLENISHMENT_AUTO
    • SYSTEM.USECASE
    • SYSTEM.USECASE_SEED
    • SYSTEM.UNSPECIFIED

Governance Rules ​

  • Additive only: add new codes; do not repurpose existing codes.
  • Stable categories: keep category list small; prefer adding codes to existing categories.
  • Deprecations: mark codes as deprecated in the internal taxonomy; do not remove from history.
  • Hard enforcement: services reject invalid format and unknown codes.

Rollout Guidance ​

  • Start with high-impact services (SCM, CRM, PPM, Accounting, ICS).
  • Use codes in outbound events first; enforcement is active.
  • Keep internal canonical list in internal-docs/reason-code-taxonomy.md.