Payload Object Schemas

Primary Components

Return Line Item Scanned

Property	Type	Nullable	Since	Description
package_scan	Package Scan		v1	Information about the package and its sorting priority
return_detail	Return Details		v1	Information about the complete return

Return Line Item Details

Property	Type	Nullable	Since	Description
line_item	Return Line Item		v1	Information about the line item
return	Return Summary		v1	Basic information about the return

Bulk Return Event

Property	Type	Nullable	Since	Description
return_bulk_details	Bulk Return Details		v1.15	Basic Information about the the bulk return
return	Return Details		v1	Detailed information about the return

Return Details

Property	Type	Nullable	Since	Description
id	string		v1	The Two Boxes ID for the return
captured_rma	string	☑️	v1.11	The value captured in the RMA field of a work capture return in Two Boxes
comments	string	☑️	v1	Grader-entered comments during grading
completed_at	string - ISO8601 UTC date	☑️	v1	Time when this return's status was marked "complete"
customer	Customer Event Data		v1.5	Information about the customer initiating the return
grading_status	string		v1	Status of grading (ready, in progress, graded, complete)
kind	string		v1.13	The kind of return. One of the following values: "production", "test"
line_items	List \ Return Line Item		v1	The line items assigned to the return. There is one line item per returned unit
linked_line_items	List \ Return Line Item		v1.12	Line Items that are part of related returns
links	Links		v1.14	Links to Two Boxes endpoints and actions relevant to the return
merchant_integration	Merchant Integration Summary		v1.10	Merchant connections triggering this event
return_provider	string		v1	Two Boxes code for the RMA provider
return_type	string		v1.13	The type of return. One of the following values: "rma", "work-capture", "rts", "import", "unexpected-item", "bulk-capture"
rma	string		v1	RMA number provided by the RMA provider
rma_address	Address Event Data		v1.5	Origin address of the RMA
rma_return_id	string	☑️	v1	The ID in the RMA provider's system for this return
rts	bool		v1	True if return was marked RTS
store_front_provider	string		v1	Storefront that initiated the order
undeliverable_shipping_charge	float64	☑️	v1.10	Shipping charges for RTS undeliverable orders
work_capture	bool		v1	True if return was processed by 3PL without an RMA

Return Line Item Ship Back

Property	Type	Nullable	Since	Description
line_item	Return Line Item		v1	Information about the package and its sorting priority
return	Return Summary		v1	Basic information about the return
ship_back_label	Ship Back Label	☑️	v1.7	Shipping information for items dispositioned as "Ship Back to Customer"

Sub-Components

Package Scan

Property	Type	Since	Description
package_priority	int	v1	Highest priority of all units in the package
return_line_item_id	UUID	v1	ID referencing a line item inside the scanned package
return_line_item_priority	string	v1	Priority assigned to a specific unit in the package
scanned_at	Time	v1	UTC timestamp of when the package was scanned
scan_id	UUID	v1	Unique scan ID for idempotency checks
tracking_number	string	v1	Tracking number on the scanned package

Return Summary

Property	Type	Nullable	Since	Description
id	string		v1	The Two Boxes ID for the return
captured_rma	string	☑️	v1.11	The value captured in the RMA field of a work capture return in Two Boxes
merchant_integration	Merchant Integration Summary		v1.10	BEING DEPRECATED DEC 30, 2025
rma	string		v1	RMA number provided by the RMA provider
rma_return_id	string	☑️	v1	RMA provider’s return ID (nullable)

Return Line Item

Property	Type	Nullable	Since	Description
id	string		v1	The Two Boxes ID for the return line item
3pl	3PL		v1.14	The Two Boxes 3pl the line item is assigned to
barcode	string	☑️	v1.5	The barcode of the item as defined by the merchant product catalog
captured_lpn	string		v1.10	An externally generated LPN that is captured for this return line item
carrier	string	☑️	v1.5	The carrier of the shipping label used to ship the return
child_reason	string	☑️	v1.5	The sub-reason for the return indicated by the customer
comments	string	☑️	v1	Optional comment provided by the grader
consolidation_code	string	☑️	v1.5	Consolidation code if shipped via LTL palette
consolidation_provider	string	☑️	v1.5	Consolidation provider if shipped via LTL palette
disposition	string		v1	Return status: Return to Stock, Resale, Donate, Recycle, Dispose, Missing, Exception, Ship Back To Customer
expected_quantity	int		v1.15	The expected number of units of this line item. Always 1 for non bulk return line items
expiration_date	string - ISO8601 UTC date	☑️	v1.9	The captured expiration date
graded_attributes	List[Return Line Item Attribute]		v1	List of grading attributes assigned to this line item
grading_ended_at	string - ISO8601 UTC date	☑️	v1	Time when grading was completed
links	Links		v1.14	Links to Two Boxes endpoints and actions relevant to the return line item
lot_code	string	☑️	v1.9	The captured lot code
lpn	string		v1	Unique LPN for this return line item
merchant	Merchant		v1.14	The Two Boxes Merchant which the line item is assigned to
parent_reason	string	☑️	v1.5	The primary reason for return as indicated by the customer
product_variant	Product Variant Summary	☑️	v1	The matched or assigned product definition for this item
put_away_bin	string	☑️	v1	Bin assigned after grading
quantity	int		v1.12	The number of units associated to the line item.
rma_line_item_id	string		v1.5	The ID of the line item in the external RMA provider
site	Site	☑️	v1.14	The Two Boxes site the line item is assigned to
sku	string		v1	The merchant's SKU as configured in the storefront provider
storefront_line_item_id	string		v1	The line item ID in the originating storefront order
storefront_order_id	string	☑️	v1	The original storefront order ID
storefront_order_name	string	☑️	v1	Name/ID for identifying the order
storefront_order_number	string	☑️	v1	The storefront's original order number
storefront_product_id	string	☑️	v1	The storefront's product ID
storefront_variant_id	string	☑️	v1	The storefront-provided unique ID for the product variant
tracking_number	string	☑️	v1.5	Tracking number of the shipping label
transform_sku	string	☑️	v1	SKU updated as a result of the grading process
transform_upc	string	☑️	v1	UPC updated as a result of the grading process
upc	string	☑️	v1.5	The UPC as defined by the merchant product catalog
work_capture	bool	☑️	v1	True if the return line item was processed by 3PL without an RMA

