logistics APIv1_beta.0.0

createFromShippingQuote

POST
/shipment/create_from_shipping_quote
This method creates a "shipment" based on the shippingQuoteId and rateId values supplied in the request. The rate identified by the rateId value specifies the carrier and service for the package shipment, and the rate ID must be contained in the shipping quote identified by the shippingQuoteId value. Call createShippingQuote to retrieve a set of live shipping rates.

When you create a shipment, eBay generates a shipping label that you can download and use to ship your package.

In a createFromShippingQuote request, sellers can include a list of shipping options they want to add to the base service quoted in the selected rate. The list of available shipping options is specific to each quoted rate and if available, the options are listed in the rate container of the of the shipping quote.

In addition to a configurable return-to location and other details about the shipment, the response to this method includes:
  • The shipping carrier and service to be used for the package shipment
  • A list of selected shipping options, if any
  • The shipment tracking number
  • The total shipping cost (the sum cost of the base shipping service and any added options)
When you create a shipment, your billing agreement account is charged the sum of the baseShippingCost and the total cost of any additional shipping options you might have selected. Use the URL returned in labelDownloadUrl field, or call downloadLabelFile with the shipmentId value from the response, to download a shipping label for your package.

Important! Sellers must set up their payment method with eBay before they can use this method to create a shipment and the associated shipping label.

Input

Resource URI (production)

POST https://api.ebay.com/sell/logistics/v1_beta/shipment/create_from_shipping_quote

URI parameters

HTTP request headers

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

OAuth scope

This request requires an access token created with the authorization code grant flow, using one scope from the following list:

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

See OAuth access tokens for more information.

Input container/fieldTypeDescription
additionalOptionsarray of AdditionalOptionSupply a list of one or more shipping options that the seller wants to purchase for this shipment.

The baseShippingCost field that's associated with the selected shipping rate is the cost of the base service offered in the rate. In addition to the base service, sellers can add additional shipping services to the base service. Shipping options include things such as shipping insurance or a recipient's signature upon delivery. The cost of any added services is summed with the base shipping cost to determine the final cost for the shipment. All options added to the shipment must be chosen from the set of shipping options offered with the selected rate.

Occurrence: Optional

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

Occurrence: Optional

additionalOptions.additionalCost.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Occurrence: Optional

additionalOptions.additionalCost.valuestringThe value of the monetary amount in the specified currency.

Occurrence: Optional

additionalOptions.optionTypestringThe 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: Optional

labelCustomMessagestringOptional text to be printed on the shipping label if the selected shipping carrier supports custom messages on their labels.

Occurrence: Optional

labelSizestringThe seller's desired label size. Any supplied value is applied only if the shipping carrier supports multiple label sizes, otherwise the carrier's default label size is used.
4"x6"

Occurrence: Optional

rateIdstringThe eBay-assigned ID of the shipping rate that the seller selected for the shipment. This value is generated by a call to createShippingQuote and is returned in the rates.rateId field.

Occurrence: Required

returnToContactThe optional return address and contact details for the shipment. The return address is printed on the shipping label. If not specified, the return address defaults to the shipFrom address returned in shipping quote.

Occurrence: Optional

returnTo.companyNamestringThe company name with which the contact is associated.

Occurrence: Optional

returnTo.contactAddressContactAddressThe details of the contact's geographical address.

Occurrence: Required

returnTo.contactAddress.addressLine1stringThe first line of the street address.

Occurrence: Required

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

Occurrence: Optional

returnTo.contactAddress.citystringThe city in which the address is located.

Occurrence: Optional

returnTo.contactAddress.countryCodeCountryCodeEnumThe country of the address, represented as two-letter ISO 3166-1 Alpha-2 country code. For example, US represents the United States and DE represents Germany.

Occurrence: Required

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

Occurrence: Required

returnTo.contactAddress.postalCodestringThe postal code of the address.

Occurrence: Required

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

Occurrence: Optional

returnTo.fullNamestringThe contact's full name.

Occurrence: Required

returnTo.primaryPhonePhoneNumberThe contact's primary telephone number.

Occurrence: Optional

returnTo.primaryPhone.phoneNumberstringA telephone number.

Occurrence: Required

shippingQuoteIdstringThe unique eBay-assigned ID of the shipping quote that was generated by a call to createShippingQuote.

Occurrence: Required

Output

HTTP response headers

{ /* Shipment */
"orders" : [
{ /* Order */ }
],
}
Output container/fieldTypeDescription
cancellationShipmentCancellationCancellation status for the package, if one exists.

Occurrence: Conditional

cancellation.cancellationRequestedDatestringThe time and date the request was made to cancel the shipment, formatted as an ISO 8601 UTC string.

Occurrence: Conditional

cancellation.cancellationStatusShipmentCancellationStatusEnumThis enum specifies the current cancellation status of a shipment, if a cancellation request has been made.

Occurrence: Conditional

creationDatestringThe date and time the shipment was created, formatted as an ISO 8601 UTC string.

Format: YYYY-MM-DDTHH:MM:SS.SSSZ
Example: 2018-08-06T01:00:00.000Z

Occurrence: Conditional

