Vendor Direct Fulfillment Shipping API v2021-12-28 reference

AmazonSPAPI

# Overview

The Selling Partner API for Direct Fulfillment Shipping provides programmatic access to a direct fulfillment vendor's shipping data.

# Version information

Version : 2021-12-28

# Operations

getShippingLabels
submitShippingLabelRequest
getShippingLabel

# Paths

# getShippingLabels

GET /vendor/directFulfillment/shipping/2021-12-28/shippingLabels

# Description

Returns a list of shipping labels created during the time frame that you specify. You define that time frame using the createdAfter and createdBefore parameters. You must use both of these parameters. The date range to search must not be more than 7 days.

Usage Plan:

Rate (requests per second) Burst
10 10

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 then 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 Default
Query shipFromPartyId
optional
The vendor warehouseId for order fulfillment. If not specified, the result will contain orders for all warehouses. string -
Query limit
optional
The limit to the number of records returned.
Minimum : 1
Maximum : 100
integer -
Query createdAfter
required
Shipping labels that became available after this date and time will be included in the result. Must be in ISO-8601 date/time format. string (date-time) -
Query createdBefore
required
Shipping labels that became available before this date and time will be included in the result. Must be in ISO-8601 date/time format. string (date-time) -
Query sortOrder
optional
Sort ASC or DESC by order creation date. enum (SortOrder) "ASC"
Query nextToken
optional
Used for pagination when there are more ship labels than the specified result size limit. The token value is returned in the previous API call. 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.
ShippingLabelList

For error status codes, descriptions and schemas, see Error responses and schemas.

# submitShippingLabelRequest

POST /vendor/directFulfillment/shipping/2021-12-28/shippingLabels

# Description

Creates a shipping label for a purchase order and returns a transactionId for reference.

Usage Plan:

Rate (requests per second) Burst
10 10

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 then those shown here. For more information, see Usage Plans and Rate Limits in the Selling Partner API (opens new window).

# Parameters

Type Name Schema
Body body
required
SubmitShippingLabelsRequest

# Responses

HTTP Code Description Schema
202 Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
TransactionReference

For error status codes, descriptions and schemas, see Error responses and schemas.

# getShippingLabel

GET /vendor/directFulfillment/shipping/2021-12-28/shippingLabels/{purchaseOrderNumber}

# Description

Returns a shipping label for the purchaseOrderNumber that you specify.

Usage Plan:

Rate (requests per second) Burst
10 10

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 then 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
Path purchaseOrderNumber
required
The purchase order number for which you want to return the shipping label. It should be the same purchaseOrderNumber as received in the order. 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.
ShippingLabel

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.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
403 Indicates that 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 resource specified 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
413 The request size exceeded the maximum accepted size.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
415 The request payload is in an unsupported format.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
429 The frequency of requests was greater than allowed.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
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-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList
503 Temporary overloading or maintenance of the server.
Headers:
x-amzn-RateLimit-Limit (string):Your rate limit (requests per second) for this operation.
Note: For this status code, the rate limit header is deprecated and no longer returned.
x-amzn-RequestId (string):Unique request reference identifier.
ErrorList

# Definitions

# SubmitShippingLabelsRequest

Name Schema
shippingLabelRequests
optional
< ShippingLabelRequest > array

# ShippingLabelRequest

Name Description Schema
purchaseOrderNumber
required
Purchase order number of the order for which to create a shipping label.
Pattern : "^[a-zA-Z0-9]+$"
string
sellingParty
required
ID of the selling party or vendor. PartyIdentification
shipFromParty
required
Warehouse code of vendor. PartyIdentification
containers
optional
A list of the packages in this shipment. < Container > array

# PackedItem

Name Description Schema
itemSequenceNumber
required
Item Sequence Number for the item. This must be the same value as sent in the order for a given item. integer
buyerProductIdentifier
optional
Buyer's Standard Identification Number (ASIN) of an item. Either buyerProductIdentifier or vendorProductIdentifier is required. string
vendorProductIdentifier
optional
The vendor selected product identification of the item. Should be the same as was sent in the Purchase Order, like SKU Number. string
packedQuantity
required
Total item quantity packed in the container. ItemQuantity

# PartyIdentification

Name Description Schema
partyId
required
Assigned Identification for the party. string
address
optional
Identification of the party by address. Address
taxRegistrationDetails
optional
Tax registration details of the entity. < TaxRegistrationDetails > array

# TaxRegistrationDetails

Tax registration details of the entity.

Name Description Schema
taxRegistrationType
optional
Tax registration type for the entity. enum (TaxRegistrationType)
taxRegistrationNumber
required
Tax registration number for the party. For example, VAT ID. string
taxRegistrationAddress
optional
Address associated with the tax registration number. Address
taxRegistrationMessages
optional
Tax registration message that can be used for additional tax related details. string

# Address

Address of the party.

