eBay Post-Order APIVersion 2.7.2
 

Get Return Estimate

POST /post-order/v2/return/estimate

This method is used on behalf of a buyer to retrieve the estimated refund amount and return shipping costs associated with returning an item. This method can be used regardless of whether or not a return request was actually filed against the line item.

Input

See also Samples.

Resource URI (production)

POST https://api.ebay.com/post-order/v2/return/estimate

This call has no path or query parameters.


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.

{ /* GetEstimateRequest */
"itemId": string,
"reason": string,
"returnQuantity": integer,
"transactionId": string
}

Request field descriptions



Input Container/Field Type Occurrence Meaning
itemId string Required The unique identifier for the eBay listing where the item was purchased. This field is used in conjunction with the transactionId field to identify a line item within an order.
reason string Optional This enumeration value indicates the reason why the buyer is returning the item.

The supported enumeration values representing valid return reasons are defined in the ReturnReasonEnum type definition.

Applicable values: See ReturnReasonEnum
returnQuantity integer Optional This integer value indicates the quantity of the line item being returned. This number is typically 1, unless the buyer bought multiple quantity of the item in a multiple-quantity, fixed-price listing. This value must be provided to get accurate estimates in the response.
transactionId string Required The unique identifier for the purchase of the item. This value is created right when the buyer is committed to buying the item, whether that buyer uses a 'Buy it Now' capability, is the winning bidder of an auction, or the buyer's Best Offer is accepted by the seller. This field is used in conjunction with the itemId field to identify a line item within an order.

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 GetEstimateResponse 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

{ /* GetEstimateResponse */
"refundInfo":
    { /* EstimatedRefundInfoType */
    "buyerTotalAmount":
        { /* Amount */
        "convertedFromCurrency": string,
        "convertedFromValue": number,
        "currency": string,
        "exchangeRate": string,
        "value": number
        },
    "estimatedRefundDetail":
        { /* EstimatedRefundDetailType */
        "itemizedRefundDetails": [
            { /* EstimatedRefundType */
            "estimatedAmount":
                { /* Amount */
                "convertedFromCurrency": string,
                "convertedFromValue": number,
                "currency": string,
                "exchangeRate": string,
                "value": number
                },
            "maxAmount":
                { /* Amount */
                "convertedFromCurrency": string,
                "convertedFromValue": number,
                "currency": string,
                "exchangeRate": string,
                "value": number
                },
            "minAmount":
                { /* Amount */
                "convertedFromCurrency": string,
                "convertedFromValue": number,
                "currency": string,
                "exchangeRate": string,
                "value": number
                },
            "purchasePriceDeductedPercentageList": [
                integer
                /* More integer nodes here */
              ],
            "refundFeeType": string,
            "restockingFeePercentage": string
            }
            /* More EstimatedRefundType nodes here */
          ],
        "optionalRefundLineItems": [
            { /* EstimatedRefundType */
            "estimatedAmount":
                { /* Amount */
                "convertedFromCurrency": string,
                "convertedFromValue": number,
                "currency": string,
                "exchangeRate": string,
                "value": number
                },
            "maxAmount":
                { /* Amount */
                "convertedFromCurrency": string,
                "convertedFromValue": number,
                "currency": string,
                "exchangeRate": string,
                "value": number
                },
            "minAmount":
                { /* Amount */
                "convertedFromCurrency": string,
                "convertedFromValue": number,
                "currency": string,
                "exchangeRate": string,
                "value": number
                },
            "purchasePriceDeductedPercentageList": [
                integer
                /* More integer nodes here */
              ],
            "refundFeeType": string,
            "restockingFeePercentage": string
            }
            /* More EstimatedRefundType nodes here */
          ]
        },
    "sellerTotalAmount":
        { /* Amount */
        "convertedFromCurrency": string,
        "convertedFromValue": number,
        "currency": string,
        "exchangeRate": string,
        "value": number
        }
    },
"returnShippingCostInfo":
    { /* EstimatedShippingInfoType */
    "carriers": [
        { /* CarrierShippingCostInfoType */
        "carrier": string,
        "shippingCost":
            { /* ReturnShippingCostDetailType */
            "itemizedReturnShippingCost": [
                { /* ItemizedReturnShippingCostType */
                "amount":
                    { /* Amount */
                    "convertedFromCurrency": string,
                    "convertedFromValue": number,
                    "currency": string,
                    "exchangeRate": string,
                    "value": number
                    },
                "returnShippingCostType": string
                }
                /* More ItemizedReturnShippingCostType nodes here */
              ],
            "totalAmount":
                { /* Amount */
                "convertedFromCurrency": string,
                "convertedFromValue": number,
                "currency": string,
                "exchangeRate": string,
                "value": number
                }
            }
        }
        /* More CarrierShippingCostInfoType nodes here */
      ],
    "returnShipmentPayer": string
    }
}