labelCustomMessagestringIf supported by the selected shipping carrier, this field can contain optional seller text to be printed on the shipping label.

Occurrence: Conditional

labelDownloadUrlstringThe direct URL the seller can use to download an image of the shipping label. By default, the file format is PDF. See downloadLabelFile for requesting different response file formats.

Occurrence: Conditional

labelSizestringThe seller's desired label size. The support for multi-sized labels is shipping-carrier specific and if the size requested in the creaateFromShippingQuote call matches a size the carrier supports, the value will be represented here in the shipment.

Currently, the only valid value is: 4"x6"

Occurrence: Conditional

ordersarray of OrderThis list value is optionally assigned by the seller. When present, each element in the returned list contains seller-assigned information about an order (such as an order number). Because a package can contain all or part of one or more orders, this field provides a way for sellers to identify the packages that contain specific orders.

Occurrence: Conditional

orders.channelstringThe e-commerce platform or environment where the order was created. Use the value EBAY to get the rates available for eBay orders.

Occurrence: Conditional

orders.orderIdstringThe unique ID of the order supplied by the channel of origin. For eBay orders, this would be the orderId.

Occurrence: Conditional

packageSpecificationPackageSpecificationThe weight and dimensions of the package.

Occurrence: Conditional

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

Occurrence: Conditional

packageSpecification.dimensions.heightstringThe numeric value of the height of the package.

Occurrence: Conditional

packageSpecification.dimensions.lengthstringThe numeric value of the length of the package.

Occurrence: Conditional

packageSpecification.dimensions.unitLengthUnitOfMeasureEnumThe unit of measure used to express the height, length, and width of the package.

Occurrence: Conditional

packageSpecification.dimensions.widthstringThe numeric value of the width of the package.

Occurrence: Conditional

packageSpecification.weightWeightDeclares the weight of the package.

Occurrence: Conditional

packageSpecification.weight.unitWeightUnitOfMeasureEnumThe unit of measure used to express the weight of the package.

Occurrence: Conditional

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

Occurrence: Conditional

ratePurchasedRateThe shipping rate that the seller has chosen to purchase for this shipment. Each rate, identified by a rateId, contains the offered base service, options, and shipping parameters that were selected for the package shipment.

Occurrence: Conditional

rate.additionalOptionsarray of AdditionalOptionAn list of additional, optional features that have been purchased for the shipment.

Occurrence: Conditional

rate.additionalOptions.additionalCostAmountThe monetary cost of the additional shipping option identified by the optionType field.

Occurrence: Conditional

rate.additionalOptions.additionalCost.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Occurrence: Conditional

rate.additionalOptions.additionalCost.valuestringThe value of the monetary amount in the specified currency.

Occurrence: Conditional

rate.additionalOptions.optionTypestringThe 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

rate.baseShippingCostAmountThe amount of the "base cost" for the shipment as set by the given carrier for the specified service. This cost excludes any addition costs accrued from the addition of any optional shipping options.

Occurrence: Conditional

rate.baseShippingCost.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Occurrence: Conditional

rate.baseShippingCost.valuestringThe value of the monetary amount in the specified currency.

Occurrence: Conditional

rate.destinationTimeZonestringThe time zone of the destination according to Time Zone Database. For example, "America/Los_Angeles".

Occurrence: Conditional

rate.maxEstimatedDeliveryDatestringA string value representing maximum (latest) estimated delivery time, formatted as an ISO 8601 UTC string.

Occurrence: Conditional

rate.minEstimatedDeliveryDatestringA string value representing minimum (earliest) estimated delivery time, formatted as an ISO 8601 UTC string.

Occurrence: Conditional

rate.pickupNetworksarray of stringA list of pickup networks compatible with the shipping service.

Occurrence: Conditional

rate.pickupSlotIdstringThis unique eBay-assigned ID value is returned only if the shipment has been configured for a scheduled pickup.

Occurrence: Conditional

rate.pickupTypePickupTypeEnumThe type of pickup or drop off configured for the shipment.

Occurrence: Conditional

rate.rateIdstringThe eBay-generated ID of the shipping rate that the seller has chosen to purchase for the shipment.

Occurrence: Conditional

rate.shippingCarrierCodestringThe ID code for the carrier that was selected for the package shipment.

Occurrence: Conditional

rate.shippingCarrierNamestringThe name of the shipping carrier.

Occurrence: Conditional

rate.shippingQuoteIdstringThe unique eBay-generated ID of the shipping quote from which the seller selected a shipping rate (rateId).

Occurrence: Conditional

rate.shippingServiceCodestringString ID code for the shipping service selected for the package shipment. This is a service that the shipping carrier supplies.

Occurrence: Conditional

rate.shippingServiceNamestringThe name of the shipping service.

Occurrence: Conditional

rate.totalShippingCostAmountThe total shipping cost, which is the sum cost of the base shipping cost and the cost of all the selected shipping options.

Occurrence: Conditional

rate.totalShippingCost.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount. The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Occurrence: Conditional

rate.totalShippingCost.valuestringThe value of the monetary amount in the specified currency.

Occurrence: Conditional

