Return Shipping Labels
ShipEngine allows you to generate and print return labels to include in your shipments to customers. This allows your customers to send back items for exchange or refund without having to deal with printing shipping labels.
API Endpoints
Return labels can be created via the following endpoints.
/v1/labels
with theis_return_label
property set totrue
/v1/labels/:label_id/return
, automatically generates a return label with the same carrier and carrier service as the outbound label.
Label Charges
When creating a request to create a return label, you will need to specify a charge_event
to indicate when you should be
charged for the return label.
You may be charged on_creation
(at the time the label is created), on_carrier_acceptance
(when the label is scanned
by the carrier), or use the carrier_default
to use the carrier's default charge behavior.
The on_carrier_acceptance
option is useful for overriding the carrier's default behavior, but you must have the carrier
enable this on your account before sending this option in your request. If you send a request with charge_event: on_carrier_acceptance
and the carrier has not enabled this feature on your account, you will get an error.
Request Properties
Property | Type | Description |
---|---|---|
is_return_label | boolean | Indicates if the label should be created as a return label. |
rma_number | string | An optional "Return Merchandise Authorization" code, which can be used to link the return label to your system. |
outbound_label_id | string | The label_id of the original (outgoing) label that this return label is for. This associates the two labels together, which is required by some carriers. |
charge_event | enumerated string | Determines when you are charged for the label.carrier_default : Use the carrier's default charge behavior.on_creation : You are charged for the label when it is created. This is the default behavior for Stamps.com (USPS).on_carrier_acceptance : You are not charged for the label until it is actually used (a.k.a. "scan-based labels"). This is the default behavior for most carriers. |
Examples
POST /v1/labels/
Since this is a return label, the ship_from
address should be your customer's address and the ship_to
address should be your warehouse or return center.
POST /v1/labels/:label_id/return
This endpoint provides a convenient way to create a return label without having to specify all the same shipment and package information over again. It just uses all the same values as the original label, but reverses the ship_from
and ship_to
addresses.