createShipment - Amazon SP API

Rate (requests per second)	Burst
2	2

Rate (requests per second)

Burst

Request

Body Params application/json

Request schema.

ShipmentRequestDetails

object (ShipmentRequestDetails)

required

Shipment information required for requesting shipping service offers or for creating a shipment.

AmazonOrderId

string

required

An Amazon-defined order identifier. Identifies the order that the seller wants to deliver using Amazon Easy Ship.

SellerOrderId

string

optional

A seller-defined order identifier.

<= 64 characters

ItemList

array[object (Item) {7}]

required

The list of items you want to include in a shipment.

ShipFromAddress

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

PackageDimensions

object (PackageDimensions)

required

Dimensions of the package.

Weight

object (Weight)

required

The weight of the scheduled package

MustArriveByDate

string <date-time>

optional

Date timestamp

ShipDate

string <date-time>

optional

Date timestamp

ShippingServiceOptions

object (ShippingServiceOptions)

required

Extra services provided by a carrier.

LabelCustomization

object (LabelCustomization)

optional

Custom text for shipping labels.

ShippingServiceId

string

required

An Amazon-defined shipping service identifier.

ShippingServiceOfferId

string

optional

Identifies a shipping service order made by a carrier.

HazmatType

enum<string>

optional

Hazardous materials options for a package. Consult the terms and conditions for each carrier for more information on hazardous materials.

Allowed values:

NoneLQHazmat

LabelFormatOption

object (LabelFormatOptionRequest)

optional

Whether to include a packing slip.

IncludePackingSlipWithLabel

boolean

optional

When true, include a packing slip with the label.

ShipmentLevelSellerInputsList

array[object (AdditionalSellerInputs) {2}]

optional

A list of additional seller input pairs required to purchase shipping.

AdditionalInputFieldName

string

required

The name of the additional input field.

AdditionalSellerInput

object (AdditionalSellerInput)

required

Additional information required to purchase shipping.

Example

