Skip to main content

POST/shipping_quote

The createShippingQuote method returns a shipping quote that contains a list of live "rates."

Each rate represents an offer made by a shipping carrier for a specific service and each offer has a live quote for the base service cost. Rates have a time window in which they are "live," and rates expire when their purchase window ends. If offered by the carrier, rates can include shipping options (and their associated prices), and users can add any offered shipping option to the base service should they desire. Also, depending on the services required, rates can also include pickup and delivery windows.

Note: The Logistics API only supports USPS shipping rates and labels.
Each rate is for a single package and is based on the following information:

  • The shipping origin
  • The shipping destination
  • The package size (weight and dimensions)
Rates are identified by a unique eBay-assigned rateId and rates are based on price points, pickup and delivery time frames, and other user requirements. Because each rate offered must be compliant with the eBay shipping program, all rates reflect eBay-negotiated prices.

The various rates returned in a shipping quote offer the user a choice from which they can choose a shipping service that best fits their needs. Select the rate for your shipment and using the associated rateId, call createFromShippingQuote to create a shipment and generate a shipping label that you can use to ship the package.

Input

Resource URI

POST https://api.ebay.com/sell/logistics/v1_beta/shipping_quote

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

This method has no URI parameters.

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

HeaderTypeDescription
Content-TypestringThis header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

X-EBAY-C-MARKETPLACE-IDstringThis header parameter specifies the eBay marketplace for the shipping quote that is being created.

For a list of valid values, refer to the section Marketplace ID Values in the Using eBay RESTful APIs guide.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.logistics

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

Request fields

Input container/fieldTypeDescription
ordersarray of Order

In this array, the seller specifies one or more orders that will be shipped in the shipping package.

A shipping package can contain any number of line items from one or more orders, providing they all ship in the same package.

Maximum list size: 10

Occurrence: Required

orders.channelstring

The marketplace where the order was created.

Use the value EBAY to get the rates available for eBay orders.

Occurrence: Required

orders.orderIdstring

The unique identifier of the order. The getOrders method of the Fulfillment API can be used to retrieve order IDs.

Occurrence: Required

packageSpecificationPackageSpecification

Declares the weight and dimensions of the package.

Occurrence: Required

packageSpecification.dimensionsDimensions

Declares the height, length, width, and unit of measure for the package to be shipped.

Occurrence: Optional

packageSpecification.dimensions.heightstring

The numeric value of the height of the package.

Occurrence: Optional

packageSpecification.dimensions.lengthstring

The numeric value of the length of the package.

Occurrence: Optional

packageSpecification.dimensions.unitLengthUnitOfMeasureEnum

The unit of measure used to express the height, length, and width of the package.

Occurrence: Optional

packageSpecification.dimensions.widthstring

The numeric value of the width of the package.

Occurrence: Optional

packageSpecification.weightWeight

Declares the weight of the package.

Occurrence: Optional

packageSpecification.weight.unitWeightUnitOfMeasureEnum

The unit of measurement used to specify the weight of a shipping package. Both the unit and value fields are required if the weight container is used. If the English system of measurement is being used, the applicable values for weight units are POUND and OUNCE. If the metric system of measurement is being used, the applicable values for weight units are KILOGRAM and GRAM. The metric system is used by most countries outside of the US.

Occurrence: Optional

packageSpecification.weight.valuestring

The numeric value of the weight of the package, as measured by the value of unit.

Occurrence: Optional

shipFromContact

The address and contact details pertaining to the origin of the shipment.

Occurrence: Required

shipFrom.companyNamestring

The company name with which the contact is associated.

Occurrence: Optional

shipFrom.contactAddressContactAddress

The details of the contact's geographical address.

Occurrence: Required

shipFrom.contactAddress.addressLine1string

The first line of the street address.

Occurrence: Required

shipFrom.contactAddress.addressLine2string

The second line of the street address. Use this field for additional address information, such as a suite or apartment number.

Occurrence: Optional

shipFrom.contactAddress.citystring

The city in which the address is located.

Occurrence: Optional

shipFrom.contactAddress.countryCodeCountryCodeEnum

The country of the address, represented as two-letter ISO 3166 country code. For example, US represents the United States and DE represents Germany.

Occurrence: Required

shipFrom.contactAddress.countystring

The county (not country) in which the address is located. Counties typically contain multiple cities or towns.

Occurrence: Required

shipFrom.contactAddress.postalCodestring

The postal code of the address.

Occurrence: Required

shipFrom.contactAddress.stateOrProvincestring

The state or province in which the address is located. States and provinces often contain multiple counties.

Occurrence: Optional

shipFrom.fullNamestring

The contact's full name.

Occurrence: Required

shipFrom.primaryPhonePhoneNumber

The contact's primary telephone number.

Occurrence: Optional

shipFrom.primaryPhone.phoneNumberstring

A telephone number.

Occurrence: Required

shipToContact

The address and contact details pertaining to the shipment's destination.

Occurrence: Required

shipTo.companyNamestring

The company name with which the contact is associated.

Occurrence: Optional

shipTo.contactAddressContactAddress

The details of the contact's geographical address.

Occurrence: Required

shipTo.contactAddress.addressLine1string

The first line of the street address.

Occurrence: Required

shipTo.contactAddress.addressLine2string

The second line of the street address. Use this field for additional address information, such as a suite or apartment number.

Occurrence: Optional

shipTo.contactAddress.citystring

The city in which the address is located.

Occurrence: Optional

shipTo.contactAddress.countryCodeCountryCodeEnum

The country of the address, represented as two-letter ISO 3166 country code. For example, US represents the United States and DE represents Germany.

Occurrence: Required

shipTo.contactAddress.countystring

The county (not country) in which the address is located. Counties typically contain multiple cities or towns.

Occurrence: Required

shipTo.contactAddress.postalCodestring

The postal code of the address.

Occurrence: Required

shipTo.contactAddress.stateOrProvincestring

The state or province in which the address is located. States and provinces often contain multiple counties.

Occurrence: Optional

shipTo.fullNamestring

The contact's full name.

Occurrence: Required

shipTo.primaryPhonePhoneNumber

The contact's primary telephone number.

Occurrence: Optional

shipTo.primaryPhone.phoneNumberstring

A telephone number.

Occurrence: Required

Output

HTTP response headers

This call has no response headers.

Response payload

{ /* ShippingQuote */
"orders" : [
{ /* Order */ }
],
}

Response fields

Output container/fieldTypeDescription
creationDatestring

The date and time this quote was created, expressed as an ISO 8601 UTC string.

Occurrence: Conditional

expirationDatestring

The last date and time that this quote will be honored, expressed as an ISO 8601 UTC string. After this time the quote expires and the expressed rates can no longer be purchased.

Occurrence: Conditional

ordersarray of Order

A list of one or more orders that will be shipped in the shipping package.

Occurrence: Always

orders.channelstring

The marketplace where the order was created.

Use the value EBAY to get the rates available for eBay orders.

Occurrence: Always

orders.orderIdstring

The unique identifier of the order. The getOrders method of the Fulfillment API can be used to retrieve order IDs.

Occurrence: Always

packageSpecificationPackageSpecification

The weight and dimensions of the package covered by this shipping quote.

Occurrence: Conditional

packageSpecification.dimensionsDimensions

Declares the height, length, width, and unit of measure for the package to be shipped.

Occurrence: Conditional

packageSpecification.dimensions.heightstring

The numeric value of the height of the package.

Occurrence: Conditional

packageSpecification.dimensions.lengthstring

The numeric value of the length of the package.

Occurrence: Conditional

packageSpecification.dimensions.unitLengthUnitOfMeasureEnum

The unit of measure used to express the height, length, and width of the package.

Occurrence: Conditional

packageSpecification.dimensions.widthstring

The numeric value of the width of the package.

Occurrence: Conditional

packageSpecification.weightWeight

Declares the weight of the package.

Occurrence: Conditional

packageSpecification.weight.unitWeightUnitOfMeasureEnum

The unit of measurement used to specify the weight of a shipping package. Both the unit and value fields are required if the weight container is used. If the English system of measurement is being used, the applicable values for weight units are POUND and OUNCE. If the metric system of measurement is being used, the applicable values for weight units are KILOGRAM and GRAM. The metric system is used by most countries outside of the US.

Occurrence: Conditional

packageSpecification.weight.valuestring

The numeric value of the weight of the package, as measured by the value of unit.

Occurrence: Conditional

ratesarray of Rate

A list of rates where each rate, as identified by a rateId, contains information about a specific shipping service offered by a carrier. Rates include shipping carrier and service, the to and from locations, the pickup and delivery windows, the seller's shipping parameters, the service constraints, and the cost for the base service and a list of additional shipping options.

Note: The Logistics API only supports USPS shipping rates and labels.
Each rate offered is supported by a label service where you can purchase the rate, and associated shipping label, via a call to createFromShippingQuote.

Occurrence: Conditional

rates.additionalOptionsarray of AdditionalOption

Contains service and pricing information for one or more shipping options that are offered by the carrier and can be purchased in addition to the base shipping service provided by this rate. Shipping options can include items such as INSURANCE and SIGNATURE.

Occurrence: Conditional

rates.additionalOptions.additionalCostAmount

The monetary cost of the additional shipping option identified by the optionType field.

Occurrence: Conditional

rates.additionalOptions.additionalCost.currencyCurrencyCodeEnum

The base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Conditional

rates.additionalOptions.additionalCost.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

rates.additionalOptions.optionTypestring

The name of a shipping option that can be purchased in addition to the base shipping cost of this rate. The value supplied in this field must match exactly the option name as supplied by the selected rate.

Occurrence: Conditional

rates.baseShippingCostAmount

A live quote for the cost that the carrier (identified by shippingCarrierCode) is charging for the shipping service being offered (identified by shippingServiceCode), excluding any additional shipping options.

Occurrence: Conditional

rates.baseShippingCost.currencyCurrencyCodeEnum

The base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO 4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The default currency of the eBay marketplace that hosts the listing.

Occurrence: Conditional

rates.baseShippingCost.valuestring

The monetary amount in the specified currency.

Required in the amount type.

Occurrence: Conditional

rates.destinationTimeZonestring

The name of the time zone region, as defined in the IANA Time Zone Database, to which the package is being shipped.

Delivery dates are calculated relative to this time zone.

Note: This is different from a Coordinated Universal Time (UTC) offset. For example, the America/Los_Angeles time zone identifies a region with the UTC standard time offset of -08:00, but so do several other time zones, including America/Tijuana,America/Dawson, and Pacific/Pitcairn.

Occurrence: Conditional

rates.maxEstimatedDeliveryDatestring

The latest stated date and time the shipment will be delivered at this rate.

The time stamp 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: 2018-08-20T07:09:00.000Z

Occurrence: Conditional

rates.minEstimatedDeliveryDatestring

The estimated earliest date and time the shipment will be delivered at this rate. The time stamp is formatted as an ISO 8601 UTC string.

Occurrence: Conditional

rates.pickupNetworksarray of string

A list of pickup networks compatible with the shipping service.

Occurrence: Conditional

rates.pickupSlotsarray of PickupSlot

A list of available pickup slots for the package.

Occurrence: Conditional

rates.pickupSlots.pickupSlotEndTimestring

The date and time the pickup slot ends, 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: 2018-08-20T07:09:00.000Z

Occurrence: Conditional

rates.pickupSlots.pickupSlotIdstring

Seller-defined name for the pickup slot.

