Easy Ship API v2022-03-23 reference

AmazonSPAPI

# 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 createScheduledPackage also generates a warranty document if you specify a SerialNumber value. 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 getOrders operation of the Selling Partner API for Orders and examine the EasyShipShipmentStatus property 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
Last Updated: 10/11/2022, 9:45:34 PM