Response field descriptions



Output Container/Field Type Occurrence Meaning
refundInfo EstimatedRefundInfoType Always This container gives an overview of estimated refund information if the buyer creates a return request and is expecting money back.
refundInfo.buyerTotalAmount Amount Always This container shows the estimated amount of money that the buyer will receive for one or more refunds associated with the line item specified in the request.
refundInfo.buyerTotalAmount
  .convertedFromCurrency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo.buyerTotalAmount
  .convertedFromValue
number Conditionally 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.
refundInfo.buyerTotalAmount
  .currency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo.buyerTotalAmount
  .exchangeRate
string Conditionally 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.
refundInfo.buyerTotalAmount
  .value
number Conditionally The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
refundInfo
  .estimatedRefundDetail
EstimatedRefundDetailType Always This container shows estimated refund information for one or more hypothetical buyer refunds associated with the line item specified in the request. There will be one itemizedRefundDetail container returned under this container for each refund fee type (such as purchase price and original shipping).
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
array of EstimatedRefundType Conditionally This array shows the estimated amounts for one or more refunds that the seller may have to issue to a buyer in a return request.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .estimatedAmount
Amount Always This container shows the estimated amount of the refund.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .estimatedAmount
  .convertedFromCurrency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .estimatedAmount
  .convertedFromValue
number Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .estimatedAmount.currency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .estimatedAmount.exchangeRate
string Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .estimatedAmount.value
number Conditionally The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .maxAmount
Amount Always This container shows the maximum amount that the refund could be based on the cost of the order.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .maxAmount
  .convertedFromCurrency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .maxAmount.convertedFromValue
number Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .maxAmount.currency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .maxAmount.exchangeRate
string Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .maxAmount.value
number Conditionally The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .minAmount
Amount Always This container shows the minimum amount that the refund could be based on the cost of the order.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .minAmount
  .convertedFromCurrency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .minAmount.convertedFromValue
number Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .minAmount.currency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .minAmount.exchangeRate
string Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .minAmount.value
number Conditionally The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .purchasePriceDeductedPercentageList
array of integer Conditionally This array shows one or more percentage values, and these values indicate the percentage value(s) deducted off of the purchase price.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .refundFeeType
string Always This enumerated value indicates the type of refund. When issuing a refund through the POST /post-order/v2/return/{returnId}/issue_refund method, the seller must use a separate itemizedRefundDetail container for each refund type, such as one for the purchase price, one for original shipping, and one for a restocking fee (if applicable).

Applicable values are from RefundFeeTypeEnum:See refundFeeType.
Code so that your app gracefully handles any future changes to this list.
refundInfo
  .estimatedRefundDetail
  .itemizedRefundDetails
  .restockingFeePercentage
string Conditionally THIS FIELD IS DEPRECATED.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
array of EstimatedRefundType Conditionally This array shows the different refund types and associated costs that the seller can voluntarily issue to the buyer at his/her discretion. The seller is not obligated to issue any of the refund types in this array, but might do so as a matter of good customer service.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .estimatedAmount
Amount Always This container shows the estimated amount of the refund.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .estimatedAmount
  .convertedFromCurrency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .estimatedAmount
  .convertedFromValue
number Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .estimatedAmount.currency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .estimatedAmount.exchangeRate
string Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .estimatedAmount.value
number Conditionally The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .maxAmount
Amount Always This container shows the maximum amount that the refund could be based on the cost of the order.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .maxAmount
  .convertedFromCurrency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .maxAmount.convertedFromValue
number Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .maxAmount.currency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .maxAmount.exchangeRate
string Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .maxAmount.value
number Conditionally The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .minAmount
Amount Always This container shows the minimum amount that the refund could be based on the cost of the order.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .minAmount
  .convertedFromCurrency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .minAmount.convertedFromValue
number Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .minAmount.currency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .minAmount.exchangeRate
string Conditionally 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.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .minAmount.value
number Conditionally The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .purchasePriceDeductedPercentageList
array of integer Conditionally This array shows one or more percentage values, and these values indicate the percentage value(s) deducted off of the purchase price.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .refundFeeType
string Always This enumerated value indicates the type of refund. When issuing a refund through the POST /post-order/v2/return/{returnId}/issue_refund method, the seller must use a separate itemizedRefundDetail container for each refund type, such as one for the purchase price, one for original shipping, and one for a restocking fee (if applicable).

Applicable values are from RefundFeeTypeEnum:See refundFeeType.
Code so that your app gracefully handles any future changes to this list.
refundInfo
  .estimatedRefundDetail
  .optionalRefundLineItems
  .restockingFeePercentage
string Conditionally THIS FIELD IS DEPRECATED.
refundInfo.sellerTotalAmount Amount Always This container shows the estimated amount of money that the seller would owe the buyer for the refund(s). This will generally be a negative value because it is money that the seller owes the buyer.
refundInfo.sellerTotalAmount
  .convertedFromCurrency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo.sellerTotalAmount
  .convertedFromValue
number Conditionally 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.
refundInfo.sellerTotalAmount
  .currency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
refundInfo.sellerTotalAmount
  .exchangeRate
string Conditionally 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.
refundInfo.sellerTotalAmount
  .value
number Conditionally The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
returnShippingCostInfo EstimatedShippingInfoType Always This container gives an overview of estimated return shipping cost information if the buyer creates a return request.
returnShippingCostInfo
  .carriers
array of CarrierShippingCostInfoType Conditionally This container consists of an array of one or more shipping carriers that can be used to return ship an item, and how much each shipping carrier will approximately cost. One or more shipping carriers will be returned if available.
returnShippingCostInfo
  .carriers.carrier
string Conditionally This enumeration value indicates a shipping carrier that can be used to ship the return item. ShippingCarrierEnum contains some popular shipping carriers for the US, UK, Germany, Canada, and Australia, but it is not a complete list.

Applicable values: See ShippingCarrierEnum
returnShippingCostInfo
  .carriers.shippingCost
ReturnShippingCostDetailType Conditionally This container provides an estimate of itemized and total shipping costs if the buyer was to use the shipping carrier specified in the carrier field.
returnShippingCostInfo
  .carriers.shippingCost
  .itemizedReturnShippingCost
array of ItemizedReturnShippingCostType Conditionally This container consists of the costs to ship an item. A separate itemizedReturnShippingCost node will be returned for each shipping cost type, such as label cost, shipping insurance, or the signature confirmation service.
returnShippingCostInfo
  .carriers.shippingCost
  .itemizedReturnShippingCost
  .amount
Amount Conditionally This container shows the amount for the shipping cost type shown in the returnShippingCostType field.
returnShippingCostInfo
  .carriers.shippingCost
  .itemizedReturnShippingCost
  .amount.convertedFromCurrency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
returnShippingCostInfo
  .carriers.shippingCost
  .itemizedReturnShippingCost
  .amount.convertedFromValue
number Conditionally 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.
returnShippingCostInfo
  .carriers.shippingCost
  .itemizedReturnShippingCost
  .amount.currency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
returnShippingCostInfo
  .carriers.shippingCost
  .itemizedReturnShippingCost
  .amount.exchangeRate
string Conditionally 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.
returnShippingCostInfo
  .carriers.shippingCost
  .itemizedReturnShippingCost
  .amount.value
number Conditionally The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
returnShippingCostInfo
  .carriers.shippingCost
  .itemizedReturnShippingCost
  .returnShippingCostType
string Conditionally This enumerated value indicates the type of shipping cost, such as the cost of the shipping label, shipping insurance, or the signature confirmation service.

Applicable values are from ReturnShippingCostType:

INSURANCE
This enumeration value indicates that the shipping cost is the price of shipping insurance to ship the return or replacement item.
LABEL_COST
This enumeration value indicates that the shipping cost is the price of the shipping label for the return or replacement item.
OTHER
This enumeration value indicates that the shipping cost is not classified or is not known.
SIGNATURE_CONFIRMATION_COST
This enumeration value indicates that the shipping cost is the price to ship the return or replacement item using certified shipping.

Code so that your app gracefully handles any future changes to this list.
returnShippingCostInfo
  .carriers.shippingCost
  .totalAmount