{
    "ShipmentRequestDetails": {
        "AmazonOrderId": "string",
        "SellerOrderId": "string",
        "ItemList": [
            {
                "sku": "string",
                "summaries": [
                    {
                        "marketplaceId": "string",
                        "asin": "string",
                        "productType": "string",
                        "conditionType": "new_new",
                        "status": [
                            "BUYABLE"
                        ],
                        "fnSku": "string",
                        "itemName": "string",
                        "createdDate": "2019-08-24T14:15:22Z",
                        "lastUpdatedDate": "2019-08-24T14:15:22Z",
                        "mainImage": {
                            "link": "string",
                            "height": 0,
                            "width": 0
                        }
                    }
                ],
                "attributes": {},
                "issues": [
                    {
                        "code": "string",
                        "message": "string",
                        "severity": "ERROR",
                        "attributeNames": [
                            "string"
                        ],
                        "categories": [
                            "INVALID_ATTRIBUTE"
                        ],
                        "enforcements": {
                            "actions": [
                                {
                                    "action": "LISTING_SUPPRESSED"
                                }
                            ],
                            "exemption": {
                                "status": "EXEMPT",
                                "expiryDate": "2023-10-28T00:36:48.914Z"
                            }
                        }
                    }
                ],
                "offers": [
                    {
                        "marketplaceId": "string",
                        "offerType": "B2C",
                        "price": {
                            "currencyCode": "string",
                            "amount": "string"
                        },
                        "points": {
                            "pointsNumber": 0,
                            "pointsMonetaryValue": {
                                "currencyCode": "string",
                                "amount": 0
                            }
                        },
                        "audience": {
                            "value": "ALL",
                            "displayName": "string"
                        }
                    }
                ],
                "fulfillmentAvailability": [
                    {
                        "fulfillmentChannelCode": "string",
                        "quantity": 0
                    }
                ],
                "procurement": [
                    {
                        "costPrice": {
                            "currencyCode": "string",
                            "amount": "string"
                        }
                    }
                ]
            }
        ],
        "ShipFromAddress": {
            "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"
        },
        "PackageDimensions": {
            "height": 0,
            "length": 0,
            "unitOfMeasurement": "INCHES",
            "width": 0
        },
        "Weight": {
            "value": 11,
            "unit": "Grams"
        },
        "MustArriveByDate": "2019-08-24T14:15:22Z",
        "ShipDate": "2019-08-24T14:15:22Z",
        "ShippingServiceOptions": {
            "DeliveryExperience": "DeliveryConfirmationWithAdultSignature",
            "DeclaredValue": {
                "CurrencyCode": "str",
                "Amount": 0
            },
            "CarrierWillPickUp": true,
            "CarrierWillPickUpOption": "CarrierWillPickUp",
            "LabelFormat": "PDF"
        },
        "LabelCustomization": {
            "CustomTextForLabel": "string",
            "StandardIdForLabel": "AmazonOrderId"
        }
    },
    "ShippingServiceId": "string",
    "ShippingServiceOfferId": "string",
    "HazmatType": "None",
    "LabelFormatOption": {
        "IncludePackingSlipWithLabel": true
    },
    "ShipmentLevelSellerInputsList": [
        {
            "AdditionalInputFieldName": "string",
            "AdditionalSellerInput": {
                "DataType": "string",
                "ValueAsString": "string",
                "ValueAsBoolean": true,
                "ValueAsInteger": 0,
                "ValueAsTimestamp": "2019-08-24T14:15:22Z",
                "ValueAsAddress": {
                    "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"
                },
                "ValueAsWeight": {
                    "value": 11,
                    "unit": "Grams"
                },
                "ValueAsDimension": {
                    "value": 0,
                    "unit": "Cm"
                },
                "ValueAsCurrency": {
                    "CurrencyCode": "str",
                    "Amount": 0
                }
            }
        }
    ]
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://sandbox.sellingpartnerapi-na.amazon.com/mfn/v0/shipments' \
--header 'Content-Type: application/json' \
--data-raw '{
    "ShipmentRequestDetails": {
        "AmazonOrderId": "string",
        "SellerOrderId": "string",
        "ItemList": [
            {
                "sku": "string",
                "summaries": [
                    {
                        "marketplaceId": "string",
                        "asin": "string",
                        "productType": "string",
                        "conditionType": "new_new",
                        "status": [
                            "BUYABLE"
                        ],
                        "fnSku": "string",
                        "itemName": "string",
                        "createdDate": "2019-08-24T14:15:22Z",
                        "lastUpdatedDate": "2019-08-24T14:15:22Z",
                        "mainImage": {
                            "link": "string",
                            "height": 0,
                            "width": 0
                        }
                    }
                ],
                "attributes": {},
                "issues": [
                    {
                        "code": "string",
                        "message": "string",
                        "severity": "ERROR",
                        "attributeNames": [
                            "string"
                        ],
                        "categories": [
                            "INVALID_ATTRIBUTE"
                        ],
                        "enforcements": {
                            "actions": [
                                {
                                    "action": "LISTING_SUPPRESSED"
                                }
                            ],
                            "exemption": {
                                "status": "EXEMPT",
                                "expiryDate": "2023-10-28T00:36:48.914Z"
                            }
                        }
                    }
                ],
                "offers": [
                    {
                        "marketplaceId": "string",
                        "offerType": "B2C",
                        "price": {
                            "currencyCode": "string",
                            "amount": "string"
                        },
                        "points": {
                            "pointsNumber": 0,
                            "pointsMonetaryValue": {
                                "currencyCode": "string",
                                "amount": 0
                            }
                        },
                        "audience": {
                            "value": "ALL",
                            "displayName": "string"
                        }
                    }
                ],
                "fulfillmentAvailability": [
                    {
                        "fulfillmentChannelCode": "string",
                        "quantity": 0
                    }
                ],
                "procurement": [
                    {
                        "costPrice": {
                            "currencyCode": "string",
                            "amount": "string"
                        }
                    }
                ]
            }
        ],
        "ShipFromAddress": {
            "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"
        },
        "PackageDimensions": {
            "height": 0,
            "length": 0,
            "unitOfMeasurement": "INCHES",
            "width": 0
        },
        "Weight": {
            "value": 11,
            "unit": "Grams"
        },
        "MustArriveByDate": "2019-08-24T14:15:22Z",
        "ShipDate": "2019-08-24T14:15:22Z",
        "ShippingServiceOptions": {
            "DeliveryExperience": "DeliveryConfirmationWithAdultSignature",
            "DeclaredValue": {
                "CurrencyCode": "str",
                "Amount": 0
            },
            "CarrierWillPickUp": true,
            "CarrierWillPickUpOption": "CarrierWillPickUp",
            "LabelFormat": "PDF"
        },
        "LabelCustomization": {
            "CustomTextForLabel": "string",
            "StandardIdForLabel": "AmazonOrderId"
        }
    },
    "ShippingServiceId": "string",
    "ShippingServiceOfferId": "string",
    "HazmatType": "None",
    "LabelFormatOption": {
        "IncludePackingSlipWithLabel": true
    },
    "ShipmentLevelSellerInputsList": [
        {
            "AdditionalInputFieldName": "string",
            "AdditionalSellerInput": {
                "DataType": "string",
                "ValueAsString": "string",
                "ValueAsBoolean": true,
                "ValueAsInteger": 0,
                "ValueAsTimestamp": "2019-08-24T14:15:22Z",
                "ValueAsAddress": {
                    "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"
                },
                "ValueAsWeight": {
                    "value": 11,
                    "unit": "Grams"
                },
                "ValueAsDimension": {
                    "value": 0,
                    "unit": "Cm"
                },
                "ValueAsCurrency": {
                    "CurrencyCode": "str",
                    "Amount": 0
                }
            }
        }
    ]
}'

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

Response schema.

payload

object (Shipment)

optional

Contains information pertaining to a shipment in an inbound plan.

Example:

