eBay Post-Order APIVersion 2

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

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 */
    "value": datetime
    },
"noLabelReason": token,
"returnLabelCost":
    { /* Amount */
    "convertedFromCurrency": string,
    "convertedFromValue": number,
    "currency": 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.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 Conditional This field indicates the currency involved in a monetary transaction before a price conversion was performed. Generally, this is the currency used by the buyer. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.

Applicable values are from CurrencyCodeEnum:See convertedFromCurrency.
returnLabelCost
  .convertedFromValue
number Conditional This value is the dollar amount of the currency involved in a monetary transaction before a price conversion was performed. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.
returnLabelCost.currency string Conditional This field indicates the currency involved in a monetary transaction. Generally, this is the currency used by the listing site's country.

Applicable values are from CurrencyCodeEnum:See currency.
returnLabelCost.value number Conditional The dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the listing site.
trackingNumber string Conditional The tracking number on the shipping label.

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.



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/5000116809/add_shipping_label
{ 
  "carrierEnum": "USPS",
  "comments":
  { 
    "content": "The shipping label you can use has been added to your return request.",
  },
  "labelId": "80034841",
  "trackingNumber": "9301920128700000562779",
  "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": "Ben Buyer, 2145 Hamilton Avenue, San Jose, CA 95125, United States",
  "labelId": "80034841",
  "labelURL": "https://return.ebay.com/ws/eBayISAPI.dll?ResolveReturn&eventName=returnLabel&returnId=5000119608",
  "trackingNumber": "9301920128700000562779"
}



Change History

Change Date Description