Skip to main content

​
Data Model Overview

The Handled Returns API is built around a hierarchical data model that mirrors real-world return operations:

Return → Return Line Items → Return Packages → Return Package Line Items

​
Core Entities

​
Returns

The top-level entity representing a customer’s return request. A return contains:
  • Customer information
  • Return reason
  • RMA status
  • Total value
  • One or more Return Line Items
  • One or more Return Packages (once shipped)

​
Return Line Items

Individual products within a return request. Each return line item represents:
  • A specific product (SKU)
  • Quantity being returned
  • Reason for return
  • Original order reference
  • Exchange items (if applicable)
Return Line Items are particularly useful during the RMA (Return Merchandise Authorization) phase before the customer has actually shipped anything back.

​
Return Packages

Physical packages containing returned items. A return can have multiple packages because:
  • Customer ships items separately
  • Items come from different locations
  • Large returns require multiple boxes
Each package contains:
  • Tracking information
  • Carrier details
  • Weight and dimensions
  • Estimated/actual arrival dates
  • One or more Return Package Line Items

​
Return Package Line Items

The actual items within a physical package. Each package line item:
  • Links to a specific Return Line Item
  • Tracks quantity received
  • Records condition/defects
  • Notes from warehouse inspection
  • Processing status
A Return Package Line Item must always be linked to a Return Line Item. This ensures tracking from RMA request through to physical receipt.

​
Relationship Example

Returns Data Model

​
Visual Representation

┌─────────────────────────────────────────────────────────────────┐
│                          RETURN #123                              │
│  Customer: John Doe | Status: In Transit | Total: $149.99        │
└─────────────────────┬───────────────────────────────────────────┘
                      │
        ┌─────────────┴──────────────┬─────────────────────┐
        ▼                            ▼                     ▼
┌─────────────────┐        ┌─────────────────┐   ┌─────────────────┐
│ Return Line Item│        │ Return Line Item│   │ Return Package  │
│ SKU-A           │        │ SKU-B           │   │ Tracking: 1Z999 │
│ Qty: 2          │        │ Qty: 1          │   │ Status: Transit │
│ Reason: Defect  │        │ Reason: Size    │   └────────┬────────┘
└────────┬────────┘        └────────┬────────┘            │
         │                          │                      ▼
         │                          │              ┌───────────────┐
         │                          │              │ Package Line  │
         │◄─────────────────────────┼──────────────│ SKU-A Qty: 1  │
         │                          │              └───────────────┘
         │                          │
         │                          │              ┌─────────────────┐
         │                          │              │ Return Package  │
         │                          │              │ Tracking: 1Z998 │
         │                          │              │ Status: Transit │
         │                          │              └────────┬────────┘
         │                          │                       │
         │                          │              ┌────────┴────────┐
         │◄─────────────────────────┼──────────────│ Package Line    │
         │                          │              │ SKU-A Qty: 1    │
         │                          │              └─────────────────┘
         │                          │                       │
         │                          │              ┌────────┴────────┐
         │                          └──────────────│ Package Line    │
         │                                         │ SKU-B Qty: 1    │
         └─────────────────────────────────────────└─────────────────┘

​
Common Scenarios

​
Scenario 1: Simple Return

  • Customer creates return for 1 product
  • Ships in 1 package
  • Result: 1 Return → 1 Return Line Item → 1 Package → 1 Package Line Item

​
Scenario 2: Multiple Items, One Package

  • Customer returns 3 different products
  • Ships all in same box
  • Result: 1 Return → 3 Return Line Items → 1 Package → 3 Package Line Items

​
Scenario 3: Split Shipment

  • Customer returns 2 products
  • Ships from different locations in separate packages
  • Result: 1 Return → 2 Return Line Items → 2 Packages → 2 Package Line Items

​
Scenario 4: RMA Without Shipment

  • Customer initiates return
  • Waiting for approval or label
  • Result: 1 Return → X Return Line Items → 0 Packages (RMA state)

​
Key Concepts

RMA State

Returns exist in RMA state when created but before packages are shipped. Return Line Items track what will be returned.

Package Association

Return Package Line Items create the link between what was requested (Return Line Items) and what was received (Package contents).

Quantity Tracking

Return Line Item quantity may not match Package Line Item quantities if items are shipped separately or partially.

Status Flow

Returns progress from RMA → In Transit → Received → Processed, with packages and line items updating independently.