RFC: Enhanced Return Schema — RMA, Warranty, and EDI Alignment

[GrayWandererr]

Title

RFC: Enhanced Return Schema — RMA, Warranty, and EDI Alignment for v1.1

Body

Context

The current Return entity schema (schemas/return.json) is solid for basic ecommerce returns — it covers inspection, disposition, exchange line items, return labels, restocking fees, and refund tracking.

However, as enterprise fulfillment vendors (Manhattan Associates, GEODIS, Radial) adopt onX, the return schema needs to account for concepts that are standard in warehouse management and EDI workflows but missing from the current spec.

Proposed Additions

1. RMA Number (distinct from Return Number)

The current returnNumber field is a customer-facing identifier. In enterprise fulfillment, the RMA (Return Merchandise Authorization) is a separate concept — it's the authorization to return, not the tracking identifier.

{
  "rmaNumber": "RMA-2026-04521",
  "rmaStatus": "authorized",
  "rmaAuthorizedAt": "2026-03-15T10:00:00Z",
  "rmaAuthorizedBy": "system",
  "rmaExpiresAt": "2026-04-15T10:00:00Z"
}

Why this matters: In EDI 180 (Return Merchandise Authorization), the RMA is the key document. Vendors receiving returns validate the RMA before processing. Without it, a return that "just shows up at the dock" is handled differently from an authorized return.

2. Return Type Classification

The current outcome field captures what the customer receives (refund/exchange). But there's no returnType for why the return is happening:

{
  "returnType": "rma | warranty | recall | defective | doa | buyer_remorse | wrong_item | damaged_in_transit"
}

Why this matters: Different return types route differently in a WMS. A warranty claim goes to the warranty desk. A recall goes to quarantine. A DOA goes to the vendor. The routing logic depends on the return type, not just the outcome.

3. Warranty Tracking

For products with warranties (electronics, appliances, furniture):

{
  "warranty": {
    "claimNumber": "WC-2026-00123",
    "warrantyProvider": "manufacturer",
    "warrantyPeriodEnd": "2027-03-15",
    "warrantyType": "limited | extended | lifetime"
  }
}

4. Structured Disposition Codes

The current inspection.dispositionOutcome is a free string. Enterprise WMS systems use structured codes:

{
  "dispositionCode": "restock | refurbish | scrap | donate | liquidate | return_to_vendor | quarantine"
}

Why this matters: Disposition drives inventory accounting. "Restock" adds back to available inventory. "Scrap" writes it off. "Return to vendor" creates an outbound shipment. Free-text strings can't drive these workflows.

5. EDI Document References

For vendors that exchange EDI documents:

{
  "ediReferences": {
    "rmaRequestDoc": "EDI-180-2026-001",
    "returnAsnDoc": "EDI-856-2026-042",
    "creditMemoDoc": "EDI-812-2026-015"
  }
}

What I'm NOT Proposing

• These fields should all be optional. A 3-person Shopify vendor should not need to implement RMA tracking to be onX conformant.
• The existing required fields (orderId, outcome, returnLineItems) remain unchanged.
• This is additive, not breaking.

Questions for the TSC

1. Which of these additions are v1.1 priority vs. v2?
2. Should disposition codes be an enum (fixed list) or a string with recommended values?
3. Do any vendors on the TSC have EDI reference patterns they'd want to share?
4. Should warranty tracking be a sub-object of the return, or its own entity?
5. Who should own the detailed spec? (Proposed: Ninaad + Manhattan representative)

Impact

• Conformance: New fields are optional — existing conformant implementations remain conformant.
• Schemas: Additions to ReturnSchema in Zod, regenerate JSON Schema.
• Reference app: Juniper Commerce would demonstrate the enhanced fields.

Looking forward to the TSC's input.

---

Ninaad Acharya, Technical Team