Changelog

2025-04

Update	Before	After
Added new fields to Return model	-	exceptions exchange.charge_by outcomes return_items.[*].removed_quantity shipments.[*].created_at shipments.[*].tracking_status_updated_at shipping_status
Support more query parameters for GET /returns	-	approval_status created_at_min limit order_name outcome page return_method customer_email
The response structure of the GET /returns API has changed.	Refer to Migration guide for more details	Refer to Migration guide for more details
Added a new webhook event	-	Add return.receiving.created

2025-01

Update	Before	After
Add new fields to approve return request payload	-	customize_label_info.label_reference customize_label_info.ship_from customize_label_info.ship_to
Remove fields in approve return request payload	custom_label_reference	-
Add new fields to Address primitive	-	contact_name company_name phone email
Add new endpoints to create return	-	POST /returns
Add new webhook event	-	Add return.exchange.order.created
Return field modified	order.country	order.country_region
Add some fields to Return	-	exchange.items[*].product_title exchange.items[*].variant_title organization.id shipments[*].label.qr_code_url

2024-10

Update	Before	After
Add new endpoints to approve return	-	POST /returns/rma/{rma_number}/approve POST /returns/returns/{return_id}/approve
Add new endpoints to resolve return	-	POST /returns/rma/{rma_number}/resolve POST /returns/returns/{return_id}/resolve
Add new endpoints to reject return	-	POST /returns/rma/{rma_number}/reject POST /returns/returns/{return_id}/reject
Add new endpoints to attach return shipment	-	POST /returns/rma/{rma_number}/attach-shipments POST /returns/returns/{return_id}/attach-shipments
Add new endpoints to receive items	-	POST /returns/rma/{rma_number}/receive-items POST /returns/returns/{return_id}/receive-items
Add new endpoints to update items	-	PATCH /returns/rma/{rma_number}/items/{item_id} PATCH /returns/returns/{return_id}/items/{item_id}
Add a new endpoint to get item tags	-	GET /item-tags
Add some fields to the Return Object	Refer to Return Object 2024-07 for more details.	Refer to Return Object 2024-07 for more details.
Rename all source_*_id to external_*_id	restock.items[*].source_order_item_id restock.items[*].location.source_id return_items[*].exchange_variant.source_product_id return_items[*].exchange_variant.source_variant_id	restock.items[*].external_order_item_id restock.items[*].location.external_id return_items[*].exchange_variant.external_product_id return_items[*].exchange_variant.external_variant_id
Return item field modified	return_items[*].discounted_price_including_tax return_items[*].image_urls	return_items[*].unit_discounted_price_including_tax return_items[*].product_image_urls
Address.country_region modified	{"country_region": {"name": "USA"}}	{"country_region": {"code": "USA"}}
Address.state modified	{"state": "Arkansas"}	{"state": {"name": "Arkansas"}}
Add some webhook events	-	Add: return.approved return.expired return.rejected return.resolved return.submitted return.dropoff.created return.dropoff.shipment.updated return.dropoff.updated return.shipment.provided return.shipment.recorded return.shipment.updated return.shipments.provided
Webhook payload modified	-	Refer to Migrate to 2024-07 for more details.

2024-07

Update	Before	After
Add new endpoint to get returns by rma number	-	Get /returns/rma/{rma_number}
Add new endpoint to get return by rma id	-	Get /returns/{rma_id}
Add new endpoint to get returns	-	GET /returns
Add new endpoint to create dropoff drops.	-	POST /returns/rma/{rma_number}/dropoffs/{dropoff_id}/drops
Add new webhook event return.restock.created	-	return.restock.created