purchaseShipment - Amazon SP API

Purchases a shipping service and returns purchase related details and documents.

Note: You must complete the purchase within 10 minutes of rate creation by the shipping service provider. If you make the request after the 10 minutes have expired, you will receive an error response with the error code equal to "TOKEN_EXPIRED". If you receive this error response, you must get the rates for the shipment again.

Usage Plan:

Rate (requests per second)	Burst
80	100

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.

Request

Header Params

x-amzn-IdempotencyKey

string

optional

A unique value which the server uses to recognize subsequent retries of the same request.

x-amzn-shipping-business-id

enum<string>

optional

Amazon shipping business to assume for this request. The default is AmazonShipping_UK.

Allowed values:

AmazonShipping_USAmazonShipping_INAmazonShipping_UKAmazonShipping_UAEAmazonShipping_SAAmazonShipping_EGAmazonShipping_ITAmazonShipping_ESAmazonShipping_FRAmazonShipping_JP

Body Params application/json

The payload schema for the purchaseShipment operation.

clientReferenceId

string

required

Client reference id.

<= 40 characters

shipTo

object (Address)

required

Shipping address that represents the origin or destination location.

Example:

{"addressLine1":"address_1","addressLine2":"address_2","addressLine3":"address_3","city":"Seattle","countryCode":"US","county":"Washington","district":"District1","name":"address_name","phoneNumber":"+14155552671","postalCode":"123456","stateOrRegion":"Washington"}

addressLine1

string

required

First line of the address text.

addressLine2

string

optional

Optional second line of the address text.

addressLine3

string

optional

Optional third line of the address text.

city

string

optional

Optional city where this address is located.

countryCode

string

required

Two-digit, ISO 3166-1 alpha-2 formatted country code where this address is located.

county

string

optional

Optional county where this address is located.

Example:

Washington

district

string

optional

Optional district where this address is located.

name

string

required

Name of the person, business, or institution at this address.

phoneNumber

string

optional

Optional E.164-formatted phone number for an available contact at this address.

Example:

+14155552671

postalCode

string

optional

Optional postal code where this address is located.

stateOrRegion

string

required

State or region where this address is located. Note that this is contextual to the specified country code.

shipFrom

object (Address)

required

Shipping address that represents the origin or destination location.

Example:

shipDate

string <date-time>

optional

The start date and time. This defaults to the current date and time.

serviceType

enum<string>

required

The type of shipping service that will be used for the service offering.

Allowed values:

Amazon Shipping GroundAmazon Shipping StandardAmazon Shipping Premium

containers

array[object (Container) {6}]

required

A list of container.

containerType

enum<string>

optional

The type of physical container being used. (always 'PACKAGE')

Allowed value:

PACKAGE

containerReferenceId

string

required

An identifier for the container. This must be unique within all the containers in the same shipment.

<= 40 characters

value

object (Currency)

required

The type and amount of currency.

dimensions

object (Dimensions)

required

Dimensions of an Amazon catalog item or item in its packaging.

items

array[object (ContainerItem) {4}]

required

A list of the items in the container.

weight

object (Weight)

required

The weight of the scheduled package

labelSpecification

object (LabelSpecification)

required

The label specification info.

labelFormat

enum<string>

required

The format of the label. Enum of PNG only for now.

Allowed value:

PNG

labelStockSize

enum<string>

required

The label stock size specification in length and height. Enum of 4x6 only for now.

Allowed value:

4x6

Example

