Calls the partner's configured returns service to create a return label.

post https://api.shipium.com/api/v1/deliveryexperience/customerreturn/label

Body Params

customerReturnParams

object

required

Details of the customer return required for label generation by the carriers.

originAddress

object

required

The address of the location where the package is being returned.

destinationAddress

object

required

The address of the location where the package is being returned.

labelParameters

object

required

Information on the types of labels to be generated by the carrier, as will as if a manifest for the shipment is generated. This field is ignored if the "generateLabel" field is set to "false".

generateLabel

boolean

Whether or not to generate a return label. This defaults to true.

packagingType

object

Fields describing the physical properties of the package.

totalWeight

object

The weight of this type of packaging empty.

orderItemQuantities

array of objects

A list of orderItems being returned.

orderItemQuantities

tenantId

string

Either the shipium tenant ID or the partner provided tenant ID. When present, this is used to indicate the tenant associated with the shipment.

Headers

X-MEGA-PROCESS-VERSION-OVERRIDE

string

Responses

Response body

object

shipiumShipmentId

string

The unique identifier for the shipment attached to this label.

carrierSelectionId

string

Unique id of the carrier selection for later lookup.

shipiumCustomerReturnLabelId

string

The unique identifier for this customer return.

status

string

Defines the result of the carrier label call. Values returned will be success, partial, and failed

success failure voided failover generated label_created manifested manifest_failure not_set carrier_selection_failure

statusDetails

string

Details explaining the result status. Pertinent when the status is "partial" or "failed".

carrier

string

The carrier that was used for the return.

carrierServiceName

string

Name of the carrier service method selected.

serviceMethodName

string

Name of the service method the label was generated for.

carrierServiceMethodId

string

Maps to the unique internal Shipium ID which represents a carrier service method definition.

carrierShipmentId

string

Carrier's identification for the return.

carrierTrackingId

string

Carrier's tracking identification for the return.

shipiumTrackingId

string

Shipium's tracking identification for the return.

packageScannableId

string

Identifier provided that matches the scannable barcode on the label

params

object

Details of the customer return required for label generation by the carriers.

partnerReturnRequestId

string

Partner provided identification for this return. Must be alphanumeric and 30 chars wide.

fulfillmentContext

string

When present, this is used to limit carrier selection to carrier accounts that contain a matching fulfillmentContext

returnRequestDateTime

date-time

ISO-8601 formatted date of the return request, if not set will use the current date time.

contentDescription

string

required

A short description (under 35 characters) of the package contents being returned that is passed on to the carrier.

customsInfo

object

Customs information about the package for international shipping.

documents

array of objects

List of links to labels generated by format for the return.

documents

object

labelExpiration

date-time

Date time when the label expires and is no longer valid.

labelFormat

string

Defines the format the shipment label was generated in by the carrier.

labelProperties

object

Metadata describing the label.

labelImage

object

Base64 encoded ZPL as generated by the carrier before label sanitation and augmentations are performed.

labelUrl

string

Url with is the link to the shipment label file on the Shipium CDN.

carrierTrackingId

string

The tracking id associated with this label.

carrierTrackingLink

string

The tracking link associated with this label.

packageReferenceIdentifier

string

The package reference id that was passed in by the customer to be associated with this package.Most frequently used for multi parcel shipments. This can be used to cross reference internation documents and carrier labels.

shipiumPackageReferenceId

string

The package reference Identifier created by shipium.

packageScannableId

string

The package scannable id associated with this label.

carrierShipmentId

string

The carrier shipment id associated with the label.

internationalDocuments

array of objects

List of international customs documents generated by the carrier for the shipment.

internationalDocuments

object

documentType

string

The type of international document. For 'multiple', there will be multiple types of forms

commercial_invoice electronic_export_information ps_2976 air_waybill multiple unknown

documentExpiration

date-time

Date time when the document expires and is no longer valid.

documentFormat

string

Defines the format the document was generated in by the carrier.

documentImage

object

Document image contents and encoding information.

electronicallySubmitted

boolean

Indication of whether or not this international document has been electronically submitted by the carrier

packageReferenceIdentifier

string

The package reference id that was passed in by the customer to be associated with a package.Most frequently used for multi parcel shipments. This can be used to cross reference internation documents and labels.

testMode

boolean

A flag denoting whether the label is a test label

Response body

object

shipiumShipmentId

string

The unique identifier for the shipment attached to this label.

carrierSelectionId

string

Unique id of the carrier selection for later lookup.

shipiumCustomerReturnLabelId

string

The unique identifier for this customer return.

status

string

Defines the result of the carrier label call. Values returned will be success, partial, and failed

success failure voided failover generated label_created manifested manifest_failure not_set carrier_selection_failure

statusDetails

string

Details explaining the result status. Pertinent when the status is "partial" or "failed".

carrier

string

The carrier that was used for the return.

carrierServiceName

string

Name of the carrier service method selected.

serviceMethodName

string

Name of the service method the label was generated for.

carrierServiceMethodId

string

Maps to the unique internal Shipium ID which represents a carrier service method definition.

carrierShipmentId

string

Carrier's identification for the return.

carrierTrackingId

string

Carrier's tracking identification for the return.

shipiumTrackingId

string

Shipium's tracking identification for the return.

packageScannableId

string

Identifier provided that matches the scannable barcode on the label

params

object

Details of the customer return required for label generation by the carriers.

partnerReturnRequestId

string

Partner provided identification for this return. Must be alphanumeric and 30 chars wide.

fulfillmentContext

string

When present, this is used to limit carrier selection to carrier accounts that contain a matching fulfillmentContext

returnRequestDateTime

date-time

ISO-8601 formatted date of the return request, if not set will use the current date time.

contentDescription

string

required

A short description (under 35 characters) of the package contents being returned that is passed on to the carrier.

customsInfo

object

Customs information about the package for international shipping.

documents

array of objects

List of links to labels generated by format for the return.

documents

object

labelExpiration

date-time

Date time when the label expires and is no longer valid.

labelFormat

string

Defines the format the shipment label was generated in by the carrier.

labelProperties

object

Metadata describing the label.

labelImage

object

Base64 encoded ZPL as generated by the carrier before label sanitation and augmentations are performed.

labelUrl

string

Url with is the link to the shipment label file on the Shipium CDN.

carrierTrackingId

string

The tracking id associated with this label.

carrierTrackingLink

string

The tracking link associated with this label.

packageReferenceIdentifier

string

shipiumPackageReferenceId

string

The package reference Identifier created by shipium.

packageScannableId

string

The package scannable id associated with this label.

carrierShipmentId

string

The carrier shipment id associated with the label.

internationalDocuments

array of objects

List of international customs documents generated by the carrier for the shipment.

internationalDocuments

object

documentType

string

The type of international document. For 'multiple', there will be multiple types of forms

commercial_invoice electronic_export_information ps_2976 air_waybill multiple unknown

documentExpiration

date-time

Date time when the document expires and is no longer valid.

documentFormat

string

Defines the format the document was generated in by the carrier.

documentImage

object

Document image contents and encoding information.

electronicallySubmitted

boolean

Indication of whether or not this international document has been electronically submitted by the carrier

packageReferenceIdentifier

string

testMode

boolean

A flag denoting whether the label is a test label

Language

Credentials

OAuth2


xxxxxxxxxx
1
curl --request POST \
2
     --url https://api.shipium.com/api/v1/deliveryexperience/customerreturn/label \
3
     --header 'accept: application/json' \
4
     --header 'content-type: application/json'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Label generated for the return.

400Invalid inputs were provided.