Easy Ship API v2022-03-23 reference

Help sellers manage and ship Amazon Easy Ship orders.

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

Contact information

Contact : Selling Partner API Test Support
Contact URL : https://github.com/amzn/amazon-marketplace-api-sdk/issues
Contact Email : [email protected]

License information

License : Amazon Software License
License URL : https://aws.amazon.com/asl/

URI scheme

Host : sellingpartnerapi-na.amazon.com
Schemes : HTTPS

Consumes

  • application/json

Produces

  • application/json

Operations

listHandoverSlots
getScheduledPackage
createScheduledPackage
updateScheduledPackages

Paths

POST /easyShip/2022-03-23/timeSlot

Operation: listHandoverSlots

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
15

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.

Parameters

TypeNameDescriptionSchema
BodyListHandoverSlotsRequest
optional
The request schema for the listHandoverSlots operation.ListHandoverSlotsRequest

Responses

HTTP CodeDescriptionSchema
200Success.
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.

GET /easyShip/2022-03-23/package

Operation: getScheduledPackage

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
15

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.

Parameters

TypeNameDescriptionSchema
QueryamazonOrderId
required
An Amazon-defined order identifier. Identifies the order that the seller wants to deliver using Amazon Easy Ship.
minLength : 1
maxLength : 255
string
QuerymarketplaceId
required
An identifier for the marketplace in which the seller is selling.
minLength : 1
maxLength : 255
string

Responses

HTTP CodeDescriptionSchema
200Success.
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.

POST /easyShip/2022-03-23/package

Operation: createScheduledPackage

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
15

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.

Parameters

TypeNameDescriptionSchema
BodyCreateScheduledPackageRequest
required
The request schema for the createScheduledPackage operation.CreateScheduledPackageRequest

Responses

HTTP CodeDescriptionSchema
200Success.
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.

PATCH /easyShip/2022-03-23/package

Operation: updateScheduledPackages

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
15

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.

Parameters

TypeNameDescriptionSchema
BodyUpdateScheduledPackagesRequest
optional
The request schema for the updateScheduledPackages operation.UpdateScheduledPackagesRequest

Responses

HTTP CodeDescriptionSchema
200Success
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 CodeDescriptionSchema
400Request 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
401The 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
403Indicates 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
404The 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
415The request payload is in an unsupported format.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
429The frequency of requests was greater than allowed.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
500An unexpected condition occurred that prevented the server from fulfilling the request.
Headers:
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
503Temporary 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

ValueDescription
ReadyForPickupThe package is ready for pickup.
PickedUpThe package has been picked up.
AtOriginFCThe package is at its origin fulfillment center.
AtDestinationFCThe package is at its destination fulfillment center.
DeliveredThe package has been delivered.
RejectedThe package has been rejected.
UndeliverableThe package is not deliverable.
ReturnedToSellerThe package has been returned to the seller.
LostInTransitThe package has been lost in transit.
LabelCanceledThe package's label has been canceled.
DamagedInTransitThe package has been damaged in transit.
OutForDeliveryThe package is out for delivery.

PackageId

An Amazon-defined identifier for the scheduled package.

Type : string

TrackingDetails

Representation of tracking metadata.

NameDescriptionSchema
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

ValueDescription
PickupAn Amazon Logistics carrier will pickup the package(s) from the seller's pickup address.
DropoffSeller 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.

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

NameDescriptionSchema
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 packageWeight

ListHandoverSlotsResponse

The response schema for the listHandoverSlots operation.

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

NameDescriptionSchema
invoiceNumber
required
The invoice number.String
invoiceDate
optional
The date that the invoice was generated.DateTime

Item

Item identifier and serial number information.

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

NameDescriptionSchema
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 packageWeight
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.

NameSchema
packages
required
< Package > array

PackageDetails

Package details. Includes packageItems, packageTimeSlot, and packageIdentifier.

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

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

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

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

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

NameDescriptionSchema
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

ValueDescription
CmCentimeters

UnitOfWeight

The unit of measurement used to measure the weight.

Type : enum

ValueDescription
GramsGrams
GGrams

Weight

The weight of the scheduled package

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

NameSchema
errors
required
< Error > array

Error

Error response returned when the request is unsuccessful.

NameDescriptionSchema
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