Easy Ship API v2022-03-23 Reference
Help sellers manage and ship Amazon Easy Ship orders.
Overview
The Selling Partner API for Easy Ship helps you build applications that help sellers manage and ship Amazon Easy Ship orders.
Your Easy Ship applications can:
-
Get available time slots for packages to be scheduled for delivery.
-
Schedule, reschedule, and cancel Easy Ship orders.
-
Print labels, invoices, and warranties.
See the Marketplace Support Table for the differences in Easy Ship operations by marketplace.
Version information
Version : 2022-03-23
Contact information
Contact : Selling Partner API Developer Support
Contact URL : https://sellercentral.amazon.com/gp/mws/contactus.html
License information
License : Apache License 2.0
License URL : http://www.apache.org/licenses/LICENSE-2.0
URI scheme
Host : sellingpartnerapi-na.amazon.com
Schemes : HTTPS
Consumes
application/json
Produces
application/json
Operations
listHandoverSlots
getScheduledPackage
createScheduledPackage
updateScheduledPackages
createScheduledPackageBulk
Paths
POST /easyShip/2022-03-23/timeSlot
Operation: listHandoverSlots
Description
Returns time slots available for Easy Ship orders to be scheduled based on the package weight and dimensions that the seller specifies.
This operation is available for scheduled and unscheduled orders based on marketplace support. See Get Time Slots in the Marketplace Support Table.
This operation can return time slots that have either pickup or drop-off handover methods - see Supported Handover Methods in the Marketplace Support Table.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 1 | 5 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Body | ListHandoverSlotsRequest optional | The request schema for the listHandoverSlots operation. | ListHandoverSlotsRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | ListHandoverSlotsResponse |
For error status codes, descriptions and schemas, see Error responses and schemas.
GET /easyShip/2022-03-23/package
Operation: getScheduledPackage
Description
Returns information about a package, including dimensions, weight, time slot information for handover, invoice and item information, and status.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 1 | 5 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Query | amazonOrderId required | An Amazon-defined order identifier. Identifies the order that the seller wants to deliver using Amazon Easy Ship. minLength : 1 maxLength : 255 | string |
| Query | marketplaceId required | An identifier for the marketplace in which the seller is selling. minLength : 1 maxLength : 255 | string |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | Package |
For error status codes, descriptions and schemas, see Error responses and schemas.
POST /easyShip/2022-03-23/package
Operation: createScheduledPackage
Description
Schedules an Easy Ship order and returns the scheduled package information.
This operation does the following:
-
Specifies the time slot and handover method for the order to be scheduled for delivery.
-
Updates the Easy Ship order status.
-
Generates a shipping label and an invoice. Calling
createScheduledPackagealso generates a warranty document if you specify aSerialNumbervalue. To get these documents, see How to get invoice, shipping label, and warranty documents. -
Shows the status of Easy Ship orders when you call the
getOrdersoperation of the Selling Partner API for Orders and examine theEasyShipShipmentStatusproperty in the response body.
See the Shipping Label, Invoice, and Warranty columns in the Marketplace Support Table to see which documents are supported in each marketplace.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 1 | 5 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Body | CreateScheduledPackageRequest required | The request schema for the createScheduledPackage operation. | CreateScheduledPackageRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success. Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | Package |
For error status codes, descriptions and schemas, see Error responses and schemas.
PATCH /easyShip/2022-03-23/package
Operation: updateScheduledPackages
Description
Updates the time slot for handing over the package indicated by the specified scheduledPackageId. You can get the new slotId value for the time slot by calling the listHandoverSlots operation before making another patch call.
See the Update Package column in the Marketplace Support Table to see which marketplaces this operation is supported in.
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 1 | 5 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Body | UpdateScheduledPackagesRequest optional | The request schema for the updateScheduledPackages operation. | UpdateScheduledPackagesRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | Packages |
For error status codes, descriptions and schemas, see Error responses and schemas.
POST /easyShip/2022-03-23/packages/bulk
Operation: createScheduledPackageBulk
Description
This operation automatically schedules a time slot for all the amazonOrderIds given as input, generating the associated shipping labels, along with other compliance documents according to the marketplace (refer to the marketplace document support table).
Developers calling this operation may optionally assign a packageDetails object, allowing them to input a preferred time slot for each order in ther request. In this case, Amazon will try to schedule the respective packages using their optional settings. On the other hand, i.e., if the time slot is not provided, Amazon will then pick the earliest time slot possible.
Regarding the shipping label's file format, external developers are able to choose between PDF or ZPL, and Amazon will create the label accordingly.
This operation returns an array composed of the scheduled packages, and a short-lived URL pointing to a zip file containing the generated shipping labels and the other documents enabled for your marketplace. If at least an order couldn't be scheduled, then Amazon adds the rejectedOrders list into the response, which contains an entry for each order we couldn't process. Each entry is composed of an error message describing the reason of the failure, so that sellers can take action.
The table below displays the supported request and burst maximum rates:
Usage Plan:
| Rate (requests per second) | Burst |
|---|---|
| 1 | 5 |
The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The table above indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may see higher rate and burst values than those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API.
Parameters
| Type | Name | Description | Schema |
|---|---|---|---|
| Body | CreateScheduledPackagesRequest required | The request schema for the createScheduledPackageBulk operation. | CreateScheduledPackagesRequest |
Responses
| HTTP Code | Description | Schema |
|---|---|---|
| 200 | Success Headers : x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation. x-amzn-RequestId (string) : Unique request reference identifier. | CreateScheduledPackagesResponse |
For error status codes, descriptions and schemas, see Error responses and schemas.
Error Responses and Schemas
This table contains HTTP status codes and associated information for error responses.
| HTTP Code | Description | Schema |
|---|---|---|
| 400 | Request has missing or invalid parameters and cannot be parsed. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 401 | The request's Authorization header is not formatted correctly or does not contain a valid token. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 403 | Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 404 | The resource specified does not exist. Headers: x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 413 | The request size exceeded the maximum accepted size. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 415 | The request payload is in an unsupported format. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 429 | The frequency of requests was greater than allowed. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 500 | An unexpected condition occurred that prevented the server from fulfilling the request. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 503 | Temporary overloading or maintenance of the server. Headers: x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
Definitions
PackageIdentifier
Optional seller-created identifier that is printed on the shipping label to help the seller identify the package.
Type : string
PackageStatus
The status of the package.
Type : enum
| Value | Description |
|---|---|
| ReadyForPickup | The package is ready for pickup. |
| PickedUp | The package has been picked up. |
| AtOriginFC | The package is at its origin fulfillment center. |
| AtDestinationFC | The package is at its destination fulfillment center. |
| Delivered | The package has been delivered. |
| Rejected | The package has been rejected. |
| Undeliverable | The package is not deliverable. |
| ReturnedToSeller | The package has been returned to the seller. |
| LostInTransit | The package has been lost in transit. |
| LabelCanceled | The package's label has been canceled. |
| DamagedInTransit | The package has been damaged in transit. |
| OutForDelivery | The package is out for delivery. |
PackageId
An Amazon-defined identifier for the scheduled package.
Type : string
TrackingDetails
Representation of tracking metadata.
| Name | Description | Schema |
|---|---|---|
| trackingId optional | The tracking identifier for the scheduled package. | String |
HandoverMethod
Identifies the method by which a seller will hand a package over to Amazon Logistics.
Type : enum
| Value | Description |
|---|---|
| Pickup | An Amazon Logistics carrier will pickup the package(s) from the seller's pickup address. |
| Dropoff | Seller will need to drop off the package(s) to a designated location. |
OrderScheduleDetails
This object allows users to specify an order to be scheduled. Only the amazonOrderId is required.
| Name | Description | Schema |
|---|---|---|
| amazonOrderId required | An Amazon-defined order identifier. Identifies the order that the seller wants to deliver using Amazon Easy Ship. | AmazonOrderId |
| packageDetails optional | Package details. Includes packageItems, packageTimeSlot, and packageIdentifier. | PackageDetails |
AmazonOrderId
An Amazon-defined order identifier. Identifies the order that the seller wants to deliver using Amazon Easy Ship.
Type : string
Dimension
The numerical value of the specified dimension.
Type : number (float)
Minimum : 0.01
Dimensions
The dimensions of the scheduled package.
| Name | Description | Schema |
|---|---|---|
| length optional | The length dimension. | Dimension |
| width optional | The width dimension. | Dimension |
| height optional | The height dimension. | Dimension |
| unit optional | The unit of measurement used to measure the length. | UnitOfLength |
| identifier optional | Identifier for custom package dimensions. | String |
ListHandoverSlotsRequest
The request schema for the listHandoverSlots operation.
| Name | Description | Schema |
|---|---|---|
| marketplaceId required | A string of up to 255 characters. | String |
| amazonOrderId required | An Amazon-defined order identifier. Identifies the order that the seller wants to deliver using Amazon Easy Ship. | AmazonOrderId |
| packageDimensions required | The dimensions of the scheduled package. | Dimensions |
| packageWeight required | The weight of the scheduled package | Weight |
ListHandoverSlotsResponse
The response schema for the listHandoverSlots operation.
| Name | Description | Schema |
|---|---|---|
| amazonOrderId required | An Amazon-defined order identifier. Identifies the order that the seller wants to deliver using Amazon Easy Ship. | AmazonOrderId |
| timeSlots required | A list of time slots. | TimeSlots |
InvoiceData
Invoice number and date.
Item
Item identifier and serial number information.
| Name | Description | Schema |
|---|---|---|
| orderItemId optional | The Amazon-defined order item identifier. | OrderItemId |
| orderItemSerialNumbers optional | A list of serial numbers for the items associated with the OrderItemId value. | OrderItemSerialNumbers |
Items
A list of items contained in the package.
Type : < Item > array
Max items : 500
OrderItemId
The Amazon-defined order item identifier.
Type : string
maxLength : 255
OrderItemSerialNumber
A serial number for an item associated with the OrderItemId value.
Type : string
maxLength : 255
OrderItemSerialNumbers
A list of serial numbers for the items associated with the OrderItemId value.
Type : < OrderItemSerialNumber > array
Max items : 100
Package
This object contains all the details of the scheduled Easy Ship package.
| Name | Description | Schema |
|---|---|---|
| scheduledPackageId required | Identifies the scheduled package to be updated. | ScheduledPackageId |
| packageDimensions required | The dimensions of the scheduled package. | Dimensions |
| packageWeight required | The weight of the scheduled package | Weight |
| packageItems optional | A list of items contained in the package. | Items |
| packageTimeSlot required | A time window to hand over an Easy Ship package to Amazon Logistics. | TimeSlot |
| packageIdentifier optional | Optional seller-created identifier that is printed on the shipping label to help the seller identify the package. | PackageIdentifier |
| invoice optional | Invoice number and date. | InvoiceData |
| packageStatus optional | The status of the package. | PackageStatus |
| trackingDetails optional | Representation of tracking metadata. | TrackingDetails |
Packages
A list of packages.
| Name | Description | Schema |
|---|---|---|
| packages required | A list of packages. | < Package > array |
PackageDetails
Package details. Includes packageItems, packageTimeSlot, and packageIdentifier.
| Name | Description | Schema |
|---|---|---|
| packageItems optional | A list of items contained in the package. | Items |
| packageTimeSlot required | A time window to hand over an Easy Ship package to Amazon Logistics. | TimeSlot |
| packageIdentifier optional | Optional seller-created identifier that is printed on the shipping label to help the seller identify the package. | PackageIdentifier |
RejectedOrder
A order which we couldn't schedule on your behalf. It contains its id, and information on the error.
| Name | Description | Schema |
|---|---|---|
| amazonOrderId required | An Amazon-defined order identifier. Identifies the order that the seller wants to deliver using Amazon Easy Ship. | AmazonOrderId |
| error optional | Error response returned when the request is unsuccessful. | Error |
TimeSlot
A time window to hand over an Easy Ship package to Amazon Logistics.
| Name | Description | Schema |
|---|---|---|
| slotId required | An Amazon-defined identifier for a time slot. | String |
| startTime optional | The start date and time of the time slot. | DateTime |
| endTime optional | The end date and time of the time slot. | DateTime |
| handoverMethod optional | The method by which a seller will hand a package over to Amazon Logistics. | HandoverMethod |
TimeSlots
A list of time slots.
Type : < TimeSlot > array
Min items : 1
Max items : 500
ScheduledPackageId
Identifies the scheduled package to be updated.
| Name | Description | Schema |
|---|---|---|
| amazonOrderId required | An Amazon-defined order identifier. Identifies the order that the seller wants to deliver using Amazon Easy Ship. | AmazonOrderId |
| packageId optional | An Amazon-defined identifier for the scheduled package. | PackageId |
CreateScheduledPackageRequest
The request schema for the createScheduledPackage operation.
| Name | Description | Schema |
|---|---|---|
| amazonOrderId required | An Amazon-defined order identifier. Identifies the order that the seller wants to deliver using Amazon Easy Ship. | AmazonOrderId |
| marketplaceId required | A string of up to 255 characters. | String |
| packageDetails required | Package details. Includes packageItems, packageTimeSlot, and packageIdentifier. | PackageDetails |
UpdateScheduledPackagesRequest
The request schema for the updateScheduledPackages operation.
| Name | Description | Schema |
|---|---|---|
| marketplaceId required | A string of up to 255 characters. | String |
| updatePackageDetailsList required | A list of package update details. | UpdatePackageDetailsList |
UpdatePackageDetails
Request to update the time slot of a package.
| Name | Description | Schema |
|---|---|---|
| scheduledPackageId required | Identifies the scheduled package to be updated. | ScheduledPackageId |
| packageTimeSlot required | A time window to hand over an Easy Ship package to Amazon Logistics. | TimeSlot |
UpdatePackageDetailsList
A list of package update details.
Type : < UpdatePackageDetails > array
Min items : 1
Max items : 500
String
A string of up to 255 characters.
Type : string
minLength : 1
maxLength : 255
DateTime
A datetime value in ISO 8601 format.
Type : string (date-time)
UnitOfLength
The unit of measurement used to measure the length.
Type : enum
| Value | Description |
|---|---|
| Cm | Centimeters |
UnitOfWeight
The unit of measurement used to measure the weight.
Type : enum
| Value | Description |
|---|---|
| Grams | Grams |
| G | Grams |
CreateScheduledPackagesRequest
The request body for the POST /easyShip/2022-03-23/packages/bulk API.
| Name | Description | Schema |
|---|---|---|
| marketplaceId required | A string of up to 255 characters. | String |
| orderScheduleDetailsList required | An array allowing users to specify orders to be scheduled. | < OrderScheduleDetails > array |
| labelFormat required | The file format in which the shipping label will be created. | LabelFormat |
CreateScheduledPackagesResponse
The response schema for the bulk scheduling API. It returns by the bulk scheduling API containing an array of the scheduled packtages, an optional list of orders we couldn't schedule with the reason, and a pre-signed URL for a ZIP file containing the associated shipping labels plus the documents enabled for your marketplace.
| Name | Description | Schema |
|---|---|---|
| scheduledPackages optional | A list of packages. Refer to the Package object. | < Package > array |
| rejectedOrders optional | A list of orders we couldn't scheduled on your behalf. Each element contains the reason and details on the error. | < RejectedOrder > array |
| printableDocumentsUrl optional | A pre-signed URL for the zip document containing the shipping labels and the documents enabled for your marketplace. | URL |
URL
A pre-signed URL for the zip document containing the shipping labels and the documents enabled for your marketplace.
Type : string
LabelFormat
The file format in which the shipping label will be created.
Type : enum
| Value | Description |
|---|---|
| - | |
| ZPL | - |
Weight
The weight of the scheduled package
| Name | Description | Schema |
|---|---|---|
| value optional | The weight of the package. | WeightValue |
| unit optional | The unit of measurement used to measure the weight. | UnitOfWeight |
WeightValue
The weight of the package.
Type : number (float)
Minimum : 11.0
ErrorList
A list of error responses returned when a request is unsuccessful.
| Name | Description | Schema |
|---|---|---|
| errors required | A list of error responses returned when a request is unsuccessful. | < Error > array |
Error
Error response returned when the request is unsuccessful.
| Name | Description | Schema |
|---|---|---|
| code required | An error code that identifies the type of error that occurred. | string |
| message required | A message that describes the error condition. | string |
| details optional | Additional details that can help the caller understand or fix the issue. | string |
Updated 4 months ago