Name Description Schema
name
required
The name of the person, business or institution at that address. string
addressLine1
required
First line of the address. string
addressLine2
optional
Additional street address information, if required. string
addressLine3
optional
Additional street address information, if required. string
city
optional
The city where the person, business or institution is located. string
county
optional
The county where person, business or institution is located. string
district
optional
The district where person, business or institution is located. string
stateOrRegion
optional
The state or region where person, business or institution is located. string
postalCode
optional
The postal code of that address. It contains a series of letters or digits or both, sometimes including spaces or punctuation. string
countryCode
required
The two digit country code in ISO 3166-1 alpha-2 format. string
phone
optional
The phone number of the person, business or institution located at that address. string

# Dimensions

Physical dimensional measurements of a container.

Name Description Schema
length
required
The length of the container. Decimal
width
required
The width of the container. Decimal
height
required
The height of the container. Decimal
unitOfMeasure
required
The unit of measure for dimensions. enum (UnitOfMeasure)

# Weight

The weight.

Name Description Schema
unitOfMeasure
required
The unit of measurement. enum (UnitOfMeasure)
value
required
The measurement value. Decimal

# Decimal

A decimal number with no loss of precision. Useful when precision loss is unacceptable, as with currencies. Follows RFC7159 for number representation.
Pattern : ^-?(0|([1-9]\\d*))(\\.\\d+)?([eE][+-]?\\d+)?$.

Type : string

# ItemQuantity

Details of item quantity.

Name Description Schema
amount
required
Quantity of units shipped for a specific item at a shipment level. If the item is present only in certain packages or pallets within the shipment, please provide this at the appropriate package or pallet level. integer
unitOfMeasure
required
Unit of measure for the shipped quantity. string

# ShippingLabelList

Name Schema
pagination
optional
Pagination
shippingLabels
optional
< ShippingLabel > array

# LabelData

Details of the shipment label.

Name Description Schema
packageIdentifier
optional
Identifier for the package. The first package will be 001, the second 002, and so on. This number is used as a reference to refer to this package from the pallet level. string
trackingNumber
optional
Package tracking identifier from the shipping carrier. string
shipMethod
optional
Ship method to be used for shipping the order. Amazon defines Ship Method Codes indicating shipping carrier and shipment service level. Ship Method Codes are case and format sensitive. The same ship method code should returned on the shipment confirmation. Note that the Ship Method Codes are vendor specific and will be provided to each vendor during the implementation. string
shipMethodName
optional
Shipping method name for internal reference. string
content
required
This field will contain the Base64encoded string of the shipment label content. string

# ShippingLabel

Name Description Schema
purchaseOrderNumber
required
This field will contain the Purchase Order Number for this order.
Pattern : "^[a-zA-Z0-9]+$"
string
sellingParty
required
ID of the selling party or vendor. PartyIdentification
shipFromParty
required
Warehouse code of vendor. PartyIdentification
labelFormat
required
Format of the label. enum (LabelFormat)
labelData
required
Provides the details of the packages in this shipment. < LabelData > array

# Pagination

Name Description Schema
nextToken
optional
A generated string used to pass information to your next request. If NextToken is returned, pass the value of NextToken to the next request. If NextToken is not returned, there are no more order items to return. string

# TransactionReference

Name Description Schema
transactionId
optional
GUID to identify this transaction. This value can be used with the Transaction Status API to return the status of this transaction. string

# 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

# Container

Name Description Schema
containerType
required
The type of container. enum (ContainerType)
containerIdentifier
required
The container identifier. string
trackingNumber
optional
The tracking number. string
manifestId
optional
The manifest identifier. string
manifestDate
optional
The date of the manifest. string
shipMethod
optional
The shipment method. string
scacCode
optional
SCAC code required for NA VOC vendors only. string
carrier
optional
Carrier required for EU VOC vendors only. string
containerSequenceNumber
optional
An integer that must be submitted for multi-box shipments only, where one item may come in separate packages. integer
dimensions
optional
Physical dimensional measurements of a container. Dimensions
weight
optional
The weight. Weight
packedItems
required
A list of packed items. < PackedItem > array

# LabelFormat

Format of the label.

Type : enum

Value Description
PNG Portable Network Graphics (png) format.
ZPL Zebra Programming Language (zpl) format.

# TaxRegistrationType

Tax registration type for the entity.

Type : enum

Value Description
VAT Value-added tax.
GST Goods and Services Tax (GST).

# ContainerType

The type of container.

Type : enum

Value Description
Carton Packing container type. Typically used for drinks or food.
Pallet A flat transport structure which supports goods in a stable fashion while being lifted by a forklift.

# SortOrder

Sort ASC or DESC by order creation date.

Type : enum

Value Description
ASC Sort in ascending order by order creation date.
DESC Sort in descending order by order creation date.

# UnitOfMeasure

Type : enum

For use with the definition(s): Weight The unit of measurement.

Value Description
KG Kilogram
LB Pounds (Libra for Latin).

For use with the definition(s): Dimensions The unit of measure for dimensions.

Value Description
IN Inches
CM Centimeters
Last Updated: 10/11/2022, 9:45:34 PM