Add Shipping Label Info

POST /post-order/v2/return/{returnId}/add_shipping_label

The seller uses this call to create a return shipping label for the buyer. This call can also be used by the seller to provide more information to the buyer about the shipping label. For example, the seller may want to use this call to inform the buyer that an eBay-generated label is already available, or to inform the buyer that a shipping label has already been sent.

Input

Resource URI (production)

POST https://api.ebay.com/post-order/v2/return/{returnId}/add_shipping_label

URI parameters

Parameter	Type	Required?	Meaning
returnId	string	Required	The unique eBay-assigned ID of the return. The returnId value is required to identify the return for which a return shipping label is being created.

HTTP request headers

All requests made to eBay REST operations require you to provide the authorization HTTP header for authentication.
See HTTP request headers for details.

Authorization

This call uses standard authorization tokens. See Making a Call for details.

Payload model

The following lists all fields that could be included in the request.

{ /* ProvideLabelRequest */
"carrierEnum": token,
"carrierName": string,
"comments":
    { /* Text */
    "content": string,
    "language": string,
    "translatedFromContent": string,
    "translatedFromLanguage": string
    },
"fileId": string,
"forwardShippingLabelProvided": boolean,
"labelAction": token,
"labelSentDate":
    { /* DateTime */
    "formattedValue": string,
    "value": datetime
    },
"noLabelReason": token,
"returnLabelCost":
    { /* Amount */
    "convertedFromCurrency": string,
    "convertedFromValue": number,
    "currency": string,
    "exchangeRate": string,
    "value": number
    },
"trackingNumber": string
}

Request field descriptions

Input Container/Field	Type	Occurrence	Meaning
carrierEnum	token	Conditional	Indicates the shipping carrier used to ship the return or replacement item. ShippingCarrierEnum contains some popular shipping carriers for the US, UK, Germany, Canada, and Australia, but it is not a complete list. Buyer/sellers can call GeteBayDetails of the Trading API to get a complete list of shipping carrier enum values. When using GeteBayDetails, 'ShippingCarrierDetails' should be passed in as a DetailName value, and the values that can be passed in as a carrierEnum value are shown in the ShippingServiceDetails.ShippingCarrier fields. Applicable values: See ShippingCarrierEnum
carrierName	string	Conditional	This field is used to show the name of the shipping carrier. This field is only needed if the carrierEnum value is 'OTHER' or if it is missing.
comments	Text	Optional	This optional container can be used to write any applicable comments about the shipping label.
comments.content	string	Conditional	This field displays the actual textual content in the language specified in the language field. This field is always used for containers using the Text type.
comments.language	string	Conditional	This two-letter code indicates the language used to display the content in the content field. The language will default to the language used on the eBay site if a specific language is not specified through the Accept-Language HTTP header. This field is always used for containers using the Text type. Applicable values are from LanguageEnum:See language.
comments.translatedFromContent	string	Conditional	If language translation/localization is required, this field displays the actual textual content in the language specified in the translatedFromLanguage field. If language translation was not required, this field is not applicable.
comments .translatedFromLanguage	string	Conditional	If language translation/localization is required, this two-letter code indicates the language used to display the content in the translatedFromContent field. If language translation was not required, this field is not applicable. Applicable values are from LanguageEnum:See translatedFromLanguage.
fileId	string	Conditional	The unique ID of a file attached to the return request.
forwardShippingLabelProvided	boolean	Optional	This field should be provided and set to `true` if the seller has already provided the buyer with a return shipping label. This field is generally provided if the labelAction value is set to `MARK_AS_SENT`.
labelAction	token	Required	This required field indicates what action is being taken with the POST /post-order/v2/return/{returnId}/add_shipping_label call. Based on what value is supplied here, the noLabelReason, forwardShippingLabelProvided, and labelId fields may become conditionally required. Applicable values: See LabelActionEnum
labelSentDate	DateTime	Conditional	This timestamp indicates when the label was sent to the buyer or seller.
labelSentDate.formattedValue	string	Optional	Reserved for future use.
labelSentDate.value	datetime	Conditional	The date and time defining the start or end of an action or event. The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Format: `[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z` Example: `2020-08-20T00:00:00.000Z`
noLabelReason	token	Conditional	This field is conditionally required if the labelAction value is set to `NO_LABEL`. If no shipping label is being provided, the seller must state the reason why through this field. Applicable values: See NoSellerUploadLabelReasonEnum
returnLabelCost	Amount	Optional	The cost of the return shipping label.
returnLabelCost .convertedFromCurrency	string	Optional	The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency. If no conversion occurs, this should not be populated. Applicable values are from CurrencyCodeEnum:See convertedFromCurrency.
returnLabelCost .convertedFromValue	number	Optional	The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field. If no conversion occurs, this should not be populated.
returnLabelCost.currency	string	Optional	A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type. Default: The currency of the authenticated user's country. Applicable values are from CurrencyCodeEnum:See currency.
returnLabelCost.exchangeRate	string	Optional	This field shows the exchange rate used to convert the amount in the convertedFromValue field to amount in the value field. This field is only returned when eBay does a currency version.
returnLabelCost.value	number	Optional	The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
trackingNumber	string	Conditional	The tracking number on the shipping label.

Output

Payload model

Note: For information about the error fields and how to work with them, see Error Handling.

The following lists all fields that could be included in the response.

Supported response formats: application/json, application/xml

For more information:
- See ProvideLabelResponse for a description of the response structure
- See the following table for descriptions of each of the data elements returned
- See the Samples for an example of the response format

{ /* ProvideLabelResponse */
"labelData": string,
"labelId": string,
"labelURL": string,
"trackingNumber": string
}

Response field descriptions

Output Container/Field	Type	Occurrence	Meaning
labelData	string	Conditionally	This field contains the text of the shipping label. This field is returned if the shipping label was successfully created.
labelId	string	Conditionally	The unique eBay-assigned ID of the shipping label. This field is returned if the shipping label was successfully created.
labelURL	string	Conditionally	This value is the URL of the page where the shipping label can be downloaded and printed. This field is returned if the shipping label was successfully created.
trackingNumber	string	Conditionally	The tracking number on the shipping label that will be used for tracking the shipment. This field is returned if the shipping label was successfully created.

null

Samples

New to making API calls? Please see Making a Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Sample: Create a Shipping Label

This call creates a return shipping label for the buyer to use.

Description

This call creates a return shipping label for the buyer to use. The shipping carrier, tracking number, and value are provided.

Input

The returnId parameter is required in the URI path to identify the return for which a return shipping label will be created. In the request payload, you must include the labelId value, which is the unique identifier of the return shipping label, and the value, which indicates the action being performed with this call. In this particular call sample, the seller is uploading a return shipping label, so the value provided in this field is . The carrierEnum and trackingNumber values should also be provided.

URL format. See also the non-wrapped version of this URL.

POST https://api.sandbox.ebay.com/post-order/v2/return/5********9/add_shipping_label
{ 
  "carrierEnum": "USPS",
  "comments":
  { 
    "content": "The shipping label you can use has been added to your return request.",
  },
  "labelId": "8******1",
  "trackingNumber": "9********************9",
  "labelAction": "UPLOAD_LABEL"
}

Output

The output fields are all returned with valid values, which confirms that the return shipping label was successfully sent to the buyer.

JSON format.
{ 
  "labelData": "B** B****, 2******************e, ********, CA 9***5, United States",
  "labelId": "8******1",
  "labelURL": "https://return.ebay.com/ws/eBayISAPI.dll?ResolveReturn&eventName=returnLabel&returnId=5********8",
  "trackingNumber": "9********************9"
}

Change History

Change Date	Description