# 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
# Operations
listHandoverSlots
getScheduledPackage
createScheduledPackage
updateScheduledPackages
# Paths
# listHandoverSlots
POST /easyShip/2022-03-23/timeSlot
# 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 (opens new window).
# 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.
# getScheduledPackage
GET /easyShip/2022-03-23/package
# 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 (opens new window).
# 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.
# createScheduledPackage
POST /easyShip/2022-03-23/package
# 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 (opens new window).
# 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.
# updateScheduledPackages
PATCH /easyShip/2022-03-23/package
# 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 (opens new window).
# 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.
# 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-RateLimit-Limit (string):Your rate limit (requests per second) for this operation. x-amzn-RequestId (string):Unique request reference identifier. | ErrorList |
| 403 | Indicates 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 specified resource 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 |
| 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. |
# 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.
| Name | Description | Schema |
|---|---|---|
| invoiceNumber required | The invoice number. | String |
| invoiceDate optional | The date that the invoice was generated. | DateTime |
# 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
A package. This object contains all the details of the scheduled Easy Ship package including the package identifier, physical attributes such as dimensions and weight, selected time slot to handover the package to carrier, status of the package, and tracking/invoice details.
| 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 | Schema |
|---|---|
| packages required | < 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 |
# 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 |
# 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 | Schema |
|---|---|
| errors required | < 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 |