Address Event Data

Property	Type	Nullable	Since	Description
address_1	string		v1.5	Primary address of the customer return
address_2	string	☑️	v1.5	Secondary address of the customer return
city	string	☑️	v1.5	City of the customer return
company	string	☑️	v1.5	Company associated with the return
country_code	string	☑️	v1.5	Country code of the customer return
phone_number	string	☑️	v1.5	Customer phone number
province_code	string	☑️	v1.5	Province of the customer return
zip	string		v1.5	ZIP/postal code of the customer return

Customer Event Data

Property	Type	Nullable	Since	Description
email	string		v1.5	Customer's email address
first_name	string	☑️	v1.5	Customer's first name
full_name	string	☑️	v1.12	Customer's full name (only populated for work capture returns)
last_name	string	☑️	v1.5	Customer's last name
tags	List<string>	☑️	v1.5	Tags for the customer

Merchant Integration Summary

Property	Type	Since	Description
id	string	v1	Unique Two Boxes ID for the merchant integration
name	string	v1	Human-readable merchant name
merchant	Merchant	v1.10	Merchant details
site	Site	v1.10	Site details

Product Variant Summary

Property	Type	Nullable	Since	Description
id	string		v1	The Two Boxes ID for the product variant
name	string	☑️	v1	Product name in the merchant catalog
sku	string	☑️	v1	Product SKU in the merchant catalog
barcode	string	☑️	v1.5	Product barcode in the merchant catalog

Return Line Item Attribute

Property	Type	Nullable	Since	Description
id	string		v1	The Two Boxes ID for the return line item attribute assigned during the grading lifecycle
merchant_grading_attribute	Merchant Grading Attribute		v1	Defines the inspection point / graded attribute assigned to this item
vas_successful	boolean	☑️	v1	Null if VAS was not attempted on this item. Otherwise, the outcome of the VAS required for this item and grading attribute
photo_urls	list of signed photo URLs	☑️	v1.9	Signed photo URLs of all return line item attributes.<br

Merchant Grading Attribute

Property	Type	Nullable	Since	Description
id	string		v1	The Two Boxes ID for merchant-specific grading
grading_attribute	Grading Attribute		v1	The specific type of inspection point
mga_type	string		v1	Inspection or preassigned grading type
vas_definition	VAS Definition	☑️	v1.12	The Value Added Service applied to the line item

Grading Attribute

Property	Type	Nullable	Since	Description
id	string		v1	The Two Boxes ID for the inspection point
title	string		v1	Name of the inspection point (e.g., "Worn Soles")

VAS Definition

Property	Type	Since	Description
id	string	v1.12	The Two Boxes ID for the VAS
instructions	string	v1.12	The instructions for the VAS
title	string	v1.12	The title of the VAS

Merchant

Property	Type	Nullable	Since	Description
id	string		v1.10	The Two Boxes ID for merchant
name	string		v1.10	Merchant name

Site

Property	Type	Nullable	Since	Description
id	string		v1.10	The Two Boxes ID for the site
name	string		v1.10	Site name

3PL

Property	Type	Nullable	Since	Description
id	string		v1.14	The Two Boxes ID for the 3PL
name	string		v1.14	3PL name

Shipback Label

Property	Type	Since	Description
carrier	string	v1.7	Shipping carrier for the unit
ship_from_address	Address Event Data	v1.7	Address listed as "from" on the shipping label
ship_to_address	Address Event Data	v1.7	Address listed as "to" on the shipping label
tracking_number	string	v1.7	Tracking number associated with the shipping label

Links

Property	Type	Nullable	Since	Description
action	string	☑️	v1.14	API actions that can be taken on the entity
portal	string	☑️	v1.14	url to view the entity in the Two Boxes Portal
self	string	☑️	v1.14	url to the entity in the Two Boxes API

Package Scan Not Found

Property	Type	Since	Description
scanned_at	Time	v1.13	UTC timestamp of when the package was scanned
site_id	UUID	v1.13	The Two Boxes ID for the site
tracking_number	string	v1.13	Tracking number on the scanned package

Bulk Return Details

Property	Type	Nullable	Since	Description
external_po	string	☑️	v1.15	External Po captured for the bulk return
external_ro	string	☑️	v1.15	External Ro captured for the bulk return
order_number	string	☑️	v1.15	Order Number captured for the bulk return
retailer	string	☑️	v1.15	Retailer captured for the bulk return
return_reason	string	☑️	v1.15	Return Reason captured for the bulk return
rma	string	☑️	v1.15	RMA captured for the bulk return
sender	string	☑️	v1.15	Sender captured for the bulk return