POST to the shipments endpoint with addresses swapped relative to the outbound shipment (customer as 'address_from', warehouse as 'address_to') and include 'extra.is_return: true' in the shipment payload; verify the exact field path in current Shippo docs as it may be a top-level field or nested under 'extra'.
Retrieve the rates array and select the appropriate return service; note that some carriers offer dedicated return service levels (e.g., USPS Return Service) which may appear as distinct service level tokens.
POST to the transactions endpoint with the selected rate 'object_id' to purchase the return label; download from 'label_url'.
For scan-based returns (pay-on-use), verify that the carrier and service level support this billing model; scan-based returns are not universally available and typically require a pre-negotiated carrier account agreement.
Distribute the label to the customer via email or a returns portal; track the return parcel using the 'tracking_number' from the transaction response.
Known gotchas
Scan-based returns (where postage is only charged when the parcel is accepted by the carrier) require specific carrier account setup outside of Shippo; not all accounts support this and it cannot be enabled purely through the API.
Return label expiration policies vary by carrier; some carriers expire return labels after a set number of days, so generate labels close to when the customer will use them or communicate expiry clearly.
Swapping address direction is your responsibility; Shippo does not automatically infer return intent from 'is_return' alone without the address swap.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp