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)
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
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.
| Header | Type | Description |
|---|---|---|
| Content-Type | string | This 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-ID | string | This 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 clipboardRequest fields
| Input container/field | Type | Description |
|---|---|---|
| orders | array of Order | In this array, the seller specifies one or more orders that will be shipped in the shipping package. Occurrence: Required |
| orders.channel | string | The marketplace where the order was created. Occurrence: Required |
| orders.orderId | string | The unique identifier of the order. The getOrders method of the Fulfillment API can be used to retrieve order IDs. Occurrence: Required |
| packageSpecification | PackageSpecification | Declares the weight and dimensions of the package. Occurrence: Required |
| packageSpecification.dimensions | Dimensions | Declares the height, length, width, and unit of measure for the package to be shipped. Occurrence: Optional |
| packageSpecification.dimensions.height | string | The numeric value of the height of the package. Occurrence: Optional |
| packageSpecification.dimensions.length | string | The numeric value of the length of the package. Occurrence: Optional |
| packageSpecification.dimensions.unit | LengthUnitOfMeasureEnum | The unit of measure used to express the height, length, and width of the package. Occurrence: Optional |
| packageSpecification.dimensions.width | string | The numeric value of the width of the package. Occurrence: Optional |
| packageSpecification.weight | Weight | Declares the weight of the package. Occurrence: Optional |
| packageSpecification.weight.unit | WeightUnitOfMeasureEnum | 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 Occurrence: Optional |
| packageSpecification.weight.value | string | The numeric value of the weight of the package, as measured by the value of unit. Occurrence: Optional |
| shipFrom | Contact | The address and contact details pertaining to the origin of the shipment. Occurrence: Required |
| shipFrom.companyName | string | The company name with which the contact is associated. Occurrence: Optional |
| shipFrom.contactAddress | ContactAddress | The details of the contact's geographical address. Occurrence: Required |
| shipFrom.contactAddress.addressLine1 | string | The first line of the street address. Occurrence: Required |
| shipFrom.contactAddress.addressLine2 | string | 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.city | string | The city in which the address is located. Occurrence: Optional |
| shipFrom.contactAddress.countryCode | CountryCodeEnum | The country of the address, represented as two-letter ISO 3166 country code. For example, Occurrence: Required |
| shipFrom.contactAddress.county | string | The county (not country) in which the address is located. Counties typically contain multiple cities or towns. Occurrence: Required |
| shipFrom.contactAddress.postalCode | string | The postal code of the address. Occurrence: Required |
| shipFrom.contactAddress.stateOrProvince | string | The state or province in which the address is located. States and provinces often contain multiple counties. Occurrence: Optional |
| shipFrom.fullName | string | The contact's full name. Occurrence: Required |
| shipFrom.primaryPhone | PhoneNumber | The contact's primary telephone number. Occurrence: Optional |
| shipFrom.primaryPhone.phoneNumber | string | A telephone number. Occurrence: Required |
| shipTo | Contact | The address and contact details pertaining to the shipment's destination. Occurrence: Required |
| shipTo.companyName | string | The company name with which the contact is associated. Occurrence: Optional |
| shipTo.contactAddress | ContactAddress | The details of the contact's geographical address. Occurrence: Required |
| shipTo.contactAddress.addressLine1 | string | The first line of the street address. Occurrence: Required |
| shipTo.contactAddress.addressLine2 | string | 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.city | string | The city in which the address is located. Occurrence: Optional |
| shipTo.contactAddress.countryCode | CountryCodeEnum | The country of the address, represented as two-letter ISO 3166 country code. For example, Occurrence: Required |
| shipTo.contactAddress.county | string | The county (not country) in which the address is located. Counties typically contain multiple cities or towns. Occurrence: Required |
| shipTo.contactAddress.postalCode | string | The postal code of the address. Occurrence: Required |
| shipTo.contactAddress.stateOrProvince | string | The state or province in which the address is located. States and provinces often contain multiple counties. Occurrence: Optional |
| shipTo.fullName | string | The contact's full name. Occurrence: Required |
| shipTo.primaryPhone | PhoneNumber | The contact's primary telephone number. Occurrence: Optional |
| shipTo.primaryPhone.phoneNumber | string | A telephone number. Occurrence: Required |
Output
HTTP response headers
This call has no response headers.
Response payload
Response fields
| Output container/field | Type | Description |
|---|---|---|
| creationDate | string | The date and time this quote was created, expressed as an ISO 8601 UTC string. Occurrence: Conditional |
| expirationDate | string | 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 |
| orders | array of Order | A list of one or more orders that will be shipped in the shipping package. Occurrence: Always |
| orders.channel | string | The marketplace where the order was created. Occurrence: Always |
| orders.orderId | string | The unique identifier of the order. The getOrders method of the Fulfillment API can be used to retrieve order IDs. Occurrence: Always |
| packageSpecification | PackageSpecification | The weight and dimensions of the package covered by this shipping quote. Occurrence: Conditional |
| packageSpecification.dimensions | Dimensions | Declares the height, length, width, and unit of measure for the package to be shipped. Occurrence: Conditional |
| packageSpecification.dimensions.height | string | The numeric value of the height of the package. Occurrence: Conditional |
| packageSpecification.dimensions.length | string | The numeric value of the length of the package. Occurrence: Conditional |
| packageSpecification.dimensions.unit | LengthUnitOfMeasureEnum | The unit of measure used to express the height, length, and width of the package. Occurrence: Conditional |
| packageSpecification.dimensions.width | string | The numeric value of the width of the package. Occurrence: Conditional |
| packageSpecification.weight | Weight | Declares the weight of the package. Occurrence: Conditional |
| packageSpecification.weight.unit | WeightUnitOfMeasureEnum | 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 Occurrence: Conditional |
| packageSpecification.weight.value | string | The numeric value of the weight of the package, as measured by the value of unit. Occurrence: Conditional |
| rates | array 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. Occurrence: Conditional |
| rates.additionalOptions | array 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 Occurrence: Conditional |
| rates.additionalOptions.additionalCost | Amount | The monetary cost of the additional shipping option identified by the optionType field. Occurrence: Conditional |
| rates.additionalOptions.additionalCost.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
| rates.additionalOptions.additionalCost.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
| rates.additionalOptions.optionType | string | 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.baseShippingCost | Amount | 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.currency | CurrencyCodeEnum | The base currency applied to the value field to establish a monetary amount. Occurrence: Conditional |
| rates.baseShippingCost.value | string | The monetary amount in the specified currency. Occurrence: Conditional |
| rates.destinationTimeZone | string | The name of the time zone region, as defined in the IANA Time Zone Database, to which the package is being shipped. Occurrence: Conditional |
| rates.maxEstimatedDeliveryDate | string | The latest stated date and time the shipment will be delivered at this rate. Occurrence: Conditional |
| rates.minEstimatedDeliveryDate | string | 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.pickupNetworks | array of string | A list of pickup networks compatible with the shipping service. Occurrence: Conditional |
| rates.pickupSlots | array of PickupSlot | A list of available pickup slots for the package. Occurrence: Conditional |
| rates.pickupSlots.pickupSlotEndTime | string | 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. Occurrence: Conditional |
| rates.pickupSlots.pickupSlotId | string | Seller-defined name for the pickup slot. Occurrence: Conditional |
| rates.pickupSlots.pickupSlotStartTime | string | The date and time the pickup slot begins, formatted as an ISO 8601 UTC string. Occurrence: Conditional |
| rates.pickupSlots.pickupSlotTimeZone | string | The time zone of the pickup location, returned as Time Zone Database ID (also know as an Olson time zone ID). Occurrence: Conditional |
| rates.pickupType | PickupTypeEnum | The type of pickup or drop-off service associated with the pickupSlots time frames. Occurrence: Conditional |
| rates.rateId | string | The unique eBay-assigned ID for this shipping rate. Occurrence: Conditional |
| rates.rateRecommendation | array of RateRecommendationEnum | A list of reasons this rate is recommended. Available values are:
Occurrence: Conditional |
| rates.shippingCarrierCode | string | The code name of the shipping carrier who will provide the service identified by shippingServiceCode. Occurrence: Conditional |
| rates.shippingCarrierName | string | The common name of the shipping carrier. Occurrence: Conditional |
| rates.shippingServiceCode | string | The code name of the shipping service to be provided by the carrier identified by shippingCarrierCode. Occurrence: Conditional |
| rates.shippingServiceName | string | The common name of the shipping service. Occurrence: Conditional |
| shipFrom | Contact | The address and contact details for the origin of the shipment. Occurrence: Conditional |
| shipFrom.companyName | string | The company name with which the contact is associated. Occurrence: Conditional |
| shipFrom.contactAddress | ContactAddress | The details of the contact's geographical address. Occurrence: Conditional |
| shipFrom.contactAddress.addressLine1 | string | The first line of the street address. Occurrence: Always |
| shipFrom.contactAddress.addressLine2 | string | 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.city | string | The city in which the address is located. Occurrence: Conditional |
| shipFrom.contactAddress.countryCode | CountryCodeEnum | The country of the address, represented as two-letter ISO 3166 country code. For example, Occurrence: Conditional |
| shipFrom.contactAddress.county | string | The county (not country) in which the address is located. Counties typically contain multiple cities or towns. Occurrence: Conditional |
| shipFrom.contactAddress.postalCode | string | The postal code of the address. Occurrence: Always |
| shipFrom.contactAddress.stateOrProvince | string | The state or province in which the address is located. States and provinces often contain multiple counties. Occurrence: Conditional |
| shipFrom.fullName | string | The contact's full name. Occurrence: Conditional |
| shipFrom.primaryPhone | PhoneNumber | The contact's primary telephone number. Occurrence: Conditional |
| shipFrom.primaryPhone.phoneNumber | string | A telephone number. Occurrence: Conditional |
| shippingQuoteId | string | 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 |
| shipTo | Contact | The address and contact details for the origin of the shipment. Occurrence: Conditional |
| shipTo.companyName | string | The company name with which the contact is associated. Occurrence: Conditional |
| shipTo.contactAddress | ContactAddress | The details of the contact's geographical address. Occurrence: Conditional |
| shipTo.contactAddress.addressLine1 | string | The first line of the street address. Occurrence: Always |
| shipTo.contactAddress.addressLine2 | string | 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.city | string | The city in which the address is located. Occurrence: Conditional |
| shipTo.contactAddress.countryCode | CountryCodeEnum | The country of the address, represented as two-letter ISO 3166 country code. For example, Occurrence: Conditional |
| shipTo.contactAddress.county | string | The county (not country) in which the address is located. Counties typically contain multiple cities or towns. Occurrence: Conditional |
| shipTo.contactAddress.postalCode | string | The postal code of the address. Occurrence: Always |
| shipTo.contactAddress.stateOrProvince | string | The state or province in which the address is located. States and provinces often contain multiple counties. Occurrence: Conditional |
| shipTo.fullName | string | The contact's full name. Occurrence: Conditional |
| shipTo.primaryPhone | PhoneNumber | The contact's primary telephone number. Occurrence: Conditional |
| shipTo.primaryPhone.phoneNumber | string | A telephone number. Occurrence: Conditional |
| warnings | array of ErrorDetailV3 | A list of any warnings triggered by the request. Occurrence: Conditional |
| warnings.category | string | The category type for this error or warning. It takes a string that can have one of three values:
Occurrence: Conditional |
| warnings.domain | string | Name of the domain containing the service or application. Occurrence: Conditional |
| warnings.errorId | integer | 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.inputRefIds | array 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.longMessage | string | An expanded version of message that should be around 100-200 characters long, but is not required to be such. Occurrence: Conditional |
| warnings.message | string | 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.outputRefIds | array of string | Identifies specific response elements associated with the error, if any. Path format is the same as Occurrence: Conditional |
| warnings.parameters | array of ErrorParameterV3 | This optional complex field type contains a list of one or more context-specific Occurrence: Conditional |
| warnings.parameters.name | string | Name of the entity that threw the error. Occurrence: Conditional |
| warnings.parameters.value | string | A description of the error. Occurrence: Conditional |
| warnings.subdomain | string | 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.
| Status | Meaning |
|---|---|
| 201 | Created |
| 400 | Bad Request |
| 409 | Conflict |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 90000 | API_LOGISTICS | APPLICATION | A system error has occurred. |
| 90010 | API_LOGISTICS | REQUEST | Missing field {fieldName}. |
| 90020 | API_LOGISTICS | REQUEST | Invalid field {fieldName}. |
| 90100 | API_LOGISTICS | REQUEST | No shipping services available for the provided addresses. |
| 90110 | API_LOGISTICS | REQUEST | The order {orderId} was not found on the platform. |
| 90120 | API_LOGISTICS | REQUEST | The package specification is incompatible with the destination. |
| 90130 | API_LOGISTICS | REQUEST | Order {orderId} is incompatible with our services. |
| 90133 | API_LOGISTICS | REQUEST | Maximum number of orders exceeded. Current limitation is 10. |
Warnings
For more on warnings, plus the codes of other common warnings, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 90135 | API_LOGISTICS | REQUEST | The 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.