Easy Ship API v2022-03-23 Use Case Guide
How to use the Easy Ship API.
API Version: v2022-03-23
What is the Easy Ship API?
The Selling Partner API for Easy Ship lets you build applications for sellers to manage and ship packages for Amazon Easy Ship orders.
Key Features
- Get available time slots.
- Schedule and reschedule Easy Ship packages for Easy Ship orders.
- Print shipping labels, invoices, and warranty documents.
Tutorial: Schedule an Easy Ship package
This tutorial serves as a guide on how to use the Easy Ship API to schedule a package for an Easy Ship order.
Step 1. Get available time slots
Call the listHandoverSlots
operation to get a list of available time slots for an unscheduled Easy Ship order. Make sure of the following:
- The specified Amazon Order Id should be an Easy Ship order and in an unshipped state.
- The request should include the desired weight and dimensions of the package.
Non Easy Ship orders and orders in Pending state will return an error response.
Request
Call the listHandoverSlots
operation.
Request example:
POST https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/timeSlot
{
"amazonOrderId": "933-1443575-9112638",
"marketplaceId": "A21TJRUUN4KGV",
"packageDimensions": {
"length": 20.0,
"width": 10.0,
"height": 12.0,
"unit": "Cm",
"identifier": "test"
},
"packageWeight": {
"value": 100.0,
"unit": "G"
}
}
Response
A successful response includes the list of available time slots. Each time slot will specify the method by which the seller will need to give the package to an Amazon carrier. Refer to supported handover methods for more details. Make sure to save the slotId
, startTime
, and endTime
of the desired slot for the next step.
Response example:
{
"amazonOrderId": "933-1443575-9112638",
"timeSlots": [
{
"handoverMethod": "Pickup",
"slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-09T23:30:00Z",
"endTime": "2022-03-10T02:00:00Z"
},
{
"handoverMethod": "Pickup",
"slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-10T02:00:00Z",
"endTime": "2022-03-10T04:30:00Z"
}
]
}
Step 2. Create an Easy Ship package
Call the createScheduledPackage
operation to create a package for an unscheduled Easy Ship order. Make sure of the following:
- The specified Amazon Order Id should be an Easy Ship order and in an unshipped state.
- The request should include the desired weight and dimensions of the package.
Non Easy Ship orders and orders in Pending state will return an error response.
Request
Call the createScheduledPackage
operation.
Request example:
POST https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/package
{
"amazonOrderId": "933-1443575-9112638",
"marketplaceId": "A21TJRUUN4KGV",
"packageDetails": {
"packageTimeSlot": {
"slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-09T23:30:00Z",
"endTime": "2022-03-10T02:00:00Z"
}
}
}
Response
A successful response includes the package's weight and dimensions, invoice details (if present), the selected time slot, and the status of the package.
Response example:
{
"packageDimensions": {
"identifier": "test",
"unit": "Cm",
"length": 20,
"width": 10,
"height": 12
},
"packageWeight": {
"unit": "G",
"value": 50
},
"invoice": {
"invoiceNumber": "IN-456",
"invoiceDate": "1.636404098172E9"
},
"scheduledPackageId": {
"amazonOrderId": "933-1443575-9112638",
"packageId": "b4be5116-98b1-6f20-a47b-03de178cfb4f"
},
"packageStatus": "ReadyForPickup",
"packageTimeSlot": {
"slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-09T23:30:00Z",
"endTime": "2022-03-10T02:00:00Z"
},
"trackingDetails": {
"trackingId": "2045079155"
}
}
Tutorial: Reschedule an Easy Ship package
This tutorial serves as a guide on how to use the Easy Ship API to reschedule a package for an Easy Ship order. We currently only allow a seller to update the selected time slot for an Easy Ship package. For both operations in this tutorial, the specified Amazon Order Id must have already been scheduled and the Easy Ship Package must be in a valid state. Refer to Tutorial: Check the status of an Easy Ship Package for more details.
Step 1. Get available time slots for rescheduling
Call the listHandoverSlots
operation to get a list of available time slots for a scheduled Easy Ship order.
Request
Call the listHandoverSlots
operation.
Request example:
POST https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/timeSlot
{
"amazonOrderId": "933-1443575-9112638",
"marketplaceId": "A21TJRUUN4KGV",
"packageDimensions": {
"length": 20.0,
"width": 10.0,
"height": 12.0,
"unit": "Cm",
"identifier": "test"
},
"packageWeight": {
"value": 100.0,
"unit": "G"
}
}
Response
A successful response includes the list of available time slots. Make sure to save the slotId
, startTime
, and endTime
of the desired slot for the next step.
Response example:
{
"amazonOrderId": "933-1443575-9112638",
"timeSlots": [
{
"handoverMethod": "Pickup",
"slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-09T23:30:00Z",
"endTime": "2022-03-10T02:00:00Z"
},
{
"handoverMethod": "Pickup",
"slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-10T02:00:00Z",
"endTime": "2022-03-10T04:30:00Z"
}
]
}
Step 2. Update an Easy Ship package
Call the updateScheduledPackages
operation to update the time slot for an Easy Ship package.
Request
Call the updateScheduledPackages
operation.
Request example:
PATCH https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/package
{
"marketplaceId":"A21TJRUUN4KGV",
"updatePackageDetailsList":[
{
"scheduledPackageId":{
"amazonOrderId":"933-1443575-9112638",
"packageId":"b4be5116-98b1-6f20-a47b-03de178cfb4f"
},
"packageTimeSlot":{
"slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-10T02:00:00Z",
"endTime": "2022-03-10T04:30:00Z"
}
}
]
}
Response
A successful response includes the package details and the updated time slot.
Response example:
{
"packages": [
{
"packageDimensions": {
"identifier": "test",
"unit": "Cm",
"length": 20,
"width": 10,
"height": 12
},
"packageWeight": {
"unit": "G",
"value": 50
},
"invoice": {
"invoiceNumber": "IN-456",
"invoiceDate": "1.636404098172E9"
},
"scheduledPackageId": {
"amazonOrderId": "933-1443575-9112638",
"packageId": "b4be5116-98b1-6f20-a47b-03de178cfb4f"
},
"packageStatus": "ReadyForPickup",
"packageTimeSlot": {
"slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-10T02:00:00Z",
"endTime": "2022-03-10T04:30:00Z"
},
"trackingDetails": {
"trackingId": "2045079155"
}
}
]
}
Tutorial: Check the status of an Easy Ship package
This tutorial serves as a guide on how to use the Easy Ship API to check the status of an Easy Ship package. This operation allows a seller to view the specified weight, dimensions, time slot, and other details of an Easy Ship package.
The status of a package is updated as events occur for the package. Examples of a few such events include
- A package is provided to an Amazon carrier.
- A package has been delivered to a buyer.
- A package has been cancelled.
- A package was lost in transit.
It is useful to check the current status of a package before rescheduling because packages cannot be rescheduled after they have been given to an Amazon carrier. Rescheduling operations will fail with an InvalidOrderState
code if it is attempted on a Easy Ship package in an invalid state. Refer to packageStatus
for all the different states of a package.
Step 1. Get an Easy Ship package
Call the getScheduledPackage
operation to get the details of an Easy Ship package.
Request
Call the getScheduledPackage
operation.
Request example:
GET https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/package?marketplaceId=A21TJRUUN4KGV&amazonOrderId=933-6451079-5067861
Response
A successful response includes the package details.
Response example:
{
"packageDimensions":{
"unit":"Cm",
"length":20,
"width":10,
"height":12
},
"packageWeight":{
"unit":"G",
"value":50
},
"invoice":{
"invoiceNumber":"IN-442"
},
"scheduledPackageId":{
"amazonOrderId":"933-6451079-5067861",
"packageId":"88be1771-923c-d581-5e29-e8a310916185"
},
"packageStatus":"ReadyForPickup",
"packageTimeSlot":{
"slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-10T02:00:00Z",
"endTime": "2022-03-10T04:30:00Z"
},
"trackingDetails": {
"trackingId": "2045079155"
}
}
How to handle order items that require serial numbers
Some items in an Amazon Easy Ship order require serial numbers so that Amazon can generate warranty documents for them. Use the getOrderItems
operation to find out which items require serial numbers.
Step 1. Get list of orders that require serial numbers
Call the getOrderItems
operation, specifying the Amazon Order ID for the order that you want to create a scheduled package for.
Amazon returns the items in order, marking the items that require a serial number with SerialNumberRequired
=true
.
Step 2. Schedule Easy Ship packages with serial numbers
Call the createScheduledPackage
operation using PackageItems
to specify serial numbers for all of the items marked SerialNumberRequired
=true
in Step 1. Don't specify serial numbers for items marked SerialNumberRequired
=false
.
Amazon generates warranty documents for the items that you specified serial numbers for. For information about getting the documents that Amazon generates when you create a scheduled package, refer to How to get invoice, shipping label, and warranty documents.
How to get shipping labels, invoice, and warranty documents
Amazon generates an invoice when a buyer places an Amazon Easy Ship order in India. When you call the CreateScheduledPackage
operation to schedule an Amazon Easy Ship time slot for the order, Amazon generates a shipping label. If you include serial numbers for the items that you specify in your call to CreateScheduledPackage
, Amazon also generates warranty documents for the items. This topic explains how to get invoices, shipping labels, and warranties for scheduled Amazon Easy Ship orders.
Step 1. Submit an Easy Ship Feed request
Submit a Feed request to request documents for the desired Easy Ship orders. After a Feed request has been successfully processed, you can download the processing report to get the report reference id. This can then be used in the next step to download the requested Easy Ship documents.
-
Follow the Tutorial: Submit a Feed to submit an Easy Ship feed. The tutorial explains all the steps from submitting the feed document to verifying the feed request has been completed successfully.
FeedContent.
UseEasyshipDocuments.xsd
to form the content of the feed document.FeedType.
SpecifyPOST_EASYSHIP_DOCUMENTS
when calling thecreateFeed
operation.ReportReferenceId.
If there are no errors in the Feed processing report, the value returned can be used in the next step.
Example of Easy Ship Feed document:
<?xml version="1.0" encoding="utf-8" ?> <AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="amzn-envelope.xsd"> <Header> <DocumentVersion>1.01</DocumentVersion> <MerchantIdentifier>ABCDEFG007V</MerchantIdentifier> </Header> <MessageType>EasyShipDocument</MessageType> <Message> <MessageID>1</MessageID> <EasyShipDocument> <AmazonOrderID>933-6451079-5067861</AmazonOrderID> <DocumentType>ShippingLabel</DocumentType> <DocumentType>Invoice</DocumentType> <DocumentType>Warranty</DocumentType> </EasyShipDocument> </Message> </AmazonEnvelope>
Example of Easy Ship Feed processing report:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <EasyShipProcessingReport> <FeedSubmissionID>98765432100</FeedSubmissionID> <MessagesProcessed>1</MessagesProcessed> <MessagesSuccessful>1</MessagesSuccessful> <MessagesWithError>0</MessagesWithError> <DocumentReportReferenceID>123456789000</DocumentReportReferenceID> </EasyShipProcessingReport>
Step 2. Get the PDF
Get a PDF that contains the invoice, shipping label, and warranty (if available) documents for the Amazon Easy Ship order.
-
Call the
getReport
operation. When specifying thereportId
parameter, use theReportReferenceId
value from Step 1. Submit an Easy Ship Feed Request.The operation returns a
reportDocumentId
value that you can pass into thegetReportDocument
operation in the following step. -
Call the
getReportDocument
operation, specifying thereportDocumentId
from the previous step. Refer to Retrieve a report for more details.
Marketplace support
Easy Ship operations are only available in select marketplaces and support for specific operations varies in each marketplace. Refer to the following table for marketplace supported operations.
Marketplace support table
Marketplace | Region | Supported Handover Methods | Get Time Slots | Create Package | Update Package | Get Package Status | Shipping Label | Invoice | Warranty |
---|---|---|---|---|---|---|---|---|---|
Mexico | NA | Pickup only | Unscheduled Orders only | Supported | Not Supported | Supported | Supported | Not Supported | Not Supported |
India | EU | Pickup only | Scheduled & Unscheduled Orders | Supported | Supported | Supported | Supported | Supported | Supported |
Turkey | EU | Pickup & Dropoff | Unscheduled Orders only | Supported | Not Supported | Supported | Supported | Not Supported | Not Supported |
Australia | FE | Pickup only | Unscheduled Orders only | Supported | Not Supported | Supported | Supported | Not Supported | Not Supported |
Singapore | FE | Pickup only | Unscheduled Orders only | Supported | Not Supported | Supported | Supported | Not Supported | Not Supported |
Updated about 1 month ago