Easy Ship API v2022-03-23 Use Case Guide

sfgoods AmazonSPAPI

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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 hand over the package to an Amazon carrier. See 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"
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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

1
2
3
4
5
6
7
8
9
10
11
12

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 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. See 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"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 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"
      }
    }
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 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 handed over 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 handed over 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. See 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"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

# 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 (opens new window) 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, see 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. Once 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 (opens new window) 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 (opens new window) to form the content of the feed document. See below for an example.
FeedType. Specify POST_EASYSHIP_DOCUMENTS (opens new window) when calling the createFeed (opens new window) operation.
ReportReferenceId. If there are no errors in the Feed processing report, the value returned may be used in the next step. See below for an example.

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>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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>

1
2
3
4
5
6
7
8

# 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 (opens new window) 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 (opens new window) operation in the following step.
Call the getReportDocument (opens new window) operation, specifying the reportDocumentId from the previous step. See How to Retrieve a Report (opens new window) for more details.

# Marketplace support

Easy Ship operations are only available in select marketplaces and support for specific operations varies in each marketplace. See the table below for supported operations by marketplace.

# 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

Catalog Items API v2022-04-01 FBA Inventory API

Amazon Selling Partner API - spapi.cyou

Choose mode