{"destination":{"destinationType":"AMAZON_OPTIMIZED"},"freightInformation":{"declaredValue":{"amount":5.5,"code":"CAD"},"freightClass":"FC_50"},"inboundPlanId":"wf1234abcd-1234-abcd-5678-1234abcd5678","placementOptionId":"pl1234abcd-1234-abcd-5678-1234abcd5678","selectedDeliveryWindow":{"availabilityType":"AVAILABLE","deliveryWindowOptionId":"dw1234abcd-1234-abcd-5678-1234abcd5678","editableUntil":"2024-01-05T20:00:00.000Z","endDate":"2024-01-05T20:00:00.000Z","startDate":"2024-01-05T14:00:00.000Z"},"shipmentConfirmationId":"shipmentConfirmationId","shipmentId":"sh1234abcd-1234-abcd-5678-1234abcd5678","source":{"sourceType":"SELLER_FACILITY"}}

amazonReferenceId

string

optional

A unique identifier created by Amazon that identifies this Amazon-partnered, Less Than Truckload/Full Truckload (LTL/FTL) shipment.

>= 1 characters<= 1024 characters

contactInformation

object (ContactInformation)

optional

The seller's contact information.

Example:

{"email":"email@email.com","name":"name","phoneNumber":"1234567890"}

dates

object (Dates)

optional

Specifies the date that the seller expects their shipment will be shipped.

Example:

{"readyToShipWindow":{"end":"2024-01-06T14:48:00.000Z","start":"2024-01-05T14:48:00.000Z"}}

destination

object (ShipmentDestination)

required

The Amazon fulfillment center address and warehouse ID.

freightInformation

object (FreightInformation)

optional

Freight information describes the skus being transported. Freight carrier options and quotes will only be returned if the freight information is provided.

Example:

{"declaredValue":{"amount":5.5,"code":"CAD"},"freightClass":"FC_50"}

name

string

optional

The name of the shipment.

placementOptionId

string

required

The identifier of a placement option. A placement option represents the shipment splits and destinations of SKUs.

>= 38 characters<= 38 characters

Match pattern:

^[a-zA-Z0-9-]*$

selectedDeliveryWindow

object (SelectedDeliveryWindow)

optional

Selected delivery window attributes.

Example:

{"availabilityType":"AVAILABLE","deliveryWindowOptionId":"dw1234abcd-1234-abcd-5678-1234abcd5678","editableUntil":"2024-01-05T20:00:00.000Z","endDate":"2024-01-05T20:00:00.000Z","startDate":"2024-01-05T14:00:00.000Z"}

selectedTransportationOptionId

string

optional

Identifier of a transportation option. A transportation option represent one option for how to send a shipment.

>= 38 characters<= 38 characters

Match pattern:

^[a-zA-Z0-9-]*$

selfShipAppointmentDetails

array[object (SelfShipAppointmentDetails) {3}]

optional

List of self ship appointment details.

shipmentConfirmationId

string

optional

The confirmed shipment ID which shows up on labels (for example, FBA1234ABCD).

>= 1 characters<= 1024 characters

shipmentId

string

required

Identifier of a shipment. A shipment contains the boxes and units being inbounded.

>= 38 characters<= 38 characters

Match pattern:

^[a-zA-Z0-9-]*$

source

object (ShipmentSource)

required

Specifies the 'ship from' address for the shipment.

status

string

optional

The status of a shipment. The state of the shipment will typically start as UNCONFIRMED, then transition to WORKING after a placement option has been confirmed, and then to READY_TO_SHIP once labels are generated.

Possible values: ABANDONED, CANCELLED, CHECKED_IN, CLOSED, DELETED, DELIVERED, IN_TRANSIT, MIXED, READY_TO_SHIP, RECEIVING, SHIPPED, UNCONFIRMED, WORKING

>= 1 characters<= 1024 characters

trackingDetails

object (TrackingDetails)

optional

Representation of tracking metadata.

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

{
    "payload": {
        "destination": {
            "destinationType": "AMAZON_OPTIMIZED"
        },
        "freightInformation": {
            "declaredValue": {
                "amount": 5.5,
                "code": "CAD"
            },
            "freightClass": "FC_50"
        },
        "inboundPlanId": "wf1234abcd-1234-abcd-5678-1234abcd5678",
        "placementOptionId": "pl1234abcd-1234-abcd-5678-1234abcd5678",
        "selectedDeliveryWindow": {
            "availabilityType": "AVAILABLE",
            "deliveryWindowOptionId": "dw1234abcd-1234-abcd-5678-1234abcd5678",
            "editableUntil": "2024-01-05T20:00:00.000Z",
            "endDate": "2024-01-05T20:00:00.000Z",
            "startDate": "2024-01-05T14:00:00.000Z"
        },
        "shipmentConfirmationId": "shipmentConfirmationId",
        "shipmentId": "sh1234abcd-1234-abcd-5678-1234abcd5678",
        "source": {
            "sourceType": "SELLER_FACILITY"
        }
    },
    "errors": [
        {
            "code": "string",
            "message": "string",
            "details": "string"
        }
    ]
}

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🟠429429

🔴500Server Error

🔴503Service Unavailable