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 identifier 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": string,
"labelId": string,
"labelSentDate":
    { /* DateTime */
    "value": datetime
    },
"noLabelReason": string,
"returnLabelCost": b:Amount,
"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 identifier 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 string 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 are from LabelActionEnum:See labelAction.
labelId string Conditional This field valid only on the German marketplace (EBAY_DE), where sellers can provide buyers with their own return shipping label.

On the German site, this field is required if the labelAction value is set to UPLOAD_LABEL and the seller is providing their own shipping label (not an eBay shipping label) to the buyer. The labelId value is should equal the shipment tracking number of the shipping label being provided to the buyer.
labelSentDate DateTime Conditional This timestamp indicates when the label was sent to the buyer or seller.
labelSentDate.value datetime Conditional This field is a timestamp for when an event or action occurred or is going to occur in the near future. It is intended for consumption by a caller's code for further computation, transformation, or comparison, and not for the end user. It uses the ISO 8601 date and time format with the 24-hour clock and Universal Coordinated Time (UTC). Following is the format template, and an example of a timestamp in this format:

Format: YYYY-MM-DDTHH:MM:SS.SSSZ

Example: 2004-08-04T19:09:02.768Z

This field is always used for containers using the DateTime type.
noLabelReason string 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 are from NoSellerUploadLabelReasonEnum:See noLabelReason.
returnLabelCost b:Amount Optional The cost of the return shipping label.
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 identifier 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