Real-time API Connection for Returns

This page defines the retailer-facing returns API contract: a GET order endpoint plus POST lifecycle endpoints to register/update, cancel, and close returns, all linked by one stable UUID return ID ac

Real-time API Connection for Returns

Returns Portal Retailer API Contract

This document is written for retailers integrating a returns experience.

• In step 1, you provide a GET endpoint that parcelLab fetches from.

• In steps 2–4, you provide POST endpoints that parcelLab calls with return lifecycle updates.

1. Fetch Order Data

parcelLab requests order data from your system so return eligibility, return-window logic, and line-item selection can be evaluated. The rules for this live in parcelLab, you provide the order data.

Endpoint you provide

• Method: GET

• Example path: /orders/{order_reference}

Required request input parcelLab sends to your GET endpoint

Field	Type	Description
order_reference	string	Shopper-facing order number

Recommended response fields your GET endpoint should return

Field	Type	Why it matters
order_reference	string*	Lookup correlation
order_id	string	Stable retailer order id for downstream updates
order_date	datetime*	Return-window fallback
order_shipping_date	datetime	Return-window fallback
order_delivery_date	datetime	Primary return-window date
currency	string*	Monetary calculations
order_total_amount	number*	Financial context
order_shipping_amount	number	Shipping refund/fee logic
order_tax_amount	number	Tax-aware calculations
customer_email	string*	Identity and communication
customer_phone	string	Optional secondary identity/contact
customer_address	object*	Postal verification and return context
fulfillments	array	Shipment-level status/tracking context
line_items	array*	Returnable item data
tags	array[string]	Optional policy segmentation
additional_properties	object	Optional custom metadata

Recommended fields inside each line item

Field	Type	Why it matters
line_item_id	string*	Stable item id across all lifecycle events
order_line_id	string	Original order-line reference (if different)
sku	string*	Product matching and targeting
product_id	string	Product-level grouping
variant_id	string	Variant-level matching
item_name	string*	Shopper display
item_category	string	Policy targeting
item_image_url	string*	Shopper display
ordered_quantity	integer*	Max returnable quantity
already_returned_quantity	integer	No longer returnable quantity
unit_price	number*	Refund estimate
line_tax_amount	number	Tax-aware estimate
tags	array[string]	Optional item-level segmentation
additional_properties	object	Optional item-level metadata

Sample GET response payload

{
  "order_reference": "100123",
  "order_id": "ord_9f2ab1",
  "order_date": "2026-01-12T10:15:00Z",
  "order_shipping_date": "2026-01-13T14:05:00Z",
  "order_delivery_date": "2026-01-15T18:40:00Z",
  "currency": "USD",
  "order_total_amount": 149.97,
  "order_shipping_amount": 8.99,
  "order_tax_amount": 12.35,
  "customer_email": "[email protected]",
  "customer_phone": "[phone]",
  "customer_address": {
    "first_name": "Alex",
    "last_name": "Miller",
    "address_line": "101 Main St",
    "city": "Austin",
    "postal_code": "78701",
    "country_iso3": "USA"
  },
  "fulfillments": [
    {
      "fulfillment_id": "ful_4471",
      "status": "delivered",
      "carrier_code": "dhl",
      "tracking_number": "JD014600006838000000",
      "shipped_date": "2026-01-13",
      "delivered_date": "2026-01-15"
    }
  ],
  "line_items": [
    {
      "line_item_id": "li_001",
      "order_line_id": "ol_001",
      "sku": "HD-001-BLK-M",
      "product_id": "prd_hoodie_001",
      "variant_id": "var_blk_m",
      "item_name": "Everyday Hoodie",
      "item_category": "apparel",
      "item_image_url": "https://cdn.example.com/images/hoodie-black-m.jpg",
      "ordered_quantity": 2,
      "already_returned_quantity": 0,
      "unit_price": 59.99,
      "line_tax_amount": 4.8,
      "tags": ["full-price"],
      "additional_properties": {
        "warehouse": "US-EAST"
      }
    }
  ],
  "tags": ["vip", "online-store"],
  "additional_properties": {
    "sales_channel": "web",
    "loyalty_tier": "gold"
  }
}

2. Register or Update RMA (incl. ASN)

parcelLab sends return submission or update payloads so your system can create or update the retailer return request. This does include tracking data for your warehouse ASN.

Endpoint you provide

• Method: POST

• Example path: /rma/register_or_update

Required payload sections parcelLab sends to your POST endpoint