Occurrence: Conditional

rates.pickupSlots.pickupSlotStartTimestring

The date and time the pickup slot begins, formatted as an ISO 8601 UTC string.

Occurrence: Conditional

rates.pickupSlots.pickupSlotTimeZonestring

The time zone of the pickup location, returned as Time Zone Database ID (also know as an Olson time zone ID).

Occurrence: Conditional

rates.pickupTypePickupTypeEnum

The type of pickup or drop-off service associated with the pickupSlots time frames.

Occurrence: Conditional

rates.rateIdstring

The unique eBay-assigned ID for this shipping rate.

Occurrence: Conditional

rates.rateRecommendationarray of RateRecommendationEnum

A list of reasons this rate is recommended. Available values are:

  • BUYER_CHOSEN — The rate meets or exceeds the requirements of the buyer's preferred shipping option.
  • CHEAPEST_ON_TIME — The rate is the cheapest rate available that will provide delivery within the seller's time frame commitment.
  • EBAY_PLUS_OK — The rate complies with the shipping requirements of the eBay Plus program.
  • FASTEST_ON_TIME — The rate has the fastest shipping time, and will provide delivery within the seller's time frame commitment.
  • GUARANTEED_DELIVERY_OK — The rate complies with the shipping requirements of the eBay Guaranteed Delivery program.

Occurrence: Conditional

rates.shippingCarrierCodestring

The code name of the shipping carrier who will provide the service identified by shippingServiceCode.

Occurrence: Conditional

rates.shippingCarrierNamestring

The common name of the shipping carrier.

Occurrence: Conditional

rates.shippingServiceCodestring

The code name of the shipping service to be provided by the carrier identified by shippingCarrierCode.

Occurrence: Conditional

rates.shippingServiceNamestring

The common name of the shipping service.

Occurrence: Conditional

shipFromContact

The address and contact details for the origin of the shipment.

Occurrence: Conditional

shipFrom.companyNamestring

The company name with which the contact is associated.

Occurrence: Conditional

shipFrom.contactAddressContactAddress

The details of the contact's geographical address.

Occurrence: Conditional

shipFrom.contactAddress.addressLine1string

The first line of the street address.

Occurrence: Always

shipFrom.contactAddress.addressLine2string

The second line of the street address. Use this field for additional address information, such as a suite or apartment number.

Occurrence: Conditional

shipFrom.contactAddress.citystring

The city in which the address is located.

Occurrence: Conditional

shipFrom.contactAddress.countryCodeCountryCodeEnum

The country of the address, represented as two-letter ISO 3166 country code. For example, US represents the United States and DE represents Germany.

Occurrence: Conditional

shipFrom.contactAddress.countystring

The county (not country) in which the address is located. Counties typically contain multiple cities or towns.

Occurrence: Conditional

shipFrom.contactAddress.postalCodestring

The postal code of the address.

Occurrence: Always

shipFrom.contactAddress.stateOrProvincestring

The state or province in which the address is located. States and provinces often contain multiple counties.

Occurrence: Conditional

shipFrom.fullNamestring

The contact's full name.

Occurrence: Conditional

shipFrom.primaryPhonePhoneNumber

The contact's primary telephone number.

Occurrence: Conditional

shipFrom.primaryPhone.phoneNumberstring

A telephone number.

Occurrence: Conditional

shippingQuoteIdstring

The unique eBay-assigned ID for this shipping quote. The value of this field is associated with a specific package, based on its origin, destination, and size.

Occurrence: Conditional

shipToContact

The address and contact details for the origin of the shipment.

Occurrence: Conditional

shipTo.companyNamestring

The company name with which the contact is associated.

Occurrence: Conditional

shipTo.contactAddressContactAddress

The details of the contact's geographical address.

Occurrence: Conditional

shipTo.contactAddress.addressLine1string

The first line of the street address.

Occurrence: Always

