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.

GET Customer Return Shipments

Query Parameters

Parameter	Type	Required	Default	Description
status	string	No	pending	Filter by status: `pending`, `open`, `done`
ids	string	No	-	Comma-separated list of shipment IDs (limit 250)
numbers	string	No	-	Comma-separated list of shipment numbers (limit 250)
planned_date_min	date	No	-	Filter shipments with planned date >= this date (YYYY-MM-DD)
planned_date_max	date	No	-	Filter shipments with planned date <= this date (YYYY-MM-DD)
updated_at_min	datetime	No	-	Filter shipments updated >= this timestamp (ISO 8601)
updated_at_max	datetime	No	-	Filter shipments updated <= this timestamp (ISO 8601)
page	integer	No	1	Page number for pagination (starts at 1)

Status Values

pending (default): Returns shipments in draft state that have not been acknowledged by 3PL
state='draft' AND acknowledged_by_3pl_at=None
open: Returns shipments in draft state that have been acknowledged by 3PL
state='draft' AND acknowledged_by_3pl_at IS NOT None
done: Returns completed shipments
state IN ('received', 'done')

Response Structure

Top-Level Fields

Field	Type	Description
id	integer	Unique identifier for the customer return shipment
number	string	Customer return shipment number (e.g., "CRS-00001")
warehouse	object	Warehouse where the return will be received
planned_date	string\|null	Planned date for the return (ISO 8601: YYYY-MM-DD)
customer	object	Customer returning the items
origin_address	object\|null	Address where return ships FROM (customer's address)
delivery_address	object\|null	Address where return ships TO (warehouse return address)
create_date	string	When the shipment was created (ISO 8601 datetime)
write_date	string\|null	When the shipment was last updated (ISO 8601 datetime)
carrier_code	string\|null	Carrier cost method (e.g., "ups", "fedex", "usps")
service_code	string\|null	Carrier service code (e.g., "ground", "express")
tracking_number	object\|null	Tracking information for the return shipment
lines	array	Array of line items being returned
shipping_instructions	string\|null	Special shipping instructions for the return
channels	array	Array of sales channels (unique list)
related_orders	array	Array of related sales orders for this return
request_confirmation	boolean	Whether delivery confirmation is requested

`warehouse`

Warehouse where the returned items are expected to arrive.

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

`customer`

Customer who initiated the return.

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

Address Object

Both origin_address and delivery_address follow this structure:

Field	Type	Description
name	string\|null	Contact name
address1	string\|null	Primary street address
address2	string\|null	Secondary street address (apartment, suite, etc.)
business_name	string\|null	Business/company name
city	string\|null	City name
zip	string\|null	Postal/ZIP code
country_code	string\|null	ISO 3166-1 alpha-2 country code (e.g., "US", "CA")
subdivision_code	string\|null	State/province code (e.g., "CA" for California)
phone	string\|null	Phone number
email	string\|null	Email address
edi_location_number	string\|null	EDI location qualifier/number
dock	string\|null	Dock or door number for delivery
code	string\|null	Address code/identifier

{
  "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
}

Tracking Number Object

Field	Type	Description
carrier_identifier	string\|null	Internal carrier identifier (e.g., "ups", "fedex", "usps")
tracking_number	string	The tracking number assigned by the carrier
delivery_date	string\|null	Actual delivery date (ISO 8601 date format) if delivered
tracking_url	string\|null	URL to track the shipment on the carrier's website
state	string	Tracking state (e.g., "in_transit", "delivered", "unknown", "exception", "out_for_delivery", "available_for_pickup", "pending_cancellation")
scac	string\|null	Standard Carrier Alpha Code (e.g., "UPSS", "FDEG", "USPS")
bill_of_lading	string\|null	Bill of lading number
load_number	string\|null	Load/shipment reference number

{
  "carrier_identifier": "ups",
  "tracking_number": "1Z9999999999999999",
  "delivery_date": "2025-11-25",
  "tracking_url": "https://www.ups.com/track?tracknum=1Z9999999999999999",
  "state": "delivered",
  "scac": "UPSS",
  "bill_of_lading": null,
  "load_number": null
}

Line Item Object

Field	Type	Description
id	integer	Stock move ID
product	object	Product being returned
product.id	integer	Product ID
product.name	string	Product name
product.code	string	Product SKU/code
product.upc	string\|null	Universal Product Code (barcode)
product.hs_code	string\|null	Harmonized System code for customs
quantity	float	Quantity being returned
unit	string	Unit of measure symbol (e.g., "ea", "lb", "kg")
order	object\|undefined	Original sales order info (only if return originated from sale)
order.id	integer	Sales order ID
order.number	string	Sales order number
order.sale_date	string	Date the order was placed (ISO 8601 date)
order.reference	string\|null	Order reference/PO number
order.channel	object	Sales channel information
order.channel.id	integer	Channel ID
order.channel.code	string	Channel code
order.channel.name	string	Channel name
order.channel_segment	string\|null	Channel segment identifier
unit_price	float	Unit price from original order (only if from sale)
unit_customs_value	float	Unit customs value from original order (only if from sale)
currency	string	Currency code (e.g., "USD", "EUR") (only if from sale)

{
  "id": 54321,
  "product": {
    "id": 789,
    "name": "Blue Widget",
    "code": "WIDGET-BLUE-001",
    "upc": "012345678901",
    "hs_code": "9503.00"
  },
  "quantity": 2.0,
  "unit": "ea",
  "order": {
    "id": 9876,
    "number": "SO-00123",
    "sale_date": "2025-11-10",
    "reference": "PO-ABC-123",
    "channel": {
      "id": 3,
      "code": "SHOPIFY",
      "name": "Shopify Store"
    },
    "channel_segment": "B2C"
  },
  "unit_price": 29.99,
  "unit_customs_value": 25.00,
  "currency": "USD"
}

Channel Object

Field	Type	Description
id	integer	Sales channel ID
code	string	Sales channel code
name	string	Sales channel name

{
  "id": 3,
  "code": "SHOPIFY",
  "name": "Shopify Store"
}

Related Order Object

Field	Type	Description
id	integer	Sales order ID
number	string	Sales order number
reference	string\|null	Order reference/PO number
edi_attributes	object\|null	EDI-related attributes for the order
shipping_start_date	string\|null	Requested shipping window start date (ISO 8601 date)
shipping_end_date	string\|null	Requested shipping window end date (ISO 8601 date)

{
  "id": 9876,
  "number": "SO-00123",
  "reference": "PO-ABC-123",
  "edi_attributes": {
    "edi_po_number": "PO-ABC-123",
    "edi_order_type": "SA"
  },
  "shipping_start_date": "2025-11-15",
  "shipping_end_date": "2025-11-18"
}

Notes

Maximum 250 records per page
Dates are in ISO 8601 format (YYYY-MM-DD)
Datetimes are in ISO 8601 format (YYYY-MM-DDTHH:MM:SS)
origin_address is the customer's address (where return ships FROM)
delivery_address is the warehouse's return address (where return ships TO)
tracking_number field only present when a tracking label has been generated
order, unit_price, unit_customs_value, and currency fields on line items only present when return originated from a sales order
channels array contains unique channel information aggregated from all line items
related_orders array includes all sales orders associated with any line in the return shipment
Product metafields may be included if configured as exposed metafields for the product.product model

Example Response

{
  "data": [
    {
      "id": 12345,
      "number": "CRS-00042",
      "warehouse": {
        "id": 5,
        "code": "WH-MAIN",
        "name": "Main Warehouse"
      },
      "planned_date": "2025-11-25",
      "customer": {
        "name": "John Doe",
        "phone": "+1-555-0123",
        "email": "[email protected]",
        "code": "CUST-001"
      },
      "origin_address": {
        "name": "John Doe",
        "address1": "123 Main St",
        "address2": "Apt 4B",
        "business_name": null,
        "city": "Los Angeles",
        "zip": "90001",
        "country_code": "US",
        "subdivision_code": "CA",
        "phone": "+1-555-0123",
        "email": "[email protected]",
        "edi_location_number": null,
        "dock": null,
        "code": null
      },
      "delivery_address": {
        "name": "Main Warehouse",
        "address1": "456 Warehouse Ave",
        "address2": null,
        "business_name": "Acme Corp",
        "city": "Commerce",
        "zip": "90040",
        "country_code": "US",
        "subdivision_code": "CA",
        "phone": "+1-555-9999",
        "email": "[email protected]",
        "edi_location_number": null,
        "dock": "DOCK-3",
        "code": null
      },
      "create_date": "2025-11-20T10:30:00",
      "write_date": "2025-11-21T14:22:15",
      "carrier_code": "ups",
      "service_code": "ground",
      "tracking_number": {
        "tracking_number": "1Z9999999999999999",
        "tracking_url": "https://www.ups.com/track?tracknum=1Z9999999999999999",
        "state": "in_transit",
        "carrier": {
          "id": 10,
          "name": "UPS",
          "code": "ups"
        },
        "carrier_service": {
          "id": 25,
          "name": "UPS Ground",
          "code": "ground"
        }
      },
      "lines": [
        {
          "id": 54321,
          "product": {
            "id": 789,
            "name": "Blue Widget",
            "code": "WIDGET-BLUE-001",
            "upc": "012345678901",
            "hs_code": "9503.00"
          },
          "quantity": 2.0,
          "unit": "ea",
          "order": {
            "id": 9876,
            "number": "SO-00123",
            "sale_date": "2025-11-10",
            "reference": "PO-ABC-123",
            "channel": {
              "id": 3,
              "code": "SHOPIFY",
              "name": "Shopify Store"
            },
            "channel_segment": "B2C"
          },
          "unit_price": 29.99,
          "unit_customs_value": 25.00,
          "currency": "USD"
        }
      ],
      "shipping_instructions": "Handle with care - fragile items",
      "channels": [
        {
          "id": 3,
          "code": "SHOPIFY",
          "name": "Shopify Store"
        }
      ],
      "related_orders": [
        {
          "id": 9876,
          "number": "SO-00123",
          "reference": "PO-ABC-123",
          "edi_attributes": {
            "edi_po_number": "PO-ABC-123",
            "edi_order_type": "SA"
          },
          "shipping_start_date": "2025-11-15",
          "shipping_end_date": "2025-11-18"
        }
      ],
      "request_confirmation": true
    }
  ],
  "has_more": false
}