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.
Output Samples Change History |
Input
See also Samples.
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. |
Input Samples Change History |
Output
See also Samples.
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. |
Input Output Change History |
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.
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"
}
Input Output Samples |
Change History
Change Date | Description |
---|