Vendor Retail Procurement APIs v1 Use Case Guide

Help vendors manage their retail business operations programmatically through web service integration.

The Selling Partner APIs for Retail Vendors help you manage your retail business operations programmatically through web service integration. Automated integration with Amazon can help you improve and maintain your performance at scale and grow your business with Amazon.

To learn more about APIs specific to direct fulfillment, refer to the Vendor Direct Fulfillment APIs v1 Use Case Guide.

You can use these APIs to build applications that increase operational efficiency, reduce effort, reduce errors, and improve performance.

For authentication and authorization information, refer to Authorizing Selling Partner API applications.

Business processes you can fulfill using the Vendor Retail Procurement APIs

You can use the Vendor Orders API to manage purchase orders, the Vendor Shipments API to send shipment confirmations, the Vendor Invoices API to submit invoices, and the Vendor Transaction Status API to determine the status of your order acknowledgments and shipment confirmations.

Business process	Use case	Operation
Purchase order management	Get purchase order changes or cancellations	`getPurchaseOrders` Returns a list of purchase orders created or changed during the time frame that you specify.
Purchase order management	Check purchase order status	`getPurchaseOrdersStatus` Returns purchase order statuses based on the filters that you specify.
Purchase order management	Submit purchase order acknowledgment	`submitAcknowledgement` Submits acknowledgements for one or more purchase orders.
Purchase order management	Check Order Confirmation transaction status	`getTransaction` Returns the status of the transaction that you specify.
Shipments	Submits shipment requests	`SubmitShipments` Submits one or more shipment request for vendor Orders.
Shipments	Get shipment status or shipment / transport labels	`GetShipmentDetails` Returns the Details about Shipment, Carrier Details, status of the shipment, container details and other details related to shipment based on the filter parameters value that you specify.
Shipments	Submit or update advance shipment notification (ASN)/shipment confirmations	`SubmitShipmentConfirmations` Submits one or more shipment confirmations for vendor orders.
Shipments	Check Shipment Confirmation transaction status	`getTransaction` Returns the status of the transaction that you specify.
Shipments	Get shipment labels	`GetShipmentLabels` Returns small parcel shipment labels based on the filters that you specify.
Invoices and credit notes	Submit vendor invoices	`submitInvoices` Submit new invoices to Amazon.

What is the Vendor Orders API?

You can use the Vendor Orders API (Orders API) to receive purchase orders and to send order acknowledgments to accept or reject order fulfillment.

The Vendor Orders API includes the following operations:

Operation	HTTP method	Path	Description
`getPurchaseOrders`	GET	`/vendor/orders/v1/purchaseOrders`	Returns a list of purchase orders created or changed during the time frame that you specify. Use the `getPurchaseOrders` operation to access orders created or changed during a specified time period (within a rolling window of the last six months, after June 2020). To optimize response time, we recommend that you limit the time range to no more than seven days.
`getPurchaseOrder`	GET	`/vendor/orders/v1/purchaseOrders /{purchaseOrderNumber}`	Returns a purchase order based on the `purchaseOrderNumber` value that you specify. Data retrieval is possible for a maximum period of six months from the date the original POST call is made. You can then use the `submitAcknowledgement` operation to accept or reject the order.
`submitAcknowledgement`	POST	`/vendor/orders/v1/acknowledgments`	Acknowledges (accepts or rejects) one or more purchase orders. After you accept or reject your orders, you can use the `getPurchaseOrdersStatus` operation to return the acknowledgement status of one or more purchase orders.
`getPurchaseOrdersStatus`	GET	`/vendor/orders/v1/purchaseOrdersStatus`	Returns purchase order statuses based on the filters that you specify. Data retrieval is possible for a maximum period of six months from the date the original POST call is made.

📘
Note
You can modify the purchase order details returned in the response of the getPurchaseOrders operation by including the includeDetails query parameter. When includeDetails=true, the response returns all purchase order details. When includeDetails=false, the response includes only a list of purchase order numbers and the current state of each purchase order.

The following diagram shows the workflow using the Vendor Orders API.

The Vendor orders workflow.

`getPurchaseOrders`

The getPurchaseOrders operation returns either a list of order references (purchase order numbers and status) or complete order details, for all orders that meet the criteria specified in the request. If you are returning only order references, they can be used later with the getPurchaseOrder operation to get order details for a specific order.

You can use this operation to get purchase orders that are available for fulfillment. You must check for orders at least once per hour during business hours. Depending on your business volume, you can choose to check more frequently. You can get up to 100 orders in one API call. If there are more than 100 orders, you can use nextToken to get the next set of orders.

Order changes and cancellations

You can return order changes and cancellations using the getPurchaseOrders operation.

Order changes: Sometimes Amazon changes the purchase order data after order creation due to a requirement change. You can use the getPurchaseOrders operation to get updated orders. If Amazon changes a purchase order, the order contains a purchaseOrderChangedDate field that is the timestamp when Amazon updated the order. If this field does not exist, the order has not changed since creation.

📘
Note
Amazon can also change the purchase order after you have acknowledged it.

You can get a list of orders that have changed within a specified date range by using the changedAfter and changedBefore query parameters. The response returns the orders that are changed by Amazon within the specified date range, and you must fulfill the updated purchase order. Alternatively, you can filter using isPOChanged=true to get all changed purchase orders.

You can make separate API calls with the changed date range a few times a day to get the changed orders for that day. For example, four times a day you can call the get purchase orders operation to get orders changed in the last six hours.

The following is a list of changes that can contribute to order changes. For these changes, you must pull the changed order and ship the correct purchase order:

Ship or delivery window change
Purchase order item updates such as quantity change, item cancellation, or item cost change
New item added to purchase order
Purchase order canceled/uncanceled
Purchase order type change
Purchase order delivery destination (fulfillment center) change
Purchase order freight information change

Item cancellation: You can also use the Vendor Orders API, with the filter poItemState=Cancelled, to return orders with one or more canceled items. This returns all orders that have had one or more items canceled by Amazon after purchase order creation. This helps you get only the orders that have canceled items (ordered quantity is zero) and to help ensure you don't ship the canceled items.

📘
Note
Item cancellation qualifies as an order change and so you will also return these orders with the list of changed orders.

Purchase order state and vendor code: The purchase order schema includes the current purchase order state and state update time. You can use the filter purchaseOrderState to filter orders based on the current state.

For example, you can get all purchase orders that have not yet been acknowledged or fulfilled using purchaseOrderState=New.

You can also get purchase orders for a specific vendor code by providing one of the authorized vendor codes in filter orderingVendorCode. This filter returns only purchase orders raised for the vendor code included with the filter.

For details about all the available filters, refer to the Vendor Orders API Reference.

The following diagram shows the integration workflow when retrieving purchase orders:

The Vendor orders workflow when retrieving purchase orders.

`getPurchaseOrder`

The getPurchaseOrder operation uses the purchase order number to return information you specify about the purchase order. The response includes complete purchase order information, including line item details, quantity, and cost.

Use this operation to get the details of specific orders returned by the getPurchaseOrders operation.

The following diagram shows the integration workflow when retrieving a specific purchase order:

The Vendor orders workflow when retrieving a specific purchase order.

Business requirements

Weight-based ordering

For orders that contain items that are sold by weight, the unitOfMeasure field (under listPrice and netCost) reflects the actual weight unit of measurement. The weight unit of measurement values includes POUNDS, OUNCES, GRAMS, and KILOGRAMS.

The listPrice segment is only required if you sell books with a list price.
Ship window or delivery window usage

Vendor paid freights require that you specify delivery window information. Dates are represented in date time interval format in accordance with ISO 8601. The format is the start and end date separated by double hyphen (--). The start date field represents the earliest date that Amazon expects the freight to be delivered to the Amazon fulfillment center listed on the purchase order. The end date field represents the latest date that Amazon expects the freight to be delivered to the Amazon fulfillment center listed on the purchase order.

Use the ship window information for Amazon-paid freights. The date is represented in date/time interval format according to ISO 8601. The format is start and end date separated by double hyphen (--). The start date field represents the earliest date that Amazon expects to pick up the freight. The end date represents the latest date that Amazon expects to pick up the freight. If the same date is listed in the start date and end date fields, then read that date as the date that Amazon expects to pick up the freight.
Backorders

The backorder policy is determined by your Amazon business representative. Read the value in the isBackOrderAllowed field in the getPurchaseOrders API response to determine whether a backorder is allowed. When true, the order can be processed as a backorder. When false, backorders are not accepted.

You must provide the price data for items on backorder. Amazon can then update the status of the order correctly. If the price is omitted, the acknowledgment is rejected.
Partial shipments

Partial shipments are allowed if the purchase order allows backorders (when isBackOrderAllowed is true). You can indicate one acknowledgment loop using the code accepted with the corresponding date and another acknowledgment loop using the code backordered and the corresponding date.
- Use accepted for the items that can be fulfilled immediately.
- Use backordered for the remaining quantity that cannot be fulfilled immediately. The remaining quantity (ordered quantity minus all confirmed quantity) is delivered later (back-ordered).
For more information, refer to Confirm partial item quantity and backorder the rest of the quantity and SubmitShipmentConfirmations.
Deal codes

Deal codes are promotional codes reported in the dealCode field of the order. Any information related to promo codes, special discounts, or pricing is present in this field.
Backorder cancellation policy

Your Amazon business representative determines the backorder policy. Discuss the details with your vendor manager.

📘
Note
Backorder cancellation dates may not be submitted in the order. You are required to set up the backorder policy at the account level.

Use the API to change an order

Submitting a change to an order using the API is not possible at this time. After an order has been placed, changing it is a manual process through Vendor Central.

Country-specific business requirements

Functionality	India	Europe	North America
Net cost	Conditional, either net cost or list price.	Conditional, either net cost or list price.	Conditional, either net cost or list price.
List price	Conditional, either net cost or list price.	Conditional, either net cost or list price.	Conditional, either net cost or list price.
Backorder	Not applicable.	Supported.	Supported.
Buying party	The address of the Amazon buying entity	The assigned party ID for the buying party.	Not applicable.
Selling party	The Amazon Vendor Code assigned to the vendor.	The Amazon Vendor Code assigned to the vendor.	The Amazon Vendor Code assigned to the vendor.
Ship-to party	The address of the ship-to entity.	The assigned party ID for the ship-to party.	Not applicable.
Bill-to party	The address of the bill-to entity.	The address of the bill-to entity	Not applicable.

`submitAcknowledgement`

You can use the submitAcknowledgement operation to accept or reject a purchase order for fulfillment. Amazon expects a complete acknowledgement, including all purchase order line items for the purchase order. If you do not provide all line items for the purchase order in the acknowledgement, Amazon implicitly rejects the missing line items. If the acknowledgment code is omitted, the acknowledgment is rejected.

In the order acknowledgement, the cost price must match the unit cost price that will be invoiced. Book vendors are required to provide a list price and discount multiplier. The price cannot be higher than the price submitted in the purchase order.

Amazon expects you to submit the acknowledgment within 24 hours, even if a line item is placed on backorder. The acknowledgment must be an accurate view of the actual shipment quantities and dates.

For any changes to quantity, price, ship dates, or delivery dates, Amazon expects an update to the acknowledgment to be submitted by you within 48 hours. You can submit a full acknowledgment update or update only a specific line item. Amazon always treats an update as a replacement of the earlier acknowledgment for the line item. After 48 hours, we only expect to receive updates to ship dates or delivery dates.

🚧
Caution
You must return the unit cost price in the acknowledgment. The cost price must match the unit cost price that is invoiced. Amazon payment systems compares the two and might delay payment if they do not match. Book vendors must provide a list price and discount multiplier.

If the first acknowledgment code for a specific line item was rejected, you are not allowed to change this with your update to either accepted or backordered.

Acknowledgement code	Description
`Accepted`	Vendor accepts to fulfill the order items.
`Backordered`	Vendor placed a backorder to fulfill the original order and provides a `scheduledShipDate` or `scheduledDeliveryDate` that is different than the `expectedShipDate` or `expectedDeliveryDate` provided in the purchase order.
`Rejected`	Vendor rejects to fulfill the order items.

If the price or availability change after the initial acknowledgment has been transmitted, you can provide manual notification. Your Amazon business representative can advise on when, how, and who to notify.

Verification of successfully submitted order acknowledgments

You can verify the status of the original or updated version of the order acknowledgment using Vendor Central or using the Transaction Status API. If the original or updated version doesn't appear after 30 minutes, submit a support case in Vendor Central by navigating to Vendor Central > Support > Contact Us > API Integration.

The following diagram shows the integration workflow when acknowledging orders.

The Vendor orders workflow when acknowledging orders.

You must send an order acknowledgment to successfully update the status of an order in the Amazon system. You can confirm your purchase order using the API or Vendor Central. You have 24 hours to accept a purchase order. Vendors should reject any purchase order that is on hold past the 24-hour time limit.

📘
Note
You cannot send a higher quantity in the order acknowledgment than what was submitted in the purchase order. However, you can confirm lesser quantity than what was submitted in the purchase order.

Country-specific business requirements

Functionality	India	Europe	North America
Scheduled Ship Date	Conditional, depends on the freight terms and current business arrangement with the you	Optional	Optional
Scheduled Delivery Date	Conditional, depends on the freight terms and current business arrangement with the you	Optional	Optional
List Price	Needed only for Book Vendors	Supported	Needed only for Book Vendors

Get purchase orders status