Section	Required fields
Identity	order_reference, order_id, rma_reference, return_registration_id
Timing & method	submitted_at, refund_method
Return lines	line_item_id, return_quantity, return_reason_code, reason_note, compensation_type
Return labels	labels[] with carrier_code, tracking_number, is_free_label, label_cost_amount
Shipping fees	refund_shipping_fees, shipping_fee_deduction
Refund estimate	base_amount, tax_amount, label_cost, net_amount, final_amount, currency
Metadata	tags, additional_properties, idempotency_key (same UUID as return_registration_id)

Sample register/update POST payload

{
  "order_reference": "100123",
  "order_id": "ord_9f2ab1",
  "rma_reference": "RMA-000042",
  "return_registration_id": "2a8f2c5c-9e54-46de-9ec3-8f9347f7d2b1",
  "submitted_at": "2026-02-24T11:00:00Z",
  "refund_method": "original_payment",
  "refund_shipping_fees": false,
  "line_items": [
    {
      "line_item_id": "li_001",
      "return_quantity": 1,
      "return_reason_code": "size_too_small",
      "reason_note": "Sleeves are too short",
      "compensation_type": "refund"
    }
  ],
  "labels": [
    {
      "carrier_code": "dhl",
      "tracking_number": "JD014600006838000000",
      "is_free_label": false,
      "label_cost_amount": 4.99
    }
  ],
  "shipping_fee_deduction": {
    "mode": "label_cost",
    "amount": 4.99,
    "currency": "USD"
  },
  "refund_estimate": {
    "currency": "USD",
    "base_amount": 59.99,
    "tax_amount": 4.8,
    "label_cost": 4.99,
    "net_amount": 55.0,
    "final_amount": 55.0
  },
  "idempotency_key": "2a8f2c5c-9e54-46de-9ec3-8f9347f7d2b1",
  "tags": ["self-service"],
  "additional_properties": {
    "source": "returns_portal"
  }
}

3. Cancel RMA

parcelLab sends cancellation updates when a return is cancelled. This is only possible for returns that are not yet closed.

Endpoint you provide

• Method: POST

• Example path: /rma/cancel

Required payload fields parcelLab sends to your cancel POST endpoint

Field	Required	Description
rma_reference	yes	Return to cancel
order_reference	yes	Shopper-facing order number
order_id	yes	Retailer order id
return_registration_id	yes	UUID lifecycle id from register/update
cancel_reason_code	yes	Structured cancellation reason
cancel_reason	yes	Human-readable reason
cancelled_at	yes	Cancellation timestamp
idempotency_key	yes	Same UUID as return_registration_id
tags	no	Optional segmentation
additional_properties	no	Optional metadata

Sample cancel POST payload

{
  "rma_reference": "RMA-000042",
  "order_reference": "100123",
  "order_id": "ord_9f2ab1",
  "return_registration_id": "2a8f2c5c-9e54-46de-9ec3-8f9347f7d2b1",
  "cancel_reason_code": "rma_expired",
  "cancel_reason": "Return window expired before drop-off",
  "cancelled_at": "2026-02-24T11:15:00Z",
  "idempotency_key": "2a8f2c5c-9e54-46de-9ec3-8f9347f7d2b1",
  "tags": ["cancelled", "expired"],
  "additional_properties": {
    "source": "expiry_job"
  }
}

4. Close Return

parcelLab sends finalization updates when a return should be closed, i.e. the refund should be settled and any exchanges released.

This step is optional if your WMS can issue refunds within your system.

Endpoint you provide

• Method: POST

• Example path: /rma/close

Required payload fields parcelLab sends to your close POST endpoint

Field	Required	Description
rma_reference	yes	Return to close
order_reference	yes	Shopper-facing order number
order_id	yes	Retailer order id
return_registration_id	yes	Same UUID lifecycle id from register/update
trigger_refund	yes	Finalization refund decision
release_exchange_items	yes	Exchange release/finalization decision
refund_shipping_fees	yes	Shipping refund decision
status_reason	yes	Closing reason
idempotency_key	yes	Same UUID as return_registration_id
tags	no	Optional segmentation
additional_properties	no	Optional metadata

Sample close POST payload and response

{
  "rma_reference": "RMA-000042",
  "order_reference": "100123",
  "order_id": "ord_9f2ab1",
  "return_registration_id": "2a8f2c5c-9e54-46de-9ec3-8f9347f7d2b1",
  "trigger_refund": true,
  "release_exchange_items": true,
  "refund_shipping_fees": false,
  "status_reason": "warehouse_received",
  "idempotency_key": "2a8f2c5c-9e54-46de-9ec3-8f9347f7d2b1",
  "tags": ["closed", "auto-close"],
  "additional_properties": {
    "close_source": "tracking_event"
  }
}