{
    "clientReferenceId": "string",
    "shipTo": {
        "addressLine1": "address_1",
        "addressLine2": "address_2",
        "addressLine3": "address_3",
        "city": "Seattle",
        "countryCode": "US",
        "county": "Washington",
        "district": "District1",
        "name": "address_name",
        "phoneNumber": "+14155552671",
        "postalCode": "123456",
        "stateOrRegion": "Washington"
    },
    "shipFrom": {
        "addressLine1": "address_1",
        "addressLine2": "address_2",
        "addressLine3": "address_3",
        "city": "Seattle",
        "countryCode": "US",
        "county": "Washington",
        "district": "District1",
        "name": "address_name",
        "phoneNumber": "+14155552671",
        "postalCode": "123456",
        "stateOrRegion": "Washington"
    },
    "shipDate": "2019-08-24T14:15:22Z",
    "serviceType": "Amazon Shipping Ground",
    "containers": [
        {
            "containerType": "PACKAGE",
            "containerReferenceId": "string",
            "value": {
                "amount": 0,
                "code": "str"
            },
            "dimensions": {
                "height": {
                    "unit": "string",
                    "value": 0
                },
                "length": {
                    "unit": "string",
                    "value": 0
                },
                "weight": {
                    "unit": "string",
                    "value": 0
                },
                "width": {
                    "unit": "string",
                    "value": 0
                }
            },
            "items": [
                {
                    "quantity": 0,
                    "unitPrice": {
                        "amount": 0,
                        "code": "str"
                    },
                    "unitWeight": {
                        "value": 11,
                        "unit": "Grams"
                    },
                    "title": "string"
                }
            ],
            "weight": {
                "value": 11,
                "unit": "Grams"
            }
        }
    ],
    "labelSpecification": {
        "labelFormat": "PNG",
        "labelStockSize": "4x6"
    }
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://sandbox.sellingpartnerapi-na.amazon.com/shipping/v2/shipments' \
--header 'Content-Type: application/json' \
--data-raw '{
    "clientReferenceId": "string",
    "shipTo": {
        "addressLine1": "address_1",
        "addressLine2": "address_2",
        "addressLine3": "address_3",
        "city": "Seattle",
        "countryCode": "US",
        "county": "Washington",
        "district": "District1",
        "name": "address_name",
        "phoneNumber": "+14155552671",
        "postalCode": "123456",
        "stateOrRegion": "Washington"
    },
    "shipFrom": {
        "addressLine1": "address_1",
        "addressLine2": "address_2",
        "addressLine3": "address_3",
        "city": "Seattle",
        "countryCode": "US",
        "county": "Washington",
        "district": "District1",
        "name": "address_name",
        "phoneNumber": "+14155552671",
        "postalCode": "123456",
        "stateOrRegion": "Washington"
    },
    "shipDate": "2019-08-24T14:15:22Z",
    "serviceType": "Amazon Shipping Ground",
    "containers": [
        {
            "containerType": "PACKAGE",
            "containerReferenceId": "string",
            "value": {
                "amount": 0,
                "code": "str"
            },
            "dimensions": {
                "height": {
                    "unit": "string",
                    "value": 0
                },
                "length": {
                    "unit": "string",
                    "value": 0
                },
                "weight": {
                    "unit": "string",
                    "value": 0
                },
                "width": {
                    "unit": "string",
                    "value": 0
                }
            },
            "items": [
                {
                    "quantity": 0,
                    "unitPrice": {
                        "amount": 0,
                        "code": "str"
                    },
                    "unitWeight": {
                        "value": 11,
                        "unit": "Grams"
                    },
                    "title": "string"
                }
            ],
            "weight": {
                "value": 11,
                "unit": "Grams"
            }
        }
    ],
    "labelSpecification": {
        "labelFormat": "PNG",
        "labelStockSize": "4x6"
    }
}'

Responses

🟢200OK

application/json

Success.

Headers

x-amzn-RateLimit-Limit

string

optional

Your rate limit (requests per second) for this operation.

x-amzn-RequestId

string

optional

Unique request reference identifier.

Body

The response schema for the purchaseShipment operation.

payload

object (PurchaseShipmentResult)

optional

The payload schema for the purchaseShipment operation.

shipmentId

string

required

An Amazon-defined shipment identifier.

serviceRate

object (ServiceRate)

required

The specific rate for a shipping service, or null if no service available.

labelResults

array[object (LabelResult) {3}]

required

A list of label results

errors

array[object (Error) {3}]

optional

A list of error responses that are returned when a request is unsuccessful.

code

string

required

An error code that identifies the type of error that occurred.

message

string

required

A message that describes the error condition.

details

string

optional

Additional details that can help the caller understand or fix the issue.

Example

{
    "shipmentId": "87852211788104",
    "packageDocumentDetails": [
        {
            "packageClientReferenceId": "abcd",
            "packageDocuments": [
                {
                    "type": "LABEL",
                    "format": "PNG",
                    "contents": "sdioadaiosfhdodsaiufhouafhoudfhdouahfac=="
                }
            ],
            "trackingId": 1578648261977
        }
    ],
    "promise": {
        "pickupWindow": {
            "start": "2019-12-11T07:09:05.513Z",
            "end": "2019-12-11T09:09:05.513Z"
        },
        "deliveryWindow": {
            "start": "2019-12-13T07:09:05.513Z",
            "end": "2019-12-13T09:09:05.513Z"
        }
    }
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🟠413413

🟠415415

🟠429429

🔴500Server Error

🔴503Service Unavailable