Shipping options
There are two ways to select the carrier method:
shipping_option_code - preferred approach. get the codes from the shipping options endpoint by setting the returns functionality to true. Pass it in the ship_with object with type set to "shipping_option_code".
If you have multiple contracts for the same carrier you need to specify which contract id to use.
shipping_product_code - legacy method from v2. Requires the shipping product code plus a functionalities object to filter which variant of that product you want. Only use this if you’re migrating existing v2 code.
International returns
Crossing borders may mean customs. You need parcel_items with hs_code and origin_country for each item when shipping through customs. Customs won’t clear it without proper classification.
The customs_invoice_nr field must reference the original outbound invoice number. If you generate a new invoice number for the return, customs treats it as a fresh import and the customer gets hit with duties again so try to always match the outbound invoice exactly.
customs_information object needs the same invoice number plus export_reason set to "returned_goods" and the return_data section with outbound tracking number, shipment date, carrier name, and return postal code. This proves it’s actually a return of previously imported goods.