Amount Conditionally This container shows the total amount of shipping costs associated with shipping the item. This value should equal the sum of the values in the itemizedReturnShippingCost.amount field(s).
returnShippingCostInfo
  .carriers.shippingCost
  .totalAmount
  .convertedFromCurrency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
returnShippingCostInfo
  .carriers.shippingCost
  .totalAmount
  .convertedFromValue
number Conditionally 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.
returnShippingCostInfo
  .carriers.shippingCost
  .totalAmount.currency
string Conditionally 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.

The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition.

Applicable values: See CurrencyCodeEnum
returnShippingCostInfo
  .carriers.shippingCost
  .totalAmount.exchangeRate
string Conditionally 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.
returnShippingCostInfo
  .carriers.shippingCost
  .totalAmount.value
number Conditionally The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type.
returnShippingCostInfo
  .returnShipmentPayer
string Always This enumeration value indicates whether the buyer or seller is responsible for return shipping costs.

Applicable values are from ReturnUserRoleEnum:

BUYER
This enumeration value indicates that the buyer performed the action on the return request.
EBAY
This enumeration value indicates that eBay customer support performed the action on the return request.
OTHER
This enumeration value indicates that it is unknown who/what performed the action on the return request.
SELLER
This enumeration value indicates that the seller performed the action on the return request.
SYSTEM
This enumeration value indicates that the action on the return request was an automated action initiated by eBay's system.

Code so that your app gracefully handles any future changes to this list.
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: Basic Call

Returns return shipping costs and estimated refund amount.

Description

This call is used to return shipping costs and the estimated refund amount for a specified order line item. This call will work regardless of whether or not there's an open return request against the order line item.

Input

In the request payload, the user identifies the order line item with the itemId and transactionId fields, and also provides the return reason and the quantity of the line item being returned.

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

POST https://api.ebay.com/post-order/v2/return/estimate

{ 
"itemId": "1**********6",
"transactionId": "8********9",
"reason": NO_LONGER_NEED_ITEM,
"returnQuantity": 1
}

Output

The returnShippingCostInfo container first indicates who is responsible for return shippping costs. For this sample, the returnShipmentPayer field indicates that the seller is responsible for return shipping costs, which total 3.00 USD.

Under the carriers container, the cost to return the line item is given for one or more shipping carriers. In this sample call, the only shipping carrier given is USPS. The total return shipping cost is given in the shippingCost.totalAmount container, and the itemized shipping costs are shown in the itemizedReturnShippingCost container. For this sample, the only return shipping cost is the cost of the shipping label; however, it is possible that other related shipping costs can be returned in the itemizedReturnShippingCost container, such as shipping insurance, or certified/signature confirmation shipping costs.

In the refundInfo container, the expected refund to the buyer is 18.00 USD, as shown in the buyerTotalAmount container. The estimatedRefundDetail container shows the itemized refund amounts. The buyer will be refunded the purchase price of 20.00 USD, but the seller will deduct 2.00 USD from this amount for a restocking fee. This accounts for the total refund amount of 18.00 USD.

JSON format.
{
	"returnShippingCostInfo": {
			"returnShipmentPayer": "SELLER",
			"carriers": [
					{
					"carrier": "USPS",
					"shippingCost": {
							"totalAmount": {
									"value": 3.0,
									"currency": "USD"
							},
							"itemizedReturnShippingCost": [
									{
									"returnShippingCostType": "LABEL_COST",
									"amount": 
											{
											"value": 3.0,
											"currency": "USD"
											}
									}
							]
					}
			}
		]
	},
	"refundInfo": {
			"buyerTotalAmount": {
					"value": 18.0,
					"currency": "USD"
			},
			"sellerTotalAmount": {
					"value": 18.0,
					"currency": "USD"
			},
			"estimatedRefundDetail": {
					"itemizedRefundDetail": [
						{
						"refundFeeType": "PURCHASE_PRICE",
						"estimatedAmount": {
								"value": 20.0,
								"currency": "USD"
								},
						},
						{
						"refundFeeType": "RESTOCKING_FEE",
						"estimatedAmount": {
								"value": -2.0,
								"currency": "USD"
								},
						"restockingFeePercentage": "10"
					}
				]
			}
		}
}



Change History

Change Date Description
1.0
2015-06-30
  • Call (added): New call.