returnToContactThe address and contact details that should be used for item returns. Sellers have the option to define a return address that is different from their shipFrom address. If not specified, the return address defaults to the shipFrom address in the shipping quote.

Occurrence: Conditional

returnTo.companyNamestringThe company name with which the contact is associated.

Occurrence: Conditional

returnTo.contactAddressContactAddressThe details of the contact's geographical address.

Occurrence: Conditional

returnTo.contactAddress.addressLine1stringThe first line of the street address.

Occurrence: Always

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

Occurrence: Conditional

returnTo.contactAddress.citystringThe city in which the address is located.

Occurrence: Conditional

returnTo.contactAddress.countryCodeCountryCodeEnumThe country of the address, represented as two-letter ISO 3166-1 Alpha-2 country code. For example, US represents the United States and DE represents Germany.

Occurrence: Conditional

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

Occurrence: Conditional

returnTo.contactAddress.postalCodestringThe postal code of the address.

Occurrence: Always

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

Occurrence: Conditional

returnTo.fullNamestringThe contact's full name.

Occurrence: Conditional

returnTo.primaryPhonePhoneNumberThe contact's primary telephone number.

Occurrence: Conditional

returnTo.primaryPhone.phoneNumberstringA telephone number.

Occurrence: Conditional

shipFromContactThe address and contact details for the origin of the package shipment.

Occurrence: Conditional

shipFrom.companyNamestringThe company name with which the contact is associated.

Occurrence: Conditional

shipFrom.contactAddressContactAddressThe details of the contact's geographical address.

Occurrence: Conditional

shipFrom.contactAddress.addressLine1stringThe first line of the street address.

Occurrence: Always

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

Occurrence: Conditional

shipFrom.contactAddress.citystringThe city in which the address is located.

Occurrence: Conditional

shipFrom.contactAddress.countryCodeCountryCodeEnumThe country of the address, represented as two-letter ISO 3166-1 Alpha-2 country code. For example, US represents the United States and DE represents Germany.

Occurrence: Conditional

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

Occurrence: Conditional

shipFrom.contactAddress.postalCodestringThe postal code of the address.

Occurrence: Always

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

Occurrence: Conditional

shipFrom.fullNamestringThe contact's full name.

Occurrence: Conditional

shipFrom.primaryPhonePhoneNumberThe contact's primary telephone number.

Occurrence: Conditional

shipFrom.primaryPhone.phoneNumberstringA telephone number.

Occurrence: Conditional

shipmentIdstringThe unique eBay-assigned ID for the shipment. The ID is generated when the shipment is created by a call to createFromShippingQuote.

Occurrence: Conditional

shipmentTrackingNumberstringA unique carrier-assigned ID string that can be used to track the shipment.

Occurrence: Conditional

shipToContactThe address and contact details for the destination of the shipment.

Occurrence: Conditional

shipTo.companyNamestringThe company name with which the contact is associated.

Occurrence: Conditional

shipTo.contactAddressContactAddressThe details of the contact's geographical address.

Occurrence: Conditional

shipTo.contactAddress.addressLine1stringThe first line of the street address.

Occurrence: Always

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

Occurrence: Conditional

shipTo.contactAddress.citystringThe city in which the address is located.

Occurrence: Conditional

shipTo.contactAddress.countryCodeCountryCodeEnumThe country of the address, represented as two-letter ISO 3166-1 Alpha-2 country code. For example, US represents the United States and DE represents Germany.

Occurrence: Conditional

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

Occurrence: Conditional

shipTo.contactAddress.postalCodestringThe postal code of the address.

Occurrence: Always

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

Occurrence: Conditional

shipTo.fullNamestringThe contact's full name.

Occurrence: Conditional

shipTo.primaryPhonePhoneNumberThe contact's primary telephone number.

Occurrence: Conditional

shipTo.primaryPhone.phoneNumberstringA telephone number.

Occurrence: Conditional

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}.
90030API_LOGISTICSREQUESTPayment could not be completed.
90200API_LOGISTICSREQUESTThe quote has expired. Please request a new quote.
90210API_LOGISTICSREQUESTThe quote has already been purchased. Please request a new quote.

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 shipment from a shipping quote

This sample creates a "shipment" from a shipping quote.

When you create a shipment, the base cost of the shipment, plus the cost any selected additional shipping options, is billed against your eBay account of billing agreement you have set up. The shipment includes a shipping label that you can download, print, and use to ship the package described in the original shipping quote.

Input

To create a shipment, specify the shippingQuoteId and the rateId of the rate you want to use, as returned in the original shipping quote you generated for your package. Each shipping quote has a time window within which the rates are valid, you must create a shipment for a rate within the valid time frame.

When creating a shipment, you can specify that you want to purchase additional shipping options, as they are available in the rate you are selecting. You can also specify a return address, if it is different from the "From:" address you specified in the original shipping quote.
POST
https://api.ebay.com/sell/logistics/v1_beta/shipment/create_from_shipping_quote

Output

If the call is successful, the response contains the full details of the shipment you created, including the totalShippingCost, which is the base shipping cost listed in the selected rate, plus any added shipping options.