The getPurchaseOrdersStatus operation returns the status for the list of purchase orders that meet the criteria specified in the request. You can use this operation to get the acknowledgment status of the items in available purchase orders for fulfillment. This operation returns the history for ordered quantity and acknowledgments of an item (order history in the orderedQuantityDetails field and acknowledgment history in acknowledgementStatusDetails field). You can view details of all the acknowledgments processed for an item in a purchase order. We have provided a wide range of query parameters to filter the list of purchase orders as per your requirement.

You can return up to 100 orders in one API call. If there are more than 100 orders, you can use nextToken to get the next set of orders.

The following are examples of how you can use the getPurchaseOrdersStatus operation with different query parameters:

You can get the status of all open purchase orders within a specified date range by using either the purchase order create date (createdBefore and createdAfter) or the purchase order update date (updatedBefore and updatedAfter) along with purchaseOrderStatus=OPEN.
You can use the getPurchaseOrdersStatus operation to filter the status of purchase orders. For example, if itemConfirmationStatus=REJECTED, the response returns all the orders that have one or more items' status as rejected.
You can check the status of a specific purchase order by providing the purchase order number in the purchaseOrderNumber query parameter.
You can get the status of all the open purchase orders raised for a specific vendor code by providing the vendor code value in orderingVendorCode and including purchaseOrderStatus=OPEN.
Use the receivingStatus field in the getPurchaseOrdersStatus response to get the Amazon fulfillment center received status and received quantity.
You can get the status of all the purchase orders created in a time range that need to be shipped to a specific Amazon FC by providing the fulfillment center (FC) code in shipToPartyId and the time period range in createdBefore and createdAfter.

Purchase order and acknowledgment use cases

Invalid line item in the purchase order

If you receive an invalid product identifier in the purchase order, reject the item with an acknowledgment code Rejected and the rejectionReason as InvalidProductIdentifier.

Do not process or ship an item that arrives with an invalid item number on the order. Return the invalid item number on the order acknowledgement. Use the rejected acknowledgement code and specify that there is an invalid item number.

Purchase order

{
  "order": {
    "purchaseOrderNumber": " L8266355",
    "purchaseOrderState": "New",
    "orderDetails": {
      "purchaseOrderDate": "2019-07-16T19:17:34.304Z",
      "purchaseOrderStateChangedDate": "2019-07-16T19:17:34.304Z",
      "purchaseOrderType": "RegularOrder",
      "paymentMethod": "Invoice",
      "buyingParty": {
        "partyId": "NAG1"
      },
      "sellingParty": {
        "partyId": "999US"
      },
      "shipToParty": {
        "partyId": "NAG1"
      },
      "billToParty": {
        "partyId": "NAG1"
      },
      "items": [
        {
          "itemSequenceNumber": "1",
          "amazonProductIdentifier": " ABC123434",
          "vendorProductIdentifier": "028877454078",
          "orderedQuantity": {
            "amount": "10",
            "unitOfMeasure": "Cases",
            "unitSize": "5"
          },
          "isBackOrderAllowed": false,
          "netCost": {
            "amount": "10.2",
            "currencyCode": "USD"
          },
          "listPrice": {
            "amount": "10.2",
            "currencyCode": "USD"
          }
        }
      ]
    }
  }
}

Purchase order acknowledgment

{
  "acknowledgements": [
    {
      "purchaseOrderNumber": "L8266355",
      "sellingParty": {
        "partyId": "999US"
      },
      "acknowledgementDate": "2019-07-17T19:17:34.304Z",
      "items": [
        {
          "itemSequenceNumber": "1",
          "amazonProductIdentifier": " ABC123434",
          "vendorProductIdentifier": "028877454078",
          "orderedQuantity": {
            "amount": 10,
            "unitOfMeasure": "Cases",
            "unitSize": 5
          },
          "netCost": {
            "currencyCode": "USD",
            "amount": "10.2"
          },
          "itemAcknowledgements": [
            {
              "acknowledgementCode": "Rejected",
              "acknowledgedQuantity": {
                "amount": 10
              },
              "rejectionReason": "InvalidProductIdentifier"
            }
          ]
        }
      ]
    }
  ]
}

Purchase order status