shipTo.contactAddress.addressLine2string

The second line of the street address. Use this field for additional address information, such as a suite or apartment number.

Occurrence: Conditional

shipTo.contactAddress.citystring

The city in which the address is located.

Occurrence: Conditional

shipTo.contactAddress.countryCodeCountryCodeEnum

The country of the address, represented as two-letter ISO 3166 country code. For example, US represents the United States and DE represents Germany.

Occurrence: Conditional

shipTo.contactAddress.countystring

The county (not country) in which the address is located. Counties typically contain multiple cities or towns.

Occurrence: Conditional

shipTo.contactAddress.postalCodestring

The postal code of the address.

Occurrence: Always

shipTo.contactAddress.stateOrProvincestring

The state or province in which the address is located. States and provinces often contain multiple counties.

Occurrence: Conditional

shipTo.fullNamestring

The contact's full name.

Occurrence: Conditional

shipTo.primaryPhonePhoneNumber

The contact's primary telephone number.

Occurrence: Conditional

shipTo.primaryPhone.phoneNumberstring

A telephone number.

Occurrence: Conditional

warningsarray of ErrorDetailV3

A list of any warnings triggered by the request.

Occurrence: Conditional

warnings.categorystring

The category type for this error or warning. It takes a string that can have one of three values:

  • Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.
  • Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as "Seller does not ship item to Antarctica" or "Buyer ineligible to purchase an alcoholic item". Business errors are not syntactical input errors.
  • Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.

Occurrence: Conditional

warnings.domainstring

Name of the domain containing the service or application.

Occurrence: Conditional

warnings.errorIdinteger

A positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Conditional

warnings.inputRefIdsarray of string

Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.

Occurrence: Conditional

warnings.longMessagestring

An expanded version of message that should be around 100-200 characters long, but is not required to be such.

Occurrence: Conditional

warnings.messagestring

An end user and app-developer friendly device agnostic message. It explains what the error or warning is, and how to fix it (in a general sense). Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale.

Occurrence: Conditional

warnings.outputRefIdsarray of string

Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3

This optional complex field type contains a list of one or more context-specific ErrorParameter objects, with each item in the list entry being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.

Occurrence: Conditional

warnings.parameters.namestring

Name of the entity that threw the error.

Occurrence: Conditional

warnings.parameters.valuestring

A description of the error.

Occurrence: Conditional

warnings.subdomainstring

Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain.

Occurrence: NA

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
201Created
400Bad Request
409Conflict
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
90000API_LOGISTICSAPPLICATIONA system error has occurred.
90010API_LOGISTICSREQUESTMissing field {fieldName}.
90020API_LOGISTICSREQUESTInvalid field {fieldName}.
90100API_LOGISTICSREQUESTNo shipping services available for the provided addresses.
90110API_LOGISTICSREQUESTThe order {orderId} was not found on the platform.
90120API_LOGISTICSREQUESTThe package specification is incompatible with the destination.
90130API_LOGISTICSREQUESTOrder {orderId} is incompatible with our services.
90133API_LOGISTICSREQUESTMaximum number of orders exceeded. Current limitation is 10.

Warnings

For more on warnings, plus the codes of other common warnings, see Handling errors.

CodeDomainCategoryMeaning
90135API_LOGISTICSREQUESTThe provided shipTo address does not match the destination address of the order(s).

Samples

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

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Creating a shipping quote

This sample creates a shipping quote for an eBay package.

Input

In the request, define the "From:" address, the "To:" address, the package size (dimensions and weight), and the order information. This method also requires you to specify the eBay marketplace ID using the X-EBAY-C-MARKETPLACE-ID HTTP header.

POSThttps://api.ebay.com/sell/logistics/v1_beta/shipping_quote

Output

A successful request returns a complete shipping quote, along with a shipping quote ID that you can use to create a "shipment," or retrieve the quote at a later time.

Got thoughts? Click the feedback button – your insights help us improve!