API Reference

The customer return shipment object

This document defines the structure of the Customer Return Shipment (CRS) object in Fulfil. It is used to serialize and transmit information about return shipments initiated by customers, including metadata, addresses, products being returned, and related sales orders.

📘 Attributes

id

The ID of the return shipment. Unique identifier, different from order IDs.

number

Unique identifier for the return shipment in Fulfil.

warehouse

Warehouse where the returned items are expected to arrive.

{
  "id": 12,
  "code": "NY-WH",
  "name": "New York Warehouse"
}

planned_date

The date on which the return shipment is expected to arrive at the warehouse (ISO 8601 UTC format).

customer

Customer who initiated the return.

{
  "name": "Jane Doe",
  "phone": "+1-555-0123",
  "email": "[email protected]",
  "code": "CUST-JANE"
}

origin_address

Serialized address where the return shipment is originating from (i.e., the customer's delivery address).

{
  "name": "Jane Doe",
  "address1": "123 Main Street",
  "address2": "Apt 4B",
  "business_name": "Jane's Boutique",
  "city": "New York",
  "zip": "10001",
  "country_code": "US",
  "subdivision_code": "NY",
  "phone": "+1-555-0123",
  "email": "[email protected]",
  "edi_location_number": null,
  "dock": null,
  "code": null
}

delivery_address

Serialized warehouse address where the CRS is being returned to. Defaults to warehouse.return_address or falls back to the warehouse address.

create_date

UTC timestamp (ISO 8601 format) when the CRS was created.

write_date

UTC timestamp when the CRS was last updated. Maybe null.

carrier_code

Internal shipping carrier code used for the return shipment.

service_code

Shipping service method used for the return (e.g., ground, express).

shipping_instructions

Any special shipping instructions provided for this return.

request_confirmation

An optional field that specifies whether delivery confirmation is required for the return shipment, and what type of confirmation should be requested. This is especially relevant for carriers like UPS, FedEx, USPS, Canada Post, and Australia Post.

Possible values:

ValueDescription
null / ""No confirmation requested.
service_defaultUses the default confirmation method provided by the carrier/service.
deliveryRequires delivery confirmation (UPS, USPS only).
signatureRequires basic signature confirmation.
adult_signatureRequires an adult to sign upon delivery.
direct_signatureRequires direct signature from recipient (FedEx, Australia Post only).
indirect_signatureAccepts indirect signature, such as a family member (FedEx, Australia Post).
do_not_safe_dropPrevents the carrier from leaving the package unattended (Canada Post, Australia Post only).
leave_at_doorAllows the carrier to leave the package at the door (Canada Post, Australia Post only).

📄 Related Orders

{
  "id": 5678,
  "number": "SO1234",
  "reference": "WEB-78910",
  "edi_attributes": {},
  "shipping_start_date": "2025-05-01",
  "shipping_end_date": "2025-05-05"
}

id

ID of the sales order related to the return.

number

Sales order number.

reference

Customer PO or marketplace reference (if available).

edi_attributes

Optional EDI metadata associated with the order.

shipping_start_date, shipping_end_date

Window when the original shipment was fulfilled.

📡 Channels

An array of unique sales channels associated with the return shipment lines.

{
  "id": 1,
  "code": "web",
  "name": "Webstore"
}

📦 Line Item Attributes

Each customer return shipment contains one or more lines that represent the products being returned.

{
  "id": 1234,
  "product": {
    "id": 4321,
    "code": "SKU-001",
    "name": "Wireless Mouse"
  },
  "quantity": 2,
  "unit": "u",
  "order": {
    "id": 5678,
    "number": "SO1234",
    "sale_date": "2025-05-01",
    "reference": "WEB-78910",
    "channel": {
      "id": 1,
      "code": "web",
      "name": "Webstore"
    },
    "channel_segment": "retail"
  },
  "unit_price": "25.00",
  "unit_customs_value": "20.00",
  "currency": "USD"
}

id

ID of the line item (stock move).

product

Details about the returned product:

  • id: Product ID
  • code: SKU code
  • name: Product or variant name

quantity

Quantity returned. Can be a float for volume/weight-based UOMs.

unit

Unit of measure.

order

Sales order from which the product originated:

  • id, number, sale_date
  • reference: Remote order reference
  • channel: Sales channel (id, code, name)
  • channel_segment: Channel segmentation (e.g., retail, b2b)

unit_price

Original unit price charged to the customer.

unit_customs_value

Declared customs value per unit.

currency

Currency of the original sales order.