{
  "payload": {
    "ordersStatus": [
      {
        "purchaseOrderNumber": "L8266355",
        "purchaseOrderStatus": "CLOSED",
        "purchaseOrderDate": "2019-07-16T19:17:34.304Z",
        "lastUpdatedDate": "2019-07-17T19:17:34.304Z",
        "sellingParty": {
          "partyId": "999US"
        },
        "shipToParty": {
          "partyId": "NAG1"
        },
        "itemStatus": [
          {
            "itemSequenceNumber": "1",
            "buyerProductIdentifier": "ABC123434",
            "vendorProductIdentifier": "028877454078",
            "netCost": {
              "amount": "10.2",
              "currencyCode": "USD"
            },
            "listPrice": {
              "amount": "10.2",
              "currencyCode": "USD"
            },
            "orderedQuantity": {
              "orderedQuantity": {
                "amount": 10,
                "unitOfMeasure": "Cases",
                "unitSize": 5
              },
              "orderedQuantityDetails": [
                {
                  "updatedDate": "2019-07-16T19:17:34.304Z",
                  "orderedQuantity": {
                    "amount": 10,
                    "unitOfMeasure": "Cases",
                    "unitSize": 5
                  }
                }
              ]
            },
            "acknowledgementStatus": {
              "confirmationStatus": "REJECTED",
              "acceptedQuantity": {
                "amount": 0,
                "unitOfMeasure": "Cases",
                "unitSize": 5
              },
              "rejectedQuantity": {
                "amount": 10,
                "unitOfMeasure": "Cases",
                "unitSize": 5
              },
              "acknowledgementStatusDetails": [
                {
                  "acknowledgementDate": "2019-07-17T19:17:34.304Z",
                  "acceptedQuantity": {
                    "amount": 0,
                    "unitOfMeasure": "Cases",
                    "unitSize": 5
                  },
                  "rejectedQuantity": {
                    "amount": 10,
                    "unitOfMeasure": "Cases",
                    "unitSize": 5
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }
}

Obsolete line item in the purchase order

If you receive an obsolete product in the purchase order, reject the item with an acknowledgment code Rejected and the rejectionReason as ObsoleteProduct.

Purchase order

{
  "order": {
    "purchaseOrderNumber": " L8266355",
    "purchaseOrderState": "New",
    "orderDetails": {
      "purchaseOrderDate": "2019-07-16T19:17:34.304Z",
      "purchaseOrderStateChangedDate": "2019-07-16T19:17:34.304Z",
      "purchaseOrderType": "RegularOrder",
      "paymentMethod": "Invoice",
      "buyingParty": {
        "partyId": "NAG1"
      },
      "sellingParty": {
        "partyId": "999US"
      },
      "shipToParty": {
        "partyId": "NAG1"
      },
      "billToParty": {
        "partyId": "NAG1"
      },
      "items": [
        {
          "itemSequenceNumber": "1",
          "amazonProductIdentifier": " ABC123434",
          "vendorProductIdentifier": "028877454078",
          "orderedQuantity": {
            "amount": "10",
            "unitOfMeasure": "Cases",
            "unitSize": "5"
          },
          "isBackOrderAllowed": false,
          "netCost": {
            "amount": "10.2",
            "currencyCode": "USD"
          }
        }
      ]
    }
  }
}

Purchase order acknowledgment

{
  "acknowledgements": [
    {
      "purchaseOrderNumber": "L8266356",
      "sellingParty": {
        "partyId": "999US"
      },
      "acknowledgementDate": "2019-07-17T19:17:34.304Z",
      "items": [
        {
          "itemSequenceNumber": "1",
          "amazonProductIdentifier": "ABC123438",
          "vendorProductIdentifier": "028877454079",
          "orderedQuantity": {
            "amount": 10,
            "unitOfMeasure": "Cases",
            "unitSize": "5"
          },
          "netCost": {
            "currencyCode": "IN",
            "amount": "100.20"
          },
          "itemAcknowledgements": [
            {
              "acknowledgementCode": "Rejected",
              "acknowledgedQuantity": {
                "amount": 10
              },
              "rejectionReason": " ObsoleteProduct"
            }
          ]
        }
      ]
    }
  ]
}

Confirm partial item quantity and backorder the rest of the quantity

The PARTIALLY_ACCEPTED status means that the vendor has accepted some items and rejected other items in the purchase order. Backordered items are considered as accepted.

Amazon ordered 10 item quantities. The vendor plans to split shipments and therefore sends an Accepted item quantity of six and a BackOrdered item quantity of four to indicate six units are shipped in the first shipment and four units in the second one.

Purchase order – (import purchase order)

{
  "order": {
    "purchaseOrderNumber": " L8266357",
    "purchaseOrderState": "Acknowledged",
    "orderDetails": {
      "purchaseOrderDate": "2019-07-16T19:17:34.304Z",
      "purchaseOrderChangedDate": "2019-07-18T16:05:00Z",
      "purchaseOrderStateChangedDate": "2019-07-17T10:00:34.304Z",
      "purchaseOrderType": "RegularOrder",
      "importDetails": {
        "importContainers": "2-20'HC,1-45',1-45'HC",
        "internationalCommercialTerms": "FreeOnBoard",
        "methodOfPayment": "PrepaidBySeller",
        "portOfDelivery": "USA",
        "shippingInstructions": "PREFERENCE IS PALLET-LOAD, BUT IF CONTAINERS ARE FLOOR-LOADED"
      },
      "paymentMethod": "Invoice",
      "buyingParty": {
        "partyId": "XYZ1"
      },
      "sellingParty": {
        "partyId": "999US"
      },
      "shipToParty": {
        "partyId": "XYZ1"
      },
      "billToParty": {
        "partyId": "XYZ1",
        "taxInfo": {
          "taxRegistrationNumber": "12AAXYZ4259Z123",
          "taxRegistrationType": "VAT"
        }
      },
      "items": [
        {
          "itemSequenceNumber": "1",
          "amazonProductIdentifier": " ABC123434",
          "vendorProductIdentifier": "028877454078",
          "orderedQuantity": {
            "amount": "10",
            "unitOfMeasure": "Eaches"
          },
          "isBackOrderAllowed": true,
          "netCost": {
            "amount": "10.2",
            "currencyCode": "USD"
          },
          "listPrice": {
            "amount": "10.2",
            "currencyCode": "USD"
          }
        }
      ]
    }
  }
}

Purchase order acknowledgment

{
  "acknowledgements": [
    {
      "purchaseOrderNumber": "L8266355",
      "sellingParty": {
        "partyId": "999US"
      },
      "acknowledgementDate": "2019-07-17T19:17:34.304Z",
      "items": [
        {
          "itemSequenceNumber": "1",
          "amazonProductIdentifier": " ABC123434",
          "vendorProductIdentifier": "028877454078",
          "orderedQuantity": {
            "amount": 10,
            "unitOfMeasure": "Eaches"
          },
          "netCost": {
            "currencyCode": "USD",
            "amount": "10.2"
          },
          "itemAcknowledgements": [
            {
              "acknowledgementCode": "Accepted",
              "acknowledgedQuantity": {
                "amount": 6
              },
              "scheduledShipDate": "2019-07-17T19:17:34.304Z"
            },
            {
              "acknowledgementCode": "Backordered",
              "acknowledgedQuantity": {
                "amount": 4
              },
              "scheduledShipDate": "2019-07-25T19:17:34.304Z"
            }
          ]
        }
      ]
    }
  ]
}

After shipping the first part of the order the vendor provides Amazon with a more accurate date for the second shipment, using scheduledShipDate for the back-ordered items. Make sure to send full updates, with the total ordered quantity, for individual line items. Full updates provide visibility into quantities.

Purchase order status

{
  "payload": {
    "ordersStatus": [
      {
        "purchaseOrderNumber": "L8266355",
        "purchaseOrderStatus": "OPEN",
        "purchaseOrderDate": "2019-07-16T19:17:34.304Z",
        "lastUpdatedDate": "2019-07-18T16:05:00Z",
        "sellingParty": {
          "partyId": "999US"
        },
        "shipToParty": {
          "partyId": "XYZ1"
        },
        "itemStatus": [
          {
            "itemSequenceNumber": "1",
            "buyerProductIdentifier": "ABC123434",
            "vendorProductIdentifier": "028877454078",
            "netCost": {
              "amount": "10.2",
              "currencyCode": "USD"
            },
            "listPrice": {
              "amount": "10.2",
              "currencyCode": "USD"
            },
            "orderedQuantity": {
              "orderedQuantity": {
                "amount": 10,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              },
              "orderedQuantityDetails": [
                {
                  "updatedDate": "2019-07-16T19:17:34.304Z",
                  "orderedQuantity": {
                    "amount": 10,
                    "unitOfMeasure": "Eaches",
                    "unitSize": 1
                  }
                }
              ]
            },
            "acknowledgementStatus": {
              "confirmationStatus": "ACCEPTED",
              "acceptedQuantity": {
                "amount": 10,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              },
              "acknowledgementStatusDetails": [
                {
                  "acknowledgementDate": "2019-07-17T19:17:34.304Z",
                  "acceptedQuantity": {
                    "amount": 10,
                    "unitOfMeasure": "Eaches",
                    "unitSize": 1
                  },
                  "rejectedQuantity": {
                    "amount": 0,
                    "unitOfMeasure": "Eaches",
                    "unitSize": 1
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }
}

Multiple acknowledgments to cancel initially accepted quantities

You can use multiple acknowledgments to cancel the initially accepted quantities when you discover that you can not fulfill some or all units of the accepted order and want to inform Amazon that these units must not be shipped.

Purchase order

{
  "order": {
    "purchaseOrderNumber": " L8266355",
    "purchaseOrderState": "New",
    "orderDetails": {
      "purchaseOrderDate": "2019-07-16T19:17:34.304Z",
      "purchaseOrderStateChangedDate": "2019-07-16T19:17:34.304Z",
      "purchaseOrderType": "RegularOrder",
      "paymentMethod": "Invoice",
      "buyingParty": {
        "partyId": "NAG1"
      },
      "sellingParty": {
        "partyId": "999US"
      },
      "shipToParty": {
        "partyId": "NAG1"
      },
      "billToParty": {
        "partyId": "NAG1"
      },
      "items": [
        {
          "itemSequenceNumber": "1",
          "amazonProductIdentifier": "ABC123434",
          "vendorProductIdentifier": "028877454078",
          "orderedQuantity": {
            "amount": "10",
            "unitOfMeasure": "Cases",
            "unitSize": "5"
          },
          "isBackOrderAllowed": false,
          "netCost": {
            "amount": "10.2",
            "currencyCode": "USD"
          },
          "listPrice": {
            "amount": "10.2",
            "currencyCode": "USD"
          }
        }
      ]
    }
  }
}

Purchase order acknowledgment

Vendor initially accepted the quantity.

{
  "acknowledgements": [
    {
      "purchaseOrderNumber": "L8266355",
      "sellingParty": {
        "partyId": "999US"
      },
      "acknowledgementDate": "2019-07-17T19:17:34.304Z",
      "items": [
        {
          "itemSequenceNumber": "1",
          "amazonProductIdentifier": "ABC123434",
          "vendorProductIdentifier": "028877454078",
          "orderedQuantity": {
            "amount": 10,
            "unitOfMeasure": "Cases",
            "unitSize": "5"
          },
          "netCost": {
            "currencyCode": "USD",
            "amount": "10.2"
          },
          "itemAcknowledgements": [
            {
              "acknowledgementCode": "Accepted",
              "acknowledgedQuantity": {
                "amount": 10,
                "unitOfMeasure": "Cases",
                "unitSize": "5"
              },
              "scheduledShipDate": "2019-07-17T19:17:34.304Z"
            }
          ]
        }
      ]
    }
  ]
}

Later the vendor is not able to fulfill the accepted quantity and sends either a full or a partial cancellation through another purchase order acknowledgment request.

Full cancellation

  {
    "acknowledgements": [
      {
        "purchaseOrderNumber": "L8266355",
        "sellingParty": {
          "partyId": "999US"
        },
        "acknowledgementDate": "2019-07-17T19:17:34.304Z",
        "items": [
          {
            "itemSequenceNumber": "1",
            "amazonProductIdentifier": "ABC123434",
            "vendorProductIdentifier": "028877454078",
            "orderedQuantity": {
              "amount": 10,
              "unitOfMeasure": "Cases",
              "unitSize": "5"
            },
            "netCost": {
              "currencyCode": "USD",
              "amount": "10.2"
            },
            "itemAcknowledgements": [
              {
                "acknowledgementCode": "Rejected",
                "acknowledgedQuantity": {
                  "amount": 10,
                  "unitOfMeasure": "Cases",
                  "unitSize": "5"
                },
                "rejectionReason": "TemporarilyUnavailable"
              }
            ]
          }
        ]
      }
    ]
  }

Partial cancellation

{
  "acknowledgements": [
    {
      "purchaseOrderNumber": "L8266355",
      "sellingParty": {
        "partyId": "999US"
      },
      "acknowledgementDate": "2019-07-17T20:10:34.304Z",
      "items": [
        {
          "itemSequenceNumber": "1",
          "amazonProductIdentifier": "ABC123434",
          "vendorProductIdentifier": "028877454078",
          "orderedQuantity": {
            "amount": 10,
            "unitOfMeasure": "Cases",
            "unitSize": "5"
          },
          "netCost": {
            "currencyCode": "USD",
            "amount": "10.2"
          },
          "itemAcknowledgements": [
            {
              "acknowledgementCode": "Accepted",
              "acknowledgedQuantity": {
                "amount": 3,
                "unitOfMeasure": "Cases",
                "unitSize": "5"
              },
              "scheduledShipDate": "2019-07-17T19:17:34.304Z"
            },
            {
              "acknowledgementCode": "Rejected",
              "acknowledgedQuantity": {
                "amount": 7,
                "unitOfMeasure": "Cases",
                "unitSize": "5"
              },
              "rejectionReason": "TemporarilyUnavailable"
            }
          ]
        }
      ]
    }
  ]
}

Purchase order status after subsequent partial cancellation

{
  "payload": {
    "ordersStatus": [
      {
        "purchaseOrderNumber": "L8266355",
        "purchaseOrderStatus": "OPEN",
        "purchaseOrderDate": "2019-07-16T19:17:34.304Z",
        "lastUpdatedDate": "2019-07-17T19:17:34.304Z",
        "sellingParty": {
          "partyId": "999US"
        },
        "shipToParty": {
          "partyId": "NAG1"
        },
        "itemStatus": [
          {
            "itemSequenceNumber": "1",
            "buyerProductIdentifier": "ABC123434",
            "vendorProductIdentifier": "028877454078",
            "netCost": {
              "amount": "10.2",
              "currencyCode": "USD"
            },
            "listPrice": {
              "amount": "10.2",
              "currencyCode": "USD"
            },
            "orderedQuantity": {
              "orderedQuantity": {
                "amount": 10,
                "unitOfMeasure": "Cases",
                "unitSize": 5
              },
              "orderedQuantityDetails": [
                {
                  "updatedDate": "2019-07-16T19:17:34.304Z",
                  "orderedQuantity": {
                    "amount": 10,
                    "unitOfMeasure": "Cases",
                    "unitSize": 5
                  }
                }
              ]
            },
            "acknowledgementStatus": {
              "confirmationStatus": "PARTIALLY_ACCEPTED",
              "acceptedQuantity": {
                "amount": 3,
                "unitOfMeasure": "Cases",
                "unitSize": 5
              },
              "rejectedQuantity": {
                "amount": 7,
                "unitOfMeasure": "Cases",
                "unitSize": 5
              },
              "acknowledgementStatusDetails": [
                {
                  "acknowledgementDate": "2019-07-17T19:17:34.304Z",
                  "acceptedQuantity": {
                    "amount": 10,
                    "unitOfMeasure": "Cases",
                    "unitSize": 5
                  },
                  "rejectedQuantity": {
                    "amount": 0,
                    "unitOfMeasure": "Cases",
                    "unitSize": 5
                  }
                },
                {
                  "acknowledgementDate": "2019-07-17T20:10:34.304Z",
                  "acceptedQuantity": {
                    "amount": 3,
                    "unitOfMeasure": "Cases",
                    "unitSize": 5
                  },
                  "rejectedQuantity": {
                    "amount": 7,
                    "unitOfMeasure": "Cases",
                    "unitSize": 5
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  }
}

What is the Vendor Shipments API?

You can use the Vendor Shipments API (Shipments API) to exchange shipment related documents with Amazon.

The following operations are included in the Shipments API:

Operation	HTTP method	Path	Description
`SubmitShipmentConfirmations`	POST	`/vendor/shipping/v1/shipmentConfirmations`	Submit one or more shipment confirmations to Amazon.
`GetShipmentDetails`	GET	`/vendor/shipping/v1/shipments`	Get shipment details for the transportation request submitted to Amazon. Data retrieval is possible for a maximum period of six months from the date the shipment request was created.
`SubmitShipments`	POST	`/vendor/shipping/v1/shipments`	Submit single or multiple transportation requests to Amazon.

`SubmitShipmentConfirmations`

You can use the SubmitShipmentConfirmations operation to submit shipment confirmations to Amazon. With your shipment confirmation we can efficiently receive and process your shipments. It contains information about the items being shipped, including purchase order number, ship date, estimated delivery date, lot number, expiration date, and the Serial Shipping Container Code (SSCC).

By receiving a valid and timely shipment confirmation, we can correctly anticipate the shipments you send us. Some advantages of submitting shipment confirmations include:

Amazon can collaborate more effectively with carriers in tracking and receiving your shipments. This allows us to effectively plan our labor resources and helps ensure quicker and more efficient receipt of your shipment, which means you can invoice your purchase orders faster.
Amazon can keep track of incoming inventory and create automated orders to ensure that items do not go out of stock.
Greater visibility into in-transit products, which enables us to more accurately reflect item availability (deliver by period) to end customers.
With Amazon's purchase order cancellation policies, outstanding purchase order shipments can be canceled. However, purchase orders with accurate shipment confirmation alert our internal systems of in-transit status. This can help avoid unnecessary purchase order cancellations, chargebacks, and freight refusals.

The lack of a valid shipment confirmations can result in:

Inadequate visibility for incoming shipments.
Errors in reconciling the physical shipments with purchase orders.
Manual follow-ups to resolve discrepancies.
The need to provide proof of delivery (PODs) for invoicing.

⭐
Tip
Container details are only required for multi-box scenarios. For single-box orders, provide only the purchase order number, vendor code (sellingParty), and warehouse code (shipFromParty). In this case, Amazon generates the shipping label based on the item details in the catalog.

Shipment confirmation - replace

When a shipment confirmation has a shipmentConfirmationType of Replace, you can correct previously submitted shipment confirmations by sending an updated version. The second shipment confirmation call overwrites the first shipment confirmation data if the shipmentIdentifier and sellingParty→partyId are identical for both transactions.

The main advantage is to improve booking accuracy by updating faulty shipment confirmations after initial submission.

How does it work?

In order to replace a previously submitted shipment confirmation, a second shipment confirmation can be sent. The shipmentIdentifier and sellingParty.partyId need to be identical for both transmissions, so that we can successfully overwrite the previous version of the shipment confirmation.

Scope of shipment confirmation - replace

All shipment confirmation values can be edited except for the shipmentIdentifier and sellingParty.partyId, which need to remain identical for a successful Shipment Confirmation - Replace.
Pallet, carton, and shipped quantity cannot be increased but only reduced (though you can increase or decrease pallet, carton, and item unit count). In order to increase volumes, you must send a second shipment confirmation with a new shipmentIdentifier. You can use the same Bill of Lading (BOL) reference, if the additional units are to be delivered with the same shipment.
A shipment confirmation submitted using the API can only be edited by submitting another shipment confirmation using the API. A shipment confirmation created in Vendor Central cannot be edited using the API.
Replacing a shipment confirmation is only possible within seven days after the initial shipment confirmation, and then only if the shipment has not yet reached the Amazon fulfillment center.

Verification of successfully submitted shipment confirmations

You can verify the status of your original or replaced shipment confirmations using Vendor Central > Orders > Shipments or by using Transaction Status API. It can take the system up to 30 minutes to show the original/replaced version after submission. If Vendor Central is not showing the correct values for the replaced shipment confirmation, open a Contact Us case in Vendor Central.

The following diagram shows the integration workflow when submitting shipment confirmations.

The Vendor shipments workflow when submitting shipment confirmations.

Business requirements

When a vendor ships items that are sold by weight, they must provide the totalWeight field. The totalWeight field contains the weight of the items that the vendor ships and the weight unit of measurement. The weight unit of measurement values includes POUNDS, OUNCES, GRAMS, and KILOGRAMS.
There is a limit of 100 shipment confirmations for every truckload shipment (FTL). This means you can send separate shipment confirmation at the purchase order level, or carton level, only if the total number of individual shipment confirmations is less than or equal to 100 for that truckload or less than truckload (LTL) shipment. We recommend that you send a single shipment confirmation for the entire FTL or LTL shipment, including all purchase order and carton details.
Amazon must receive the shipment confirmation prior to the product being received at the Amazon fulfillment center. Missing or delayed shipment confirmations will result in chargebacks.
For Small Parcel Shipments, a shipment confirmation is required for every package/carton.
The following are required by Amazon and is measured to track compliance:
- For palletized deliveries, you must send a shipment confirmation before requesting a delivery slot at the Amazon fulfillment center, because appointments are only provided if a valid shipment confirmation is found in the Amazon systems. For exceptions, refer to the local shipment confirmation Help pages to understand the available options. For parcels, the shipment confirmation needs to be submitted before items are shipped. Missing or delayed shipment confirmation will result in chargebacks.
- A shipment confirmation must be for one delivery, from one vendor and for only one truck. Shipments in multiple trucks, to multiple Amazon fulfillment centers, from multiple vendor accounts, or with arrivals on multiple days require multiple shipment confirmations.
- If several smaller shipments for the same vendor account are combined in a larger shipment, and multiple shipment confirmations are required, you can use the umbrella BOL option as shown in the following example:

Shipment confirmation 1:

"billOfLadingNumber": "BOL1"
"shipmentIdentifier": "SHIPMENT CONFIRMATION_ID1"

Shipment confirmation 2:

"billOfLadingNumber": "BOL1"
"shipmentIdentifier": "SHIPMENT CONFIRMATION_ID2"

Country-specific business requirements

Additional field explanations

Bill of Lading number

The Bill of Lading number (BOL#) is the reference number needed for appointment booking at Amazon. This reference must be provided when Amazon asks for a valid shipment confirmation. It is the default reference number for the document accompanying the physical shipment. The BOL# in the shipment confirmation must match the BOL# provided in the shipment documentation.

When you define the BOL#, make sure it's unique for every shipment. Your BOL# can be the physical BOL reference, but if you opt for a different number:

Use a minimum of eight digits.
Set the Amazon vendor code as a prefix (for example: ABCD193939393).
Don't use a date or time.

Shipment identification

This field is a unique ID (uniqueness is defined within the context of the vendor) that represents this shipment confirmation. Failure to provide a Shipment Identification results in the shipment confirmation being rejected. Ensure that the ID being sent is not used in the last 365 days.

Shipped date

This field indicates the date of departure of the shipment from the vendor's location. Vendors are requested to send the shipment confirmations before the freight arrives at Amazon FC.

Estimated delivery date

This is a rough estimate, based on experience, of when a shipment is expected to be delivered to the Amazon fulfillment center. You are required to determine this based on the average transit time of the carrier. This information helps us plan for the shipment if we do not get an Estimated Delivery Date from the carrier.

This date needs to be provided for each shipment, even though an appointment date is potentially unknown at this stage.

Serial Shipment Container Code (SSCC)

Amazon processes receipts using a highly automated approach called License Plate or LP Receive and this process requires that you provide carton content details in your shipment confirmation messages. This required receive process scans a Serial Shipment Container Code (SSCC) barcode on the outside of a carton or pallet of received items, eliminating the need to scan each item within the carton or pallet. This process has a number of significant advantages, including increased efficiency, improved receiving accuracy, more accurate payment, and faster payment cycle time.

You can choose a technical solution, as Amazon decided not to strictly follow the GS1-128 solution. To be compliant with Amazon License Plate requirements, a SSCC must be a unique 18-digit code that defines a pallet or carton, it cannot be repeated within 365 days, and must include a barcode on both the carton label and in the shipment confirmation message. Additionally, the barcode on the physical label has to match 100% with the SSCC in shipment confirmation. Vendors who want to implement GS1-128 are asked to add a 00 at the beginning of their SSCC within the shipment confirmation.

For more information about generating an SSCC and the requirements for the physical shipment, refer to Vendor Central. To locate the Vendor Manual with labelling requirements, select Shipping, then License Plate label and receiving requirements.

Expiration date

The expiration date determines the limit of consumption or use of a product. It is determined based on the trade item context (for example, for food this indicates the possibility of a direct health risk resulting from use of the product after the date, for pharmaceutical products it indicates the possibility of an indirect health risk resulting from the ineffectiveness of the product after the date). It is often referred to as "use by date" or "maximum durability date."

Manufacturing date

The date the goods were packaged or manufactured. You must provide this field if an item is perishable or has a defined shelf life.

Lot number

The batch or lot number associates an item with information that the manufacturer considers relevant for traceability of the item itself or the ingredients contained in the item. The number can indicate a production lot, a work shift, a machine, a time, or an internal production code.

Use of expiration date, manufacturing date, and lot numbers in the shipment confirmation

These fields are mandatory only for perishable items, that is, for those items where the is expiration dated product attribute is Yes on the new item set-up (NIS) form.

When you define the Expiration Dates, Manufacturing Dates, or Lot Numbers in the shipment confirmation:

Expiration Dates, Manufacturing Dates, or Lot Numbers must be sent on item level.
A case or pallet can have multiple items (ASINs), each with individual Expiration Dates, Manufacturing Dates, or Lot Numbers.
One item (ASIN) must not have multiple Expiration Dates, Manufacturing Dates, or Lot Numbers within the same Case or Pallet.

You are required to provide the Expiration Date and Manufacturing Date in the shipment confirmation in YYYYMMDD format.

Shipment confirmation use cases

Small parcel standard case with expiration and lot numbers

{
  "shipmentConfirmations": [
    {
      "shipmentIdentifier": "00050003",
      "shipmentConfirmationType": "Original",
      "shipmentType": "TruckLoad",
      "shipmentStructure": "LooseStandardCase",
      "transportationDetails": {
        "carrierScac": "UPSN",
        "billOfLadingNumber": "02440000"
      },
      "amazonReferenceNumber": "ARN_Number",
      "shipmentConfirmationDate": "2019-07-29T21:56:18.575Z",
      "shippedDate": "2019-07-29T21:56:18.575Z",
      "estimatedDeliveryDate": "2019-07-29T21:56:18.575Z",
      "sellingParty": {
        "partyId": "VENDORCODE"
      },
      "shipFromParty": {
        "address": {
          "name": "ABC electronics warehouse",
          "addressLine1": "DEF 1st street",
          "city": "Lisses",
          "stateOrRegion": "abcland",
          "postalCode": "91090",
          "countryCode": "DE"
        },
        "partyId": "ABCED"
      },
      "shipToParty": {
        "partyId": "AMZWAREHOUSECODE"
      },
      "shipmentMeasurements": {
        "grossShipmentWeight": {
          "unitOfMeasure": "Kg",
          "value": "120.45"
        },
        "shipmentVolume": {
          "unitOfMeasure": "CuFt",
          "value": "2.4"
        },
        "cartonCount": 2
      },
      "shippedItems": [
        {
          "itemSequenceNumber": "001",
          "amazonProductIdentifier": "AB1234233",
          "vendorProductIdentifier": "VN24343334",
          "shippedQuantity": {
            "amount": 50,
            "unitOfMeasure": "Eaches",
            "unitSize": 1
          },
          "itemDetails": {
            "purchaseOrderNumber": "PO1234BD",
            "lotNumber": " 12345",
            "expiry": {
              "expiryDate": "2019-11-29T21:56:18.575Z"
            }
          }
        }
      ],
      "cartons": [
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567666698888"
            }
          ],
          "cartonSequenceNumber": " 001",
          "trackingNumber": "UPS TRACKING NUMBER",
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 25,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              }
            }
          ]
        },
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567666698889"
            }
          ],
          "cartonSequenceNumber": " 002",
          "trackingNumber": "UPS TRACKING NUMBER",
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 25,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              }
            }
          ]
        }
      ]
    }
  ]
}

Small `LooseAssortmentCase` parcel with expiration and lot numbers

{
  "shipmentConfirmations": [
    {
      "shipmentIdentifier": "00050003",
      "shipmentConfirmationType": "Original",
      "shipmentType": "TruckLoad",
      "shipmentStructure": "LooseAssortmentCase",
      "transportationDetails": {
        "carrierScac": "UPSN",
        "billOfLadingNumber": "02440000"
      },
      "amazonReferenceNumber": "ARN_Number",
      "shipmentConfirmationDate": "2019-07-29T21:56:18.575Z",
      "shippedDate": "2019-07-29T21:56:18.575Z",
      "estimatedDeliveryDate": "2019-07-29T21:56:18.575Z",
      "sellingParty": {
        "partyId": "VENDORCODE"
      },
      "shipFromParty": {
        "address": {
          "name": "ABC electronics warehouse",
          "addressLine1": "DEF 1st street",
          "city": "Lisses",
          "stateOrRegion": "abcland",
          "postalCode": "91090",
          "countryCode": "DE"
        },
        "partyId": "ABCED"
      },
      "shipToParty": {
        "partyId": "AMZWAREHOUSECODE"
      },
      "shipmentMeasurements": {
        "grossShipmentWeight": {
          "unitOfMeasure": "Kg",
          "value": "120.45"
        },
        "shipmentVolume": {
          "unitOfMeasure": "CuFt",
          "value": "2.4"
        },
        "cartonCount": 2
      },
      "shippedItems": [
        {
          "itemSequenceNumber": "001",
          "amazonProductIdentifier": "AB1234233",
          "vendorProductIdentifier": "VN24343334",
          "shippedQuantity": {
            "amount": 50,
            "unitOfMeasure": "Eaches",
            "unitSize": 1
          },
          "itemDetails": {
            "purchaseOrderNumber": "PO1234BD",
            "lotNumber": " 12345",
            "expiry": {
              "expiryDate": "2019-11-29T21:56:18.575Z"
            }
          }
        },
        {
          "itemSequenceNumber": "002",
          "amazonProductIdentifier": "AB1234235",
          "vendorProductIdentifier": "VN24343370",
          "shippedQuantity": {
            "amount": 50,
            "unitOfMeasure": "Eaches",
            "unitSize": 1
          },
          "itemDetails": {
            "purchaseOrderNumber": "PO1234BD",
            "lotNumber": " 12345",
            "expiry": {
              "expiryDate": "2019-11-29T21:56:18.575Z"
            }
          }
        }
      ],
      "cartons": [
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567666698888"
            }
          ],
          "cartonSequenceNumber": " 001",
          "trackingNumber": "UPS TRACKING NUMBER",
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 10,
                "unitOfMeasure": "Cases",
                "unitSize": 1
              }
            },
            {
              "itemReference": "002",
              "shippedQuantity": {
                "amount": 10,
                "unitOfMeasure": "Cases",
                "unitSize": 1
              }
            }
          ]
        }
      ]
    }
  ]
}

Palletized truck load with multiple items

{
  "shipmentConfirmations": [
    {
      "shipmentIdentifier": "00050003",
      "shipmentConfirmationType": "Original",
      "shipmentType": "TruckLoad",
      "shipmentStructure": "PalletizedAssortmentCase",
      "transportationDetails": {
        "transportationMode": "Road",
        "billOfLadingNumber": "02440000"
      },
      "shipmentConfirmationDate": "2019-08-07T19:56:45.632Z",
      "shippedDate": "2019-08-07T19:56:45.632Z",
      "estimatedDeliveryDate": "2019-08-07T19:56:45.632Z",
      "sellingParty": {
        "partyId": "VENDORCODE"
      },
      "shipFromParty": {
        "address": {
          "name": "ABC electronics warehouse",
          "addressLine1": "DEF 1st street",
          "city": "Lisses",
          "stateOrRegion": "abcland",
          "postalCode": "91090",
          "countryCode": "DE"
        },
        "partyId": "VENDORWAREHOUSECODE"
      },
      "shipToParty": {
        "partyId": "AMZWAREHOUSECODE"
      },
      "shipmentMeasurements": {
        "grossShipmentWeight": {
          "unitOfMeasure": "Kg",
          "value": "250"
        },
        "shipmentVolume": {
          "unitOfMeasure": "CuFt",
          "value": "2.4"
        },
        "palletCount": 2
      },
      "shippedItems": [
        {
          "itemSequenceNumber": "001",
          "vendorProductIdentifier": "9782700001659",
          "shippedQuantity": {
            "amount": 100,
            "unitOfMeasure": "Eaches",
            "unitSize": 1
          }
        },
        {
          "itemSequenceNumber": "002",
          "vendorProductIdentifier": "9782700001000",
          "shippedQuantity": {
            "amount": 400,
            "unitOfMeasure": "Eaches",
            "unitSize": 1
          }
        }
      ],
      "cartons": [
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567666698888"
            }
          ],
          "cartonSequenceNumber": "001",
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 25,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              },
              "itemDetails": {
                "purchaseOrderNumber": "1BBBAAAA",
                "lotNumber": "1045",
                "maximumRetailPrice": {
                  "currencyCode": "EUR",
                  "amount": "89.00"
                },
                "handlingCode": "Oversized"
              }
            },
            {
              "itemReference": "002",
              "shippedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              },
              "itemDetails": {
                "purchaseOrderNumber": "1BBBAACC",
                "lotNumber": "1087",
                "maximumRetailPrice": {
                  "currencyCode": "EUR",
                  "amount": "120.00"
                },
                "handlingCode": "Oversized"
              }
            }
          ]
        },
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567666698999"
            }
          ],
          "cartonSequenceNumber": "002",
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 25,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              },
              "itemDetails": {
                "purchaseOrderNumber": "1BBBAACD",
                "lotNumber": "1045",
                "maximumRetailPrice": {
                  "currencyCode": "EUR",
                  "amount": "89.00"
                },
                "handlingCode": "Oversized"
              }
            },
            {
              "itemReference": "002",
              "shippedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              },
              "itemDetails": {
                "purchaseOrderNumber": "1BBBAADD",
                "lotNumber": "1087",
                "maximumRetailPrice": {
                  "currencyCode": "EUR",
                  "amount": "120.00"
                },
                "handlingCode": "Oversized"
              }
            }
          ]
        },
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567666698669"
            }
          ],
          "cartonSequenceNumber": "003",
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 25,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              },
              "itemDetails": {
                "purchaseOrderNumber": "1BBBAACD",
                "lotNumber": "1045",
                "maximumRetailPrice": {
                  "currencyCode": "EUR",
                  "amount": "89.00"
                },
                "handlingCode": "Oversized"
              }
            },
            {
              "itemReference": "002",
              "shippedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              },
              "itemDetails": {
                "purchaseOrderNumber": "1BBBAADD",
                "lotNumber": "1087",
                "maximumRetailPrice": {
                  "currencyCode": "EUR",
                  "amount": "120.00"
                },
                "handlingCode": "Oversized"
              }
            }
          ]
        },
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567666697799"
            }
          ],
          "cartonSequenceNumber": "004",
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 25,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              },
              "itemDetails": {
                "purchaseOrderNumber": "1BBBAACD",
                "lotNumber": "1045",
                "maximumRetailPrice": {
                  "currencyCode": "EUR",
                  "amount": "89.00"
                },
                "handlingCode": "Oversized"
              }
            },
              {
              "itemReference": "002",
              "shippedQuantity": {
                "amount": 100,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              },
              "itemDetails": {
                "purchaseOrderNumber": "1BBBAADD",
                "lotNumber": "1087",
                "maximumRetailPrice": {
                  "currencyCode": "EUR",
                  "amount": "120.00"
                },
                "handlingCode": "Oversized"
              }
            }
          ]
        }
      ],
      "pallets": [
        {
          "palletIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567898098745"
            }
          ],
          "tier": 1,
          "block": 2,
          "dimensions": {
            "length": "1.2",
            "width": "0.8",
            "height": "1",
            "unitOfMeasure": "In"
          },
          "weight": {
            "unitOfMeasure": "Kg",
            "value": "55"
          },
          "cartonReferenceDetails": {
            "cartonCount": 2,
            "cartonReferenceNumbers": [
              "001",
              "002"
            ]
          }
        },
        {
          "palletIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567898098700"
            }
          ],
          "tier": 1,
          "block": 2,
          "dimensions": {
            "length": "1.2",
            "width": "0.8",
            "height": "1",
            "unitOfMeasure": "In"
          },
          "weight": {
            "unitOfMeasure": "Kg",
            "value": "55"
          },
          "cartonReferenceDetails": {
            "cartonCount": 2,
            "cartonReferenceNumbers": [
              "003",
              "004"
            ]
          }
        }
      ]
    }
  ]
}

