Easy Ship API v2022-03-23 Use Case Guide

API Version: v2022-03-23

What is the Easy Ship API?

You can use the Selling Partner API for Easy Ship to 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

Learn 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

Learn how to use the Easy Ship API to reschedule a package for an Easy Ship order. To use the listHandoverSlots and updateScheduledPackages operations, the Amazon order with the specified orderId must be scheduled and the Easy Ship Package must have a valid state. Refer to Tutorial: Check the status of an Easy Ship Package for more details.

⭐

Tip

Only a seller can update the selected time slot for an Easy Ship package.

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

Learn 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"
  }
}

Tutorial: 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. Learn how to use the Easy Ship API 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 Tutorial: Get invoice, shipping label, and warranty documents.

Tutorial: 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.

1. 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. Use EasyshipDocuments.xsd to form the content of the feed document.
   • FeedType. Specify POST_EASYSHIP_DOCUMENTS when calling the createFeed 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

   <?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

   <?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.

1. Call the getReport operation. When specifying the reportId parameter, use the ReportReferenceId value from Step 1. Submit an Easy Ship Feed Request.

   The operation returns a reportDocumentId value that you can pass into the getReportDocument operation in the following step.

2. Call the getReportDocument operation, specifying the reportDocumentId 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.