Create a return

POST {{baseUrl}}/returns

The Create a return endpoint is the heart of the Return API; it allows you to create a stand-alone return, based mainly on the to and from_address, parcel weight and the ship_with object.

You can provide a list of items and item descriptions to be included in the return via the parcel_items field (optional).

The parcel_items field is mandatory if you're creating a return from outside-EU. This is because information about the parcel contents must be provided in order to generate the required customs documents.

The ship_with object

This object is formed by two properties, the chosen shipping_product_code and the requested functionalities that we use to filter the right shipping method within the product. Find all these data on the Retrieve a list of shipping products endpoint.

The contract attribute refers to the ID of a direct contract you have with the carrier. Get the IDs for your contracts from Retrieve a list of contracts.

If you have more than one active contract for a specific carrier, you must fill the contract attribute with your desired contract ID in your request.

Retrieve return shipping products

In your request, you must provide an appropriate shipping_product_code and a set of functionalities inside the ship_with object. To find a suitable product, refer to the following endpoint: Retrieve a list of shipping products.

You can filter for a return method by flagging the returns field as true, and by including the from_country and to_country fields. The more fields you specify, the more refined the results will be. This helps you find the most appropriate shipping product for your return parcel.

It's also possible to filter based on your preferred shipping functionality, e.g. age_check=18, delivery_before, etc.

Add return reasons

You can (optionally) assign a return reason to parcel_items by providing areturn_reason_id and entering a value from the key below. Assigning return reasons to items provides you with analyzable data you can use to predict return trends or identify issues with particular products.

Retrieve the shipping label for this return

Once the parcel for the created return is announced, you can download the shipping label for it.

Find the documentation on how to retrieve a label for a parcel on the Retrieve a PDF label endpoint.

The url for downloading the label is also available on the Return object (Only if the parcel is announced). To retrieve a Return, take a look at Retrieve a Return.

To learn more about all the options for retrieving labels and customs declaration documents, refer to the Labels section of the API V2 documentation.

Request Body

{"from_address"=>{"name"=>"<string>", "company_name"=>"<string>", "address_line_1"=>"<string>", "house_number"=>"<string>", "address_line_2"=>"<string>", "postal_code"=>"<string>", "city"=>"<string>", "po_box"=>"<string,null>", "state_province_code"=>"<string>", "country_code"=>"<string>", "email"=>"<email>", "phone_number"=>"<string>"}, "to_address"=>{"name"=>"<string>", "company_name"=>"<string>", "address_line_1"=>"<string>", "house_number"=>"<string>", "address_line_2"=>"<string>", "postal_code"=>"<string>", "city"=>"<string>", "po_box"=>"<string,null>", "state_province_code"=>"<string>", "country_code"=>"<string>", "email"=>"<email>", "phone_number"=>"<string>"}, "ship_with"=>{"shipping_product_code"=>"<string>", "functionalities"=>{"age_check"=>18, "b2b"=>"<boolean>", "b2c"=>"<boolean>", "boxable"=>"<boolean>", "bulky_goods"=>"<boolean>", "carrier_billing_type"=>"zonal", "cash_on_delivery"=>"<integer,null>", "dangerous_goods"=>"<boolean>", "delivery_attempts"=>"<integer,null>", "delivery_before"=>"3317", "delivery_deadline"=>"within_72h", "direct_contract_only"=>"<boolean>", "eco_delivery"=>"<boolean>", "first_mile"=>"pickup", "flex_delivery"=>"<boolean>", "form_factor"=>"mailbox", "fragile_goods"=>"<boolean>", "fresh_goods"=>"<boolean>", "harmonized_label"=>"<boolean>", "id_check"=>"<boolean>", "incoterm"=>nil, "insurance"=>"<integer,null>", "last_mile"=>"home_delivery", "manually"=>"<boolean>", "multicollo"=>"<boolean>", "neighbor_delivery"=>"<boolean>", "non_conveyable"=>"<boolean>", "personalized_delivery"=>"<boolean>", "premium"=>"<boolean>", "priority"=>"economical", "registered_delivery"=>"<boolean>", "returns"=>"<boolean>", "segment"=>"c", "service_area"=>nil, "signature"=>"<boolean>", "size"=>"xl", "sorted"=>"<boolean>", "surcharge"=>"<boolean>", "tracked"=>"<boolean>", "tyres"=>"<boolean>", "weekend_delivery"=>"weekends", "ers"=>"<boolean>", "pick_up"=>"<boolean>", "labelless"=>"<boolean>"}, "contract"=>"<integer>"}, "weight"=>{"value"=>"<number>", "unit"=>"g"}, "dimensions"=>{"length"=>"<number>", "width"=>"<number>", "height"=>"<number>", "unit"=>"in"}, "collo_count"=>1, "parcel_items"=>[{"description"=>"<string>", "quantity"=>"<integer>", "weight"=>{"value"=>"<number>", "unit"=>"kg"}, "value"=>{"value"=>"<number>", "currency"=>"EUR"}, "hs_code"=>"<string>", "origin_country"=>"<string>", "sku"=>"<string>", "product_id"=>"<string>", "return_reason_id"=>"<string,null>", "return_message"=>"<string,null>"}, {"description"=>"<string>", "quantity"=>"<integer>", "weight"=>{"value"=>"<number>", "unit"=>"oz"}, "value"=>{"value"=>"<number>", "currency"=>"GBP"}, "hs_code"=>"<string>", "origin_country"=>"<string>", "sku"=>"<string>", "product_id"=>"<string>", "return_reason_id"=>"<string,null>", "return_message"=>"<string,null>"}], "send_tracking_emails"=>false, "brand_id"=>"<integer>", "total_insured_value"=>{"value"=>"<number>", "currency"=>"EUR"}, "order_number"=>"<string>", "total_order_value"=>{"value"=>"<number>", "currency"=>"USD"}, "external_reference"=>"<string>", "customs_invoice_nr"=>"<string,null>", "delivery_option"=>"drop_off_point", "customs_information"=>nil}

HEADERS

RESPONSES

status: Created

{"return_id":"\u003cinteger\u003e","parcel_id":"\u003cinteger\u003e","multi_collo_ids":["\u003cinteger\u003e","\u003cinteger\u003e"]}