Less than truck load shipment with palletized standard cases

{
  "shipmentConfirmations": [
    {
      "shipmentIdentifier": "00050003",
      "shipmentConfirmationType": "Original",
      "shipmentType": "LessThanTruckLoad",
      "shipmentStructure": "PalletizedStandardCase",
      "transportationDetails": {
        "transportationMode": "Road",
        "billOfLadingNumber": "02440000"
      },
      "shipmentConfirmationDate": "2019-08-07T19:56:45.632Z",
      "shippedDate": "2019-08-07T19:56:45.632Z",
      "estimatedDeliveryDate": "2019-08-07T19:56:45.632Z",
      "sellingParty": {
        "partyId": "VENDORCODE"
      },
      "shipFromParty": {
        "address": {
          "name": "ABC electronics warehouse",
          "addressLine1": "DEF 1st street",
          "city": "Lisses",
          "stateOrRegion": "abcland",
          "postalCode": "91090",
          "countryCode": "DE"
        },
        "partyId": "VENDORWAREHOUSECODE"
      },
      "shipToParty": {
        "partyId": "AMZWAREHOUSECODE"
      },
      "shipmentMeasurements": {
        "grossShipmentWeight": {
          "unitOfMeasure": "Kg",
          "value": "120.45"
        },
        "shipmentVolume": {
          "unitOfMeasure": "CuFt",
          "value": "2.4"
        },
        "palletCount": 1
      },
      "shippedItems": [
        {
          "itemSequenceNumber": "001",
          "vendorProductIdentifier": "9782700001659",
          "shippedQuantity": {
            "amount": 100,
            "unitOfMeasure": "Eaches",
            "unitSize": 1
          },
          "itemDetails": {
            "purchaseOrderNumber": "1BBBAAAA",
            "lotNumber": "1045",
            "maximumRetailPrice": {
              "currencyCode": "EUR",
              "amount": "299.00"
            },
            "handlingCode": "Oversized"
          }
        }
      ],
      "cartons": [
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567666698888"
            }
          ],
          "cartonSequenceNumber": "001",
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 25,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              }
            }
          ]
        },
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567666699999"
            }
          ],
          "cartonSequenceNumber": "002",
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 25,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              }
            }
          ]
        },
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567666696666"
            }
          ],
          "cartonSequenceNumber": "003",
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 25,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              }
            }
          ]
        },
        {
          "cartonIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567666697777"
            }
          ],
          "cartonSequenceNumber": "004",
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 25,
                "unitOfMeasure": "Eaches",
                "unitSize": 1
              }
            }
          ]
        }
      ],
      "pallets": [
        {
          "palletIdentifiers": [
            {
              "containerIdentificationType": "SSCC",
              "containerIdentificationNumber": "00102234567898098745"
            }
          ],
          "tier": 2,
          "block": 2,
          "dimensions": {
            "length": "1.2",
            "width": "0.8",
            "height": "1",
            "unitOfMeasure": "In"
          },
          "weight": {
            "unitOfMeasure": "Kg",
            "value": "120.45"
          },
          "cartonReferenceDetails": {
            "cartonCount": 4,
            "cartonReferenceNumbers": [
              "001",
              "002",
              "003",
              "004"
            ]
          }
        }
      ]
    }
  ]
}

Less than truck load shipment of single ASIN pallets

{
  "shipmentConfirmations": [
    {
      "shipmentIdentifier": "5013088794",
      "shipmentConfirmationType": "Original",
      "shipmentType": "LessThanTruckLoad",
      "shipmentStructure": "PalletOfItems",
      "transportationDetails": {
        "carrierShipmentReferenceNumber": "1021396377",
        "billOfLadingNumber": "501308879400010001",
        "transportationMode": "Road"
      },
      "shipmentConfirmationDate": "2023-04-21T22:31:43Z",
      "shippedDate": "2023-04-21T22:31:43Z",
      "estimatedDeliveryDate": "2023-04-21T22:31:43Z",
      "sellingParty": {
        "partyId": "VENDORCODE"
      },
      "shipFromParty": {
        "address": {
          "name": "ABC electronics warehouse",
          "addressLine1": "DEF 1st street",
          "city": "Lisses",
          "stateOrRegion": "abcland",
          "postalCode": "91090",
          "countryCode": "DE"
        },
        "partyId": "ABCED"
      },
      "shipToParty": {
        "partyId": "AMZWAREHOUSECODE"
      },
      "shipmentMeasurements": {
        "shipmentVolume": {
          "unitOfMeasure": "CuFt",
          "value": "181.656"
        },
        "palletCount": 3,
        "grossShipmentWeight": {
          "unitOfMeasure": "Lb",
          "value": "3315.744"
        }
      },
      "shippedItems": [
        {
          "itemSequenceNumber": "001",
          "vendorProductIdentifier": "VN24343334",
          "shippedQuantity": {
            "amount": 315,
            "unitOfMeasure": "Cases",
            "unitSize": 1
          },
          "itemDetails": {
            "purchaseOrderNumber": "PO1234BD",
            "lotNumber": " 12345",
            "expiry": {
              "expiryDate": "2024-11-29T21:56:18.575Z"
            }
          }
        }
      ],
      "pallets": [
        {
          "tier": 10,
          "palletIdentifiers": [
            {
              "containerIdentificationNumber": "108195730651297459",
              "containerIdentificationType": "SSCC"
            }
          ],
          "weight": {
            "unitOfMeasure": "Lb",
            "value": "828.936"
          },
          "block": 15,
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 105,
                "unitOfMeasure": "Cases",
                "unitSize": 1
              }
            }
          ],
          "dimensions": {
            "unitOfMeasure": "In",
            "length": "44.375",
            "width": "39.750",
            "height": "40.500"
          }
        },
        {
          "tier": 10,
          "palletIdentifiers": [
            {
              "containerIdentificationNumber": "108195730651297589",
              "containerIdentificationType": "SSCC"
            }
          ],
          "weight": {
            "unitOfMeasure": "Lb",
            "value": "828.936"
          },
          "block": 15,
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 105,
                "unitOfMeasure": "Cases",
                "unitSize": 1
              }
            }
          ],
          "dimensions": {
            "unitOfMeasure": "In",
            "length": "44.375",
            "width": "39.750",
            "height": "40.500"
          }
        },
        {
          "tier": 10,
          "palletIdentifiers": [
            {
              "containerIdentificationNumber": "108195730651297595",
              "containerIdentificationType": "SSCC"
            }
          ],
          "weight": {
            "unitOfMeasure": "Lb",
            "value": "828.936"
          },
          "block": 15,
          "items": [
            {
              "itemReference": "001",
              "shippedQuantity": {
                "amount": 105,
                "unitOfMeasure": "Cases",
                "unitSize": 1
              }
            }
          ],
          "dimensions": {
            "unitOfMeasure": "In",
            "length": "44.375",
            "width": "39.750",
            "height": "40.500"
          }
        }
      ]
    }
  ]
}

`SubmitShipments`

❗
Important
SubmitShipments is only available in North American and EU marketplaces.

The SubmitShipments operation is designed for Collect or WePay vendors to submit requests for the pickup of their shipments by Amazon. With this operation they can also update or cancel submitted requests. You can consolidate multiple orders that are ready to be shipped and request transportation through a single shipment request, thus saving time and lowering costs. When submitting a shipment request, the requested pickup date must be a minimum of two business days after the current date.

📘
Note
The SubmitShipments operation does not support submitting shipment requests for non-standard pallets.

Create or update shipment:

When the transactionType for a shipment request is New, you can create a new request or update a previously submitted shipment request. Updates to an existing shipment request are done based on the Vendor Shipment ID. If a shipment with the provided vendor shipment ID already exists, an update operation occurs; otherwise, a new shipment is created.

Scope of update shipment:

All shipment request values are editable, except vendorShipmentIdentifier,buyerReferenceNumber, and sellingParty.partyId which must remain identical for a successful update. You have the flexibility to modify all other fields in the shipment request before the carrier is assigned.
The requested pickup date in the shipment request can only be modified after the carrier is assigned.

Cancel shipment:

A shipment request with transactionType as Cancel enables you to cancel a previously submitted shipment request. To cancel a previously submitted shipment request, you are required to provide vendorShipmentIdentifier, buyerReferenceNumber, sellingParty.partyId, shipFromParty.partyId, shipToParty.partyId and transactionType as Cancel.

Scope of cancel shipment:

You can cancel a shipment request both before and after a carrier is assigned and routing is scheduled.

Verification of successfully submitted shipment requests

You use Vendor Central or the Vendor Transaction Status API to verify the status of your shipment request. If the status of the posted request doesn't appear after 30 minutes, submit a support case in Vendor Central by navigating to Vendor Central > Support > Contact Us > API Integration.

📘
Note
The Transaction Status API only supports Processing and Failure status values for submitted Cancel Shipment requests.

The following diagram shows the integration workflow when submitting shipment requests.

The Vendor Submit shipment workflow.

Business requirements

The shipment request must be submitted only when the corresponding purchase order is completely confirmed. If the purchase order is yet not confirmed, the shipment request fails to process.
The requestedPickUp in the Shipment request, must be a minimum of two business days after the current date.
All shipment request values are editable, except vendorShipmentIdentifier, buyerReferenceNumber, and sellingParty.partyId, which must remain identical for a successful update. You have the flexibility to modify all other fields in the shipment request before the carrier is assigned.
You can only modify the requested pickup date in the Shipment request after a carrier is assigned.
You can cancel a shipment request both before and after a carrier is assigned and routing is scheduled.

Label flips

Label flips occur when the shipping method that is assigned during shipping label generation differs from the shipping method that is assigned during order creation.

Label flips are expected. During shipping label requests, our planning system might find a better shipping method than the shipping method that the purchase order originally assigned. However, you can greatly reduce the number of label flips by incorporating the following best practices into your processes:

For single-package orders, don't include any container details in the body of shipping label creation request.
Set sellingParty.partyId to the vendor code.
Set shipFromParty.partyId to the warehouse ID.

Always submit shipping label requests between the carrier pick-up time of the previous day of the expected ship date and the actual day of shipping.

Additional field explanations

Vendor shipment identifier

This field is a unique ID (uniqueness is defined within the context of the vendor), that represents this Transportation Request. Failure to provide a vendorShipmentIdentifier results in the Transportation Request being rejected. Ensure that the ID sent is not used in the last 365 days.

Requested pickup date

This field also called Freight Ready Date, is used to specify the earliest shipment pickup date from the vendor’s location. You are requested to send the Transportation Request when the items are ready to be picked up.

Submit shipment example requests

Create or update shipment request

{
  "shipments": [
    {
      "vendorShipmentIdentifier": "00050003",
      "transactionType": "New",
      "transactionDate": "2019-08-07T19:56:45.632",
      "shipmentFreightTerm": "Collect",
      "sellingParty": {
        "partyId": "PQRSS"
      },
      "shipFromParty": {
        "address": {
          "name": "ABC electronics warehouse",
          "addressLine1": "DEF 1st street",
          "city": "Lisses",
          "stateOrRegion": "abcland",
          "postalCode": "91090",
          "countryCode": "DE"
        },
        "partyId": "999US"
      },
      "shipToParty": {
        "partyId": "ABCDF"
      },
      "shipmentMeasurements": {
        "totalCartonCount": 30,
        "totalPalletStackable": 30,
        "totalPalletNonStackable": 30,
        "shipmentWeight": {
          "unitOfMeasure": "Kg",
          "value": "120.45"
        },
        "shipmentVolume": {
          "unitOfMeasure": "CuFt",
          "value": "2.4"
        }
      },
      "collectFreightPickupDetails": {
        "requestedPickUp": "2019-08-07T19:56:45.632"
      },
      "purchaseOrders": [
        {
          "purchaseOrderNumber": "1BBBAAAA"
        },
        {
          "purchaseOrderNumber": "1BBBACCC"
        }
      ]
    }
  ]
}

Cancel shipment request

{
  "shipments": [
    {
      "vendorShipmentIdentifier": "00050003",
      "buyerReferenceNumber": "1234567",
      "transactionType": "Cancel",
      "transactionDate": "2019-08-07T19:56:45.632",
      "shipmentFreightTerm": "Collect",
      "sellingParty": {
        "partyId": "PQRSS"
      },
      "shipFromParty": {
        "address": {
          "name": "ABC electronics warehouse",
          "addressLine1": "DEF 1st street",
          "city": "Lisses",
          "stateOrRegion": "abcland",
          "postalCode": "91090",
          "countryCode": "DE"
      },
        "partyId": "999US"
      },
      "shipToParty": {
      "partyId": "ABCDF"
      }
    }
  ]
}

`GetShipmentDetails`

🚧
Important
GetShipmentDetails is only for WePay and collect orders in North American and EU marketplaces.

You can use the GetShipmentDetails operation to retrieve scheduled pickup and carrier assignment information. You must use SubmitShipments or a routing request before shipment details are available. GetShipmentDetails only returns a response after carrier assignment, which occurs either on the same day as the scheduled pickup or one day prior to the pickup date.

The details returned in the response help you efficiently run your shipping process, ensure that the order is packed, and that it's ready for pickup by the carrier on the assigned pickup date. At any time during the shipment lifecycle, you can use this operation to view shipment status and details. This operation is primarily used by WePay vendors.

The following diagram shows the Vendor Get shipment integration workflow.

The Vendor Get shipment workflow.

Business requirements

The GetShipmentDetails operation will only return a response for shipments with completed carrier assignments. Carrier assignment occurs on the same day as the scheduled pickup or one day prior to the pickup date.
The GetShipmentDetails operation will not provide details for shipments submitted through Vendor Central.

`GetShipmentDetails` request

To return a list of shipments, call the GetShipmentDetails operation and pass the following parameters:

Query parameters:

Name	Description	Required
`limit`	The limit to the number of records returned. Type: int	No
`sortOrder`	Sort the list by shipment creation date in ascending or descending order. Type: string Type: enum ( `SortOrder` )	No
`nextToken`	Use for pagination when there are more shipments than the specified result size limit. The token value is returned in the previous API call. Type: string	No
`createdAfter`	Shipments created after this time will be included in the result. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`createdBefore`	Shipments created before this time will be included in the result. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`shipmentConfirmedBefore`	Use to provide the date to retrieve Shipment Details of all shipments confirmed before this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`shipmentConfirmedAfter`	Use to provide the date to retrieve Shipment Details of all shipments confirmed after this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`packageLabelCreatedBefore`	Use to provide the date to fetch Shipment Details of all shipments for which package labels were created before this date. This field must be in ISO 8601 date/time format. Type: string (Boolean)	No
`packageLabelCreatedAfter`	Use to provide the date to retrieve Shipment Details of all shipments for which package labels were created after this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`shippedBefore`	Use to provide the date to retrieve Shipment Details of all shipments for which shipped date is before this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`shippedAfter`	Use to provide the date to retrieve Shipment Details of all shipments for which the shipped date is after this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`estimatedDeliveryBefore`	Use to provide the date to retrieve Shipment Details of all shipments for which estimated delivery date is before this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`estimatedDeliveryAfter`	Use to provide the date to retrieve Shipment Details of all shipments with estimated delivery date after this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`shipmentDeliveryBefore`	Use to provide the date to retrieve Shipment Details of all shipments with shipment delivery date before this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`shipmentDeliveryAfter`	Use to provide the date to retrieve Shipment Details of all shipments for which shipment delivery date is after this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`requestedPickUpBefore`	Use to provide the date to retrieve Shipment Details of all shipments for which requested pickup date is before this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`requestedPickUpAfter`	Use to provide the date to retrieve Shipment Details of all shipments for which requested pickup date is after this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`scheduledPickUpBefore`	Use to provide the date to retrieve Shipment Details of all shipments for which scheduled pickup date is before this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`scheduledPickUpAfter`	Use to provide the date to retrieve Shipment Details of all shipments for which scheduled pickup date is after this date. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`currentShipmentStatus`	Get Shipment Details by passing Current shipment status. Type: string	No
`vendorShipmentIdentifier`	Get Shipment Details by passing Vendor Shipment ID. Type: string	No
`buyerReferenceNumber`	Get Shipment Details by passing buyer Reference ID. Type: string	No
`buyerWarehouseCode`	Get Shipping Details based on buyer warehouse code. This value should be same as the `shipToParty.partyId` in the Shipment. Type: string	No
`sellerWarehouseCode`	Get Shipping Details based on vendor warehouse code. This value should be same as the `sellingParty.partyId` in the Shipment. Type: string	No

`GetShipmentLabels`

You can use the GetShipmentLabels operation to obtain shipping labels from Amazon exclusively for small parcel shipments on behalf of Collect/WePay vendors. This operation helps vendors retrieve shipping labels for confirmed orders that require shipment from the vendor's warehouse to Amazon's warehouse. Vendors can retrieve labels through a single API call or multiple API calls. Labels are generated once the shipment request is finalized and a carrier is assigned. Vendors have the option to filter Amazon-generated labels based on various parameters, such as buyer reference numbers (also known as Amazon reference numbers), seller warehouse codes, and other values.

The following diagram depicts the vendor get shipment label integration workflow.

The workflow for getting a shipment label

Business requirements

Call the GetShipmentLabels only after a carrier is assigned.
If GetShipmentLabels does not return a label or returns Resource Not Found, verify that a carrier has been assigned. Alternatively, you can call GetShipmentDetails to confirm whether the carrier has been assigned.
If a carrier has been assigned and the operation still returns no label, open a "Contact Us" case in the Vendor Central portal.
Once a label is used for shipping, it can never be reused.

Country-specific business requirements

This API operation is available only in the NA region.

Query request

To return a list of shipment labels, call the GetShipmentLabels operation and pass the following parameters:

Name	Description	Required
`limit`	The limit to the number of records returned. Type: int	No
`sortOrder`	Sort the list by shipment label creation date in ascending or descending order. Type: string Type: enum ( `SortOrder` )	No
`nextToken`	Used for pagination when there are more labels than the specified result size limit. The token value is returned in the previous API call. Type: string	No
`labelCreatedAfter`	Shipments labels created after this time is included in the result. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`labelCreatedBefore`	Shipments labels created before this time is included in the result. This field must be in ISO 8601 date/time format. Type: string (date-time)	No
`buyerReferenceNumber`	Get Shipment labels by passing Buyer Reference ID. Type: string	No
`vendorShipmentIdentifier`	Get Shipment labels by passing Vendor Shipment ID. Type: string	No
`sellerWarehouseCode`	Get Shipping labels based on vendor warehouse code. This value must be same as the `sellingParty.partyId` in the Shipment. Type: string	No

What is the Vendor Invoices API?

You can use the Vendor Invoices API to exchange payment related documents with Amazon. With the Submit Invoices operation, you can send vendor invoices to Amazon for confirmed and shipped orders.

The following operations are included:

Operation	HTTP method	Path	Description
`submitInvoices`	POST	`/vendor/payments/v1/invoices`	Submits one or more vendor invoices to Amazon

Submit invoices

You can use the submitInvoices operation to request payment from Amazon for items shipped. You can use this operation to submit multiple invoices in a single API call.

Items must be invoiced only after they are confirmed and shipped to Amazon. Otherwise, the invoice is rejected.

An invoice with correct information is processed by Amazon without any human interaction, which means that you receive payment more quickly.

Invoices with incorrect information is rejected in Amazon's payee system, so sending correct information is important. Refer to the business requirements section to learn how to create invoices with correct information.

Parallel testing of invoice submission

You need to complete parallel testing with our payments system before you can start using the submitInvoices operation for payment processing.

When you begin sending invoices using the API, the parallel testing phase begins. During the parallel testing phase, you send Vendor Central and API invoices for all orders shipped. You are required to parallel test until the content of at least five to 10 invoice files are validated. Parallel testing is conducted with production purchase orders and invoices.

The Amazon Accounts Payable (AP) team contacts you when parallel testing is complete, or if there are any content discrepancies in your invoices.

When you receive an email saying parallel testing is complete, you no longer need to send Vender Central invoices; you can use the API to send invoices.

Verification of successfully submitted invoices

The Transaction Status API shows the status of the semantic validations for submitted invoices, but not the actual status of invoice processing. You can verify the actual status of the original or updated version of the invoice using Vendor Central > Payments > Invoices. For more information on how to use the Transaction Status API, refer to the business use case documentation for Transaction Status. If the original or updated version with the correct values for the updated invoice isn't present after 30 minutes, submit a support case in Vendor Central by navigating to Vendor Central > Support > Contact Us > API Integration.

📘
Note
An invoice can be successfully submitted, then rejected. If your invoice is rejected after a successful submission, you will receive an email with details about why it was rejected.

The following diagram shows the integration workflow when submitting an invoice for a confirmed and shipped order.

The Vendor invoices workflow when submitting an invoice for a confirmed and shipped order.

Business requirements

For items that you price by weight, you must provide the totalWeight field. The totalWeight field contains the aggregate weight of the item that is invoiced. Additionally, the netCostUnitOfMeasure field must reflect the unit of measure for the items that you price by weight. The unit of measure values includes POUNDS, OUNCES, GRAMS, and KILOGRAMS.
Invoice numbers must be unique and must never be reused.
If an invoice sent by API fails due to incorrect data, but a Vendor Central invoice has the correct data, then you must update the invoice through the API with the correct data using the same Invoice ID.
If an invoice has incorrect data (both Vendor Central and API), then the invoice is canceled, and a new invoice must be sent with a new Invoice ID.
No invoice with total amount = 0 must be sent, as this would cause the invoice to fail.
Amazon requires the full address details in the address segments for tax compliance reasons. This is especially important for the bill-to party. For this segment the Amazon Payee system requires an exact match. For the list of addresses, refer to SP-API Bill-to Party Addresses.
Payment terms sent in an invoice must match the payment terms agreed upon with the Amazon buyer.
Item product identifier must match the order item product identifier that was sent to the vendor in the matching purchase order.
The invoice total amount must be equal to the total sum of the items, charges, and allowances.
Total of tax amount for each line level must be equal to total of tax amount at the header level.
The invoice total quantity must match the sum of the quantity of all items.
Each different charges and allowance has to be itemized on the header level (for example freight charge, package charge, and small ordering charge).

❗
Warning
A remit-to address must match the address that Amazon has on file. If the address doesn't match, the invoice fails.

Country-specific business requirements

Functionality	India	Europe	North America
Invoice type	Invoice type `CreditNote` is not supported. Invoice type must always be `Invoice`.	Invoice types `Invoice` and `CreditNote` are supported. Vendors need to send the invoice type accordingly.	Invoice type `CreditNote` is not supported. Invoice type must always be `Invoice`.
Credit note references	Not used	Vendors are required to send these references at the item level if the invoice type is `CreditNote`.	Not used
Date	Must be `now` or before.	Must be `now` or before.	Must be `now` or before.
HSN number	The Harmonized System of Nomenclature (HSN) code is mandatory for Tax Compliant Invoices. Maximum length allowed is eight characters.	Not used	Not used
Tax type at line and header level	The following are allowed for tax type: - SGST & CGST - >SGST & CGST & CESS - UTGST & CGST - UTGST & CGST & CESS - IGST - IGST & CESS If no tax information is provided, the invoice is rejected.	Tax type to be sent.	Not used
Tax registration number	A 15-character GST ID must be provided.	VAT Number	VAT Number
Tax details at line and header level	If multiple taxes are applicable for an item, the Tax details section must be sent multiple times with the appropriate tax type for that item. The same applies to the total amount of the invoice.	If multiple taxes are applicable for an item, the Tax details section must be sent multiple times with the appropriate tax type for that item. The same applies to the total amount of the invoice. There is also an additional tax type called `DomesticVAT`, which can be used to submit the tax amount in the local currency. In order to process the Domestic VAT you must use the same TaxRate used on tax Type `VAT`.	If multiple taxes are applicable for an item, the Tax details section must be sent multiple times with the appropriate tax type for that item. The same applies to the total amount of the invoice.
Remit-to party	The party who supplies goods to Amazon and gets the payment. Also reffered to as 'supplier'.	Tax and address details of the party (vendor) who receive the payment for the shipped items (in the case of an invoice) or the returned items (in case of a credit note). This is required.	Tax and address details of the party (vendor) who receive the payment for the shipped items. This is required.
Ship-from party	Ship-from address details, along with the State ISO Code. GST ID must be sent in the tax registration number. Ship-from party is required. Values must match the values in Amazon's systems.	Vendor code or warehouse code and address of the party from where items are shipped.	Vendor code or warehouse code and address of the party from where items are shipped.
Ship-to party	Ship-to address details along with the State ISO Code. Ship-to party is required. Values must match the values in Amazon's systems.	Amazon ID or warehouse code and address of the party to which items are shipped.	Amazon ID or warehouse code and address of the party to which items are shipped.
Bill-to party	Bill-to party is required. It might be the same as ship-to party. If so, the vendor is required to send the same information in both segments.	Tax and Address details of the party (Amazon) who is billed for the shipped items (in case of an Invoice) or the returned items (in case of a credit note). For a complete list of Amazon bill-to party addresses and JSON code examples, refer to SP-API Bill-to Party Addresses. This field is required.	Tax and Address details of the party (Amazon) who is billed for shipped items. This field is required.
Amazon Product Identifier and External Product Identifier	At least one of these values is required. The identifier must be the same as what is received in order.	At least one of those values is required. The identifier must be the same as what is received in order.	At least one of those values is required. The identifier must be the same as what is received in order.
Net cost	This field is required.	This field is required.	This field is required.
Purchase order number	One invoice can contain information for only one order. Therefore the purchase order number must be the same for all line items in one invoice. Required.	One invoice can have information for multiple orders. The purchase order number must be sent accordingly for different line items. This field is required if the invoice type is `Invoice` and is not used when the invoice type is `CreditNote`.	One invoice can have information for multiple orders. The purchase order number must be sent accordingly for different line items. Required.
Additional details	Not used.	This field is used when the selling party has to submit additional details for special purposes. For example, in the case of Polish split payment invoices, the selling party must send in the detail "mechanizm podzielonej płatności" of type `SUR` and `languageCode` "PL".	Not used.
`referenceNumber`	A unique invoice reference number generated by Government of India for every invoice. This field is mandatory.	Not used.	Not used.

Bill-to party addresses

When submitting an invoice, bill-to party address details must be complete and formatted correctly, or the API call fails. If you do not know the Amazon Tax ID for a bill-to location, refer to the Vendor Central help pages.

For a complete list of Amazon bill-to party addresses and JSON code examples, refer to SP-API Bill-to Party Addresses. You can also find this list, including Amazon's tax IDs, on the EDI Resources help page in your Vendor Central account.

Credit note

You can use the submitInvoices operation to send credit notes to Amazon. A credit note lists the products, quantities, and agreed prices for products or services that you provided to Amazon, but Amazon returned or did not receive. A credit note can be issued in the case of damaged goods or errors in price when allowances or rebates are agreed on beforehand between Amazon and the vendor.

📘
Note
The submitInvoices operation can be used to submit credit notes in ES, IN, IE, ZA, BE, FR, EG, PL, NL, GB, DE, SE, SA, and IT marketplaces.

Credit notes supported by Amazon

Accounts Payable (AP) CREDIT NOTES	Accounts Receivable (AR) CREDIT NOTES
PQV credit Credit for items billed but not received, or credit for duplicate payments.	Returns Credit for the items returned to the vendor due to, for example, damaged goods, goods wrongly shipped, and overstock.
PPV credit Credit for items billed at a higher/lower cost.	COOP (for example, Price Protection, Damage Allowance) COOP Credits paid by the vendor to Amazon to sell their product or for a price protection agreement.

📘
Note
Credit notes are supported in ES, IN, IE, ZA, BE, FR, EG, PL, NL, GB, DE, SE, SA, and IT marketplaces. Credit notes are not supported in AE and TR marketplaces.

`submitInvoices` use cases

Invoice with multiple items with no tax

{
  "invoices": [
    {
      "invoiceType": "Invoice",
      "id": "I5599913",
      "date": "2019-07-24T21:17:59.821Z",
      "remitToParty": {
        "partyId": "VENDORID",
        "address": {
          "name": "VENDORNAME",
          "addressLine1": "PO BOX 1234",
          "city": "SAN RAFAEL",
          "stateOrRegion": "CA",
          "postalOrZipCode": "60693",
          "countryCode": "US"
        }
      },
      "shipToParty": {
        "partyId": "AMAZON",
        "address": {
          "name": "AMAZON.COM",
          "addressLine1": "500 MCCARTHY DR",
          "addressLine2": "FAIRVIEW BUSINESS PARK",
          "city": "LEWISBERRY",
          "stateOrRegion": "PA",
          "postalOrZipCode": "17339",
          "countryCode": "US"
        }
      },
      "billToParty": {
        "partyId": "AMAZON",
        "address": {
          "name": "AMAZON.COM",
          "addressLine1": "500 MCCARTHY DR",
          "addressLine2": "FAIRVIEW BUSINESS PARK",
          "addressLine3": "string",
          "city": "LEWISBERRY",
          "stateOrRegion": "PA",
          "postalOrZipCode": "17339",
          "countryCode": "US"
        }
      },
      "paymentTerms": {
        "type": "Basic",
        "discountPercent": "2.00",
        "discountDueDays": 30,
        "netDueDays": 31
      },
      "invoiceTotal": {
        "currencyCode": "USD",
        "amount": "1295"
      },
      "items": [
        {
          "itemSequenceNumber": 1,
          "amazonProductIdentifier": "ABC123434",
          "vendorProductIdentifier": "040YP0U",
          "invoicedQuantity": {
            "amount": 2,
            "unitOfMeasure": "Cases",
            "unitSize": "10"
          },
          "netCost": {
            "currencyCode": "USD",
            "amount": "140"
          },
          "purchaseOrderNumber": "S8672793"
        },
        {
          "itemSequenceNumber": 2,
          "amazonProductIdentifier": "ABC123435",
          "vendorProductIdentifier": "0264CBS",
          "invoicedQuantity": {
            "amount": 5,
            "unitOfMeasure": "Cases",
            "unitSize": "10"
          },
          "netCost": {
            "currencyCode": "USD",
            "amount": "125"
          },
          "purchaseOrderNumber": "S8672793"
        },
        {
          "itemSequenceNumber": 3,
          "amazonProductIdentifier": "ABC123436",
          "vendorProductIdentifier": "040YP0K",
          "invoicedQuantity": {
            "amount": 3,
            "unitOfMeasure": "Cases",
            "unitSize": "5"
          },
          "netCost": {
            "currencyCode": "USD",
            "amount": "130"
          },
          "purchaseOrderNumber": "S8672793"
        }
      ]
    }
  ]
}

Invoice with single tax on an item

{
  "invoices": [
    {
      "invoiceType": "Invoice",
      "id": "5002841638",
      "date": "2019-07-24T21:17:59.821Z",
      "remitToParty": {
        "partyId": "VENDORID",
        "address": {
          "name": "VENDORNAME",
          "addressLine1": "PO BOX 1234",
          "city": "TORONTO",
          "stateOrRegion": "ON",
          "postalOrZipCode": "M5W 5M5",
          "countryCode": "CA"
        },
        "taxRegistrationDetails": [
          {
            "taxRegistrationType": "VAT",
            "taxRegistrationNumber": "VENDORTAXID"
          }
        ]
      },
      "shipToParty": {
        "partyId": "AMAZONCA",
        "address": {
          "name": "AMAZON CANADA",
          "addressLine1": "500 MCCARTHY DR",
          "addressLine2": "FAIRVIEW BUSINESS PARK",
          "city": "MISSISSAUGA",
          "stateOrRegion": "ON",
          "postalOrZipCode": "M5W 5M5",
          "countryCode": "CA"
        }
      },
      "billToParty": {
        "partyId": "AMAZONCA",
        "address": {
          "name": "AMAZON CANADA",
          "addressLine1": "500 MCCARTHY DR",
          "addressLine2": "FAIRVIEW BUSINESS PARK",
          "addressLine3": "string",
          "city": "MISSISSAUGA",
          "stateOrRegion": "ON",
          "postalOrZipCode": "M5W 5M5",
          "countryCode": "CA"
        },
        "taxRegistrationDetails": [
          {
            "taxRegistrationType": "VAT",
            "taxRegistrationNumber": "AMAZONTAXID"
          }
        ]
      },
      "paymentTerms": {
        "type": "Basic",
        "netDueDays": 31
      },
      "invoiceTotal": {
        "currencyCode": "CAD",
        "amount": "1950"
      },
      "taxDetails": [
        {
          "taxType": "GS",
          "taxRate": "5",
          "taxAmount": {
            "currencyCode": "CAD",
            "amount": "97.5"
          },
          "taxableAmount": {
            "currencyCode": "CAD",
            "amount": "1950"
          }
        }
      ],
      "items": [
        {
          "itemSequenceNumber": 1,
          "amazonProductIdentifier": "ABC123434",
          "vendorProductIdentifier": "1012380100000",
          "invoicedQuantity": {
            "amount": 4,
            "unitOfMeasure": "Eaches"
          },
          "netCost": {
            "currencyCode": "CAD",
            "amount": "20.00"
          },
          "purchaseOrderNumber": "Q6515853",
          "taxDetails": [
            {
              "taxType": "GS",
              "taxRate": "5",
              "taxAmount": {
                "currencyCode": "CAD",
                "amount": "1.00"
              }
            }
          ]
        },
        {
          "itemSequenceNumber": 2,
          "amazonProductIdentifier": "ABC123435",
          "vendorProductIdentifier": "1000570100000",
          "invoicedQuantity": {
            "amount": 30,
            "unitOfMeasure": "Eaches"
          },
          "netCost": {
            "currencyCode": "CAD",
            "amount": "50.00"
          },
          "purchaseOrderNumber": "Q6515853",
          "taxDetails": [
            {
              "taxType": "GS",
              "taxRate": "5",
              "taxAmount": {
                "currencyCode": "CAD",
                "amount": "2.50"
              }
            }
          ]
        },
        {
          "itemSequenceNumber": 3,
          "amazonProductIdentifier": "ABC123436",
          "vendorProductIdentifier": "0543900100000",
          "invoicedQuantity": {
            "amount": 3,
            "unitOfMeasure": "Eaches"
          },
          "netCost": {
            "currencyCode": "CAD",
            "amount": "90"
          },
          "purchaseOrderNumber": "Q6515853",
          "taxDetails": [
            {
              "taxType": "GS",
              "taxRate": "5",
              "taxAmount": {
                "currencyCode": "CAD",
                "amount": "4.50"
              }
            }
          ]
        },
        {
          "itemSequenceNumber": 4,
          "amazonProductIdentifier": "ABC123437",
          "vendorProductIdentifier": "1000570200000",
          "invoicedQuantity": {
            "amount": 5,
            "unitOfMeasure": "Eaches"
          },
          "netCost": {
            "currencyCode": "CAD",
            "amount": "20.00"
          },
          "purchaseOrderNumber": "Q6515853",
          "taxDetails": [
            {
              "taxType": "GS",
              "taxRate": "5",
              "taxAmount": {
                "currencyCode": "CAD",
                "amount": "1.00"
              }
            }
          ]
        }
      ]
    }
  ]
}

Invoice with multiple taxes on an item

{
  "invoices": [
    {
      "invoiceType": "Invoice",
      "id": "8900000001234",
      "date": "2019-07-24T21:17:59.821Z",
      "remitToParty": {
        "partyId": "XYZ123",
        "address": {
          "name": "XYZ INDIA PRIVATE LIMITED",
          "addressLine1": "4TH FLOOR",
          "city": "GURUGRAM",
          "stateOrRegion": "HR",
          "postalOrZipCode": "122002",
          "countryCode": "IN"
        },
        "taxRegistrationDetails": [
          {
            "taxRegistrationType": "VAT",
            "taxRegistrationNumber": "VENDORTAXID"
          }
        ]
      },
      "shipToParty": {
        "partyId": "AMAZONIN",
        "address": {
          "name": "AMAZON INDIA",
          "addressLine1": "Chowranghee Mansion JN Road",
          "city": "Kolkata",
          "stateOrRegion": "WB",
          "countryCode": "IN"
        }
      },
      "shipFromParty": {
        "partyId": "XYZ123",
        "address": {
          "name": "XYZ RETAIL PVT LTD",
          "addressLine1": "Chowranghee Mansion JN Road",
          "city": "Kolkata",
          "stateOrRegion": "WB",
          "postalOrZipCode": "700016",
          "countryCode": "IN"
        }
      },
      "billToParty": {
        "partyId": "AMAZONIN",
        "address": {
          "name": "AMAZON INDIA",
          "addressLine1": "Arrjaw Industrial & Warehouse Park",
          "addressLine2": "Near Coal India Complex",
          "city": "Hooghly",
          "stateOrRegion": "WB",
          "postalOrZipCode": "712310",
          "countryCode": "IN"
        },
        "taxRegistrationDetails": [
          {
            "taxRegistrationType": "VAT",
            "taxRegistrationNumber": "AMAZONTAXID"
          }
        ]
      },
      "paymentTerms": {
        "type": "Basic",
        "netDueDays": 30
      },
      "invoiceTotal": {
        "currencyCode": "INR",
        "amount": "258262.39"
      },
      "taxDetails": [
        {
          "taxType": "SGST",
          "taxRate": "9",
          "taxAmount": {
            "currencyCode": "INR",
            "amount": "19697.98"
          },
          "taxableAmount": {
            "currencyCode": "INR",
            "amount": "218866.43"
          }
        },
        {
          "taxType": "CGST",
          "taxRate": "9",
          "taxAmount": {
            "currencyCode": "INR",
            "amount": "19697.98"
          },
          "taxableAmount": {
            "currencyCode": "INR",
            "amount": "218866.43"
          }
        }
      ],
      "items": [
        {
          "itemSequenceNumber": 1,
          "amazonProductIdentifier": "ABC123434",
          "vendorProductIdentifier": "809000-0000",
          "invoicedQuantity": {
            "amount": 2,
            "unitOfMeasure": "Eaches"
          },
          "netCost": {
            "currencyCode": "INR",
            "amount": "21060.34"
          },
          "purchaseOrderNumber": "3DY3TK6T",
          "hsnCode": "76.06.92.90",
          "taxDetails": [
            {
              "taxType": "SGST",
              "taxRate": "9",
              "taxAmount": {
                "currencyCode": "INR",
                "amount": "1895.43"
              },
              "taxableAmount": {
                "currencyCode": "INR",
                "amount": "21060.34"
              }
            },
            {
              "taxType": "CGST",
              "taxRate": "9",
              "taxAmount": {
                "currencyCode": "INR",
                "amount": "1895.43"
              },
              "taxableAmount": {
                "currencyCode": "INR",
                "amount": "21060.34"
              }
            }
          ]
        },
        {
          "itemSequenceNumber": 2,
          "amazonProductIdentifier": "ABC123435",
          "vendorProductIdentifier": "795000-0001",
          "invoicedQuantity": {
            "amount": 3,
            "unitOfMeasure": "Eaches"
          },
          "netCost": {
            "currencyCode": "INR",
            "amount": "58915.25"
          },
          "purchaseOrderNumber": "3DY3TK6T",
          "hsnCode": "76.06.92.91",
          "taxDetails": [
            {
              "taxType": "SGST",
              "taxRate": "9",
              "taxAmount": {
                "currencyCode": "INR",
                "amount": "5302.37"
              },
              "taxableAmount": {
                "currencyCode": "INR",
                "amount": "58915.25"
              }
            },
            {
              "taxType": "CGST",
              "taxRate": "9",
              "taxAmount": {
                "currencyCode": "INR",
                "amount": "5302.37"
              },
              "taxableAmount": {
                "currencyCode": "INR",
                "amount": "58915.25"
              }
            }
          ]
        }
      ]
    }
  ]
}

Invoice with header level and line level allowance/charge details with tax

{
  "invoices": [
    {
      "invoiceType": "Invoice",
      "id": "0136981234",
      "date": "2019-07-24T21:17:59.821Z",
      "remitToParty": {
        "partyId": "XYZ12345",
        "address": {
          "name": "XYZ INDIA PRIVATE LIMITED",
          "addressLine1": "4TH FLOOR",
          "city": "GURUGRAM",
          "stateOrRegion": "HR",
          "postalOrZipCode": "122002",
          "countryCode": "IN"
        },
        "taxRegistrationDetails": [
          {
            "taxRegistrationType": "VAT",
            "taxRegistrationNumber": "VENDORVATID"
          }
        ]
      },
      "shipToParty": {
        "partyId": "AMAZONIN",
        "address": {
          "name": "AMAZON INDIA",
          "addressLine1": "Chowranghee Mansion JN Road",
          "city": "Kolkata",
          "stateOrRegion": "WB",
          "countryCode": "IN"
        }
      },
      "shipFromParty": {
        "partyId": "XYZ12345",
        "address": {
          "name": "XYZ RETAIL PVT LTD",
          "addressLine1": "Chowranghee Mansion JN Road",
          "city": "Kolkata",
          "stateOrRegion": "WB",
          "postalOrZipCode": "700016",
          "countryCode": "IN"
        }
      },
      "billToParty": {
        "partyId": "AMAZONIN",
        "address": {
          "name": "AMAZON INDIA",
          "addressLine1": "Arrjaw Industrial & Warehouse Park",
          "addressLine2": "Near Coal India Complex",
          "city": "Hooghly",
          "stateOrRegion": "WB",
          "postalOrZipCode": "712310",
          "countryCode": "IN"
        },
        "taxRegistrationDetails": [
          {
            "taxRegistrationType": "VAT",
            "taxRegistrationNumber": "AMAZONVATID"
          }
        ]
      },
      "paymentTerms": {
        "type": "Basic",
        "discountPercent": "5",
        "discountDueDays": 15,
        "netDueDays": 30
      },
      "invoiceTotal": {
        "currencyCode": "INR",
        "amount": "259678.39"
      },
      "taxDetails": [
        {
          "taxType": "SGST",
          "taxRate": "9",
          "taxAmount": {
            "currencyCode": "INR",
            "amount": "19697.98"
          },
          "taxableAmount": {
            "currencyCode": "INR",
            "amount": "218866.43"
          }
        },
        {
          "taxType": "CGST",
          "taxRate": "9",
          "taxAmount": {
            "currencyCode": "INR",
            "amount": "19697.98"
          },
          "taxableAmount": {
            "currencyCode": "INR",
            "amount": "218866.43"
          }
        }
      ],
      "chargeDetails": [
        {
          "type": "Freight",
          "description": "Freight Charges",
          "chargeAmount": {
            "currencyCode": "INR",
            "amount": "1200.00"
          },
          "taxDetails": [
            {
              "taxType": "CGST",
              "taxRate": "9",
              "taxAmount": {
                "currencyCode": "INR",
                "amount": "108.00"
              },
              "taxableAmount": {
                "currencyCode": "string",
                "amount": "string"
              }
            },
            {
              "taxType": "SGST",
              "taxRate": "9",
              "taxAmount": {
                "currencyCode": "INR",
                "amount": "108.00"
              },
              "taxableAmount": {
                "currencyCode": "string",
                "amount": "string"
              }
            }
          ]
        }
      ],
      "items": [
        {
          "itemSequenceNumber": 1,
          "amazonProductIdentifier": "ABC123434",
          "vendorProductIdentifier": "809281-5100",
          "invoicedQuantity": {
            "amount": 2,
            "unitOfMeasure": "Eaches"
          },
          "netCost": {
            "currencyCode": "INR",
            "amount": "21060.34"
          },
          "purchaseOrderNumber": "3DY3TK6T",
          "hsnCode": "76.06.92.93",
          "taxDetails": [
            {
              "taxType": "SGST",
              "taxRate": "9",
              "taxAmount": {
                "currencyCode": "INR",
                "amount": "1895.43"
              },
              "taxableAmount": {
                "currencyCode": "INR",
                "amount": "21060.34"
              }
            },
            {
              "taxType": "CGST",
              "taxRate": "9",
              "taxAmount": {
                "currencyCode": "INR",
                "amount": "1895.43"
              },
              "taxableAmount": {
                "currencyCode": "INR",
                "amount": "21060.34"
              }
            }
          ],
          "chargeDetails": [
            {
              "type": "Freight",
              "description": "Freight Charges",
              "chargeAmount": {
                "currencyCode": "INR",
                "amount": "600.00"
              }
            }
          ]
        },
        {
          "itemSequenceNumber": 2,
          "amazonProductIdentifier": "ABC123435",
          "vendorProductIdentifier": "795000-0001",
          "invoicedQuantity": {
            "amount": 3,
            "unitOfMeasure": "Eaches"
          },
          "netCost": {
            "currencyCode": "INR",
            "amount": "58915.25"
          },
          "purchaseOrderNumber": "3DY3TK6T",
          "taxDetails": [
            {
              "taxType": "SGST",
              "taxRate": "9",
              "taxAmount": {
                "currencyCode": "INR",
                "amount": "5302.37"
              },
              "taxableAmount": {
                "currencyCode": "INR",
                "amount": "58915.25"
              }
            },
            {
              "taxType": "CGST",
              "taxRate": "9",
              "taxAmount": {
                "currencyCode": "INR",
                "amount": "5302.37"
              },
              "taxableAmount": {
                "currencyCode": "INR",
                "amount": "58915.25"
              }
            }
          ],
          "chargeDetails": [
            {
              "type": "Freight",
              "description": "Freight Charges",
              "chargeAmount": {
                "currencyCode": "INR",
                "amount": "600.00"
              }
            }
          ]
        }
      ]
    }
  ]
}

EU credit note with tax

{
  "invoices": [
    {
      "invoiceType": "CreditNote",
      "id": "BasicCredit",
      "date": "2019-07-24T21:17:59.821Z",
      "remitToParty": {
        "partyId": "AMAZON",
        "address": {
          "name": "AMAZON EU SARL, UK BRANCH",
          "addressLine1": "1 PRINCIPAL PLACE WORSHIP STREET",
          "city": "LONDON",
          "postalOrZipCode": "EC2A 2FA",
          "countryCode": "GB"
        }
      },
      "billToParty": {
        "partyId": "VendorCode",
        "address": {
          "name": "Vendor Name",
          "addressLine1": "Vendor Address",
          "city": "Vendor City",
          "stateOrRegion": "Vendor State",
          "postalOrZipCode": "Vendor ZIP Code",
          "countryCode": "Vendor Country"
        }
      },
      "invoiceTotal": {
        "currencyCode": "GBP",
        "amount": "100"
      },
      "taxDetails": [
        {
          "taxType": "VAT",
          "taxRate": "10",
          "taxAmount": {
            "currencyCode": "GBP",
            "amount": "10.00"
          },
          "taxableAmount": {
            "currencyCode": "GBP",
            "amount": "100.00"
          }
        }
      ],
      "items": [
        {
          "itemSequenceNumber": 1,
          "amazonProductIdentifier": "ABC123434",
          "vendorProductIdentifier": "TESTSKU",
          "invoicedQuantity": {
            "amount": 1,
            "unitOfMeasure": "Cases",
            "unitSize": "10"
          },
          "netCost": {
            "currencyCode": "GBP",
            "amount": "100"
          },
          "creditNoteDetails": {
            "referenceInvoiceNumber": "test-basic-ref",
            "debitNoteNumber": "debit-ref",
            "returnsReferenceNumber": "return-ref",
            "goodsReturnDate": "2019-07-24T21:17:59.821Z",
            "rmaId": "rma-ref",
            "consignorsReferenceNumber": "VRET-ref"
          }
        }
      ]
    }
  ]
}

What is the Vendor Transaction Status API?

You can use the Vendor Transaction Status API to check the transaction status of your POST transactions.

The following operations are included:

Operation	HTTP method	Path	Description
`getTransaction`	GET	`/vendor/transactions/v1/transactionStatus/{transactionId}`	Get status of a post transaction request. Returns a purchase order (PO) based on the `purchaseOrderNumber` value that you specify. The status of transactions can be checked for data up to four months from the date the original POST call is made.

Get transaction status

You can use the Vendor Transaction Status API to check the status of a POST transaction. When a transaction such as an Order Acknowledgement or Shipment Confirmation is posted to Amazon using an API, the response includes a transaction identifier that uniquely identifies the transaction. Amazon will process the transaction asynchronously and the final response will be available via the getTransaction operation. Refer to the corresponding integration workflow diagrams in the individual API sections (for example, Vendor Orders and Vendor Shipments) to understand when to call this API to get the transaction status.

Amazon offers the final processed status for POST API transactions such as Order Acknowledgment and Shipment Confirmation using this API. You must check the status using this API to ensure that your transactions are processed successfully. If an error occurs the response contains error information. You can then correct the transaction and resubmit it.

Transaction status	Definition
`Processing`	The API transaction was received by Amazon and is being processed. The processing has not completed yet. Check the SLA for each API operation for the expected time to complete processing.
`Success`	This status is supported only for Submit Shipment Confirmations and Submit Shipment in NA and EU only. Success is not supported for the `submitAcknowledgement` and `submitInvoices` operations.
`Failure`	The API transaction failed during processing. The error details will be provided in the transaction status response body.

📘
Note
Transaction status is supported for the following API operations:

submitAcknowledgement

submitInvoices

SubmitShipmentConfirmations

SubmitShipments

Transaction status only supports the Processing and Failure status values. If transaction status is Processing, and not updated to Failure after 15 minutes, that indicates the transaction has successfully processed in our systems.

A transaction is generally considered to be successfully delivered on our end when the status is Processing. If for any reason, Vendor Central status is not updated within 30 minutes of sending the message, open a support case using Vendor Central by providing the transaction ID returned in the POST call. Ensure data submitted is in the correct format before opening the case.

You can't use this API for Invoice messages as they are not supported and status remains Processing. For any payment related queries, first check in Vendor Central, and then create a Contact Us case in Vendor Central and select the relevant queue.

Transaction status use cases

Transaction is in processing state

{
  "payload": {
    "transactionStatus": {
      "transactionId": "20190905193800-0c6b76cb-9662-4f3a-be03-1686c1e21477",
      "status": "Processing"
    }
  }
}

Transaction has successfully processed

Transaction has been in the processing state for 15 minutes after posting it.

{
  "payload": {
    "transactionStatus": {
      "transactionId": "20190905193800-0c6b76cb-9662-4f3a-be03-1686c1e21477",
      "status": "Processing"
    }
  }
}

Transaction has failed in Amazon

{
  "payload": {
    "transactionStatus": {
      "transactionId": "20190908091302-6ca0ac50-d06e-45f5-a1e2-eb448eadac50",
      "status": "Failure",
      "errors": [
        {
          "code": "INVALID_ORDER_ID",
          "message": "Invalid order ID."
        }
      ]
    }
  }
}

Updated 8 days ago

Business processes you can fulfill using the Vendor Retail Procurement APIs

What is the Vendor Orders API?

📘Note

getPurchaseOrders

Order changes and cancellations

📘Note

📘Note

getPurchaseOrder

Business requirements

📘Note

Country-specific business requirements

submitAcknowledgement

🚧Caution

Verification of successfully submitted order acknowledgments

📘Note

Country-specific business requirements

Get purchase orders status

Purchase order and acknowledgment use cases

Invalid line item in the purchase order

Purchase order

Purchase order acknowledgment

Purchase order status

Obsolete line item in the purchase order

Purchase order

Purchase order acknowledgment

Confirm partial item quantity and backorder the rest of the quantity

Purchase order – (import purchase order)

Purchase order acknowledgment

Purchase order status

Multiple acknowledgments to cancel initially accepted quantities

Purchase order

Purchase order acknowledgment

Full cancellation

Partial cancellation

Purchase order status after subsequent partial cancellation

What is the Vendor Shipments API?

SubmitShipmentConfirmations

⭐Tip

Shipment confirmation - replace

How does it work?

Scope of shipment confirmation - replace

Verification of successfully submitted shipment confirmations

Business requirements

Country-specific business requirements

Additional field explanations

Bill of Lading number

Shipment identification

Shipped date

Estimated delivery date

Serial Shipment Container Code (SSCC)

Expiration date

Manufacturing date

Lot number

Use of expiration date, manufacturing date, and lot numbers in the shipment confirmation

Shipment confirmation use cases

Small parcel standard case with expiration and lot numbers

Small LooseAssortmentCase parcel with expiration and lot numbers

Palletized truck load with multiple items

Less than truck load shipment with palletized standard cases

Less than truck load shipment of single ASIN pallets

SubmitShipments

❗Important

📘Note

📘Note

Business requirements

Label flips

Additional field explanations

Vendor shipment identifier

Requested pickup date

Submit shipment example requests

Create or update shipment request

Cancel shipment request

GetShipmentDetails

🚧Important

Business requirements

GetShipmentDetails request

GetShipmentLabels

Business requirements

Country-specific business requirements

Query request

📘
Note

`getPurchaseOrders`

📘
Note

📘
Note

`getPurchaseOrder`

📘
Note

`submitAcknowledgement`

🚧
Caution

📘
Note

`SubmitShipmentConfirmations`

⭐
Tip

Small `LooseAssortmentCase` parcel with expiration and lot numbers

`SubmitShipments`

❗
Important

📘
Note

📘
Note

`GetShipmentDetails`

🚧
Important

`GetShipmentDetails` request

`GetShipmentLabels`

📘
Note

❗
Warning

📘
Note

📘
Note

`submitInvoices` use cases

📘
Note