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.

Vendors in the direct fulfillment program should refer to the Vendor Direct Fulfillment APIs v1 Use Case Guide to learn about APIs specific to direct fulfillment.

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 acknowledgements 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.
	Check purchase order status	`getPurchaseOrdersStatus` Returns purchase order statuses based on the filters that you specify.
	Submit purchase order acknowledgement	`submitAcknowledgement` Submits acknowledgements for one or more purchase orders.
	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.
	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.
	Submit or update advance shipment notification (ASN)/shipment confirmations	`SubmitShipmentConfirmations` Submits one or more shipment confirmations for vendor orders.
	Check Shipment Confirmation transaction status	`getTransaction` Returns the status of the transaction that you specify.
	Get shipment labels	`GetShipmentLabels` Returns small parcel shipment labels based on the filters that you specify.
Invoices and credit notes
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 acknowledgements 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. Data retrieval is possible for a maximum period of six months from the date the original POST call is made.
`getPurchaseOrder`	GET	`/vendor/orders/v1/purchaseOrders /{purchaseOrderNumber}`	Returns a purchase order (PO) 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.
`submitAcknowledgement`	POST	`/vendor/orders/v1/acknowledgements`	Acknowledges (accepts or rejects) 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.

You can 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.

You can use the getPurchaseOrder operation to get detailed order information for a specific order. You can then use the submitAcknowledgement operation to accept or reject the order.

After you accept or reject your orders, you can use the getPurchaseOrdersStatus operation to return the acknowledgement status of one or more purchase orders.

📘
Note
You can return complete purchase order details by calling the getPurchaseOrders operation, or return only the purchase order numbers with the includeDetails filter. The default value for this parameter is true, so if you don't include this query parameter, you will return the complete details of the purchase orders. If you use includeDetails=false, the response will include 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 should use this operation to get purchase orders that are available to you for fulfillment. Amazon recommends that you 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 will change 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 will have 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. These will return orders that have been 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.

Amazon recommends running a separate API call, with the changed date range, a few times a day to get the changed orders for a 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
PO item updates such as quantity change, item cancellation, or item cost change
New item added to PO
PO canceled/uncanceled
PO type change
PO delivery destination (fulfillment center) change
PO 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 will return all orders that have had one or more items canceled by Amazon after purchase order creation. This will help 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 will return 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.
Ship Window or Delivery Window usage

For vendor paid freights, the delivery window information should be used. 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.
Are backorders acceptable for a line item?

You must read the value in the isBackOrderAllowed field. When true, the order can be processed as a backorder. When false, backorders are not allowed.
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 will be present in this field.
Backorder cancelation 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
Back Order	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 will implicitly reject the missing line items.

Amazon expects you to submit the acknowledgement as fast as possible; within 24 hours at the latest. The acknowledgement should 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 acknowledgement to be submitted by you within 48 hours. You can submit a full acknowledgement update or update only a specific line item. Amazon always treats an update as a replacement of the earlier acknowledgement for the line item. After 48 hours, we only expect to receive updates to ship dates or delivery dates.

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

Verification of successfully submitted order acknowledgements

You can verify the status of the original or updated version of the order acknowledgement 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.

Business requirements

Can I increase the original quantity submitted in the purchase order when acknowledging an order?

No, you cannot send a higher quantity in the acknowledgement than what was submitted in the purchase order.
Is it a requirement to send an order acknowledgement for each purchase order?

Yes, in order to update the status of an order in the Amazon system correctly, Amazon requires PO confirmation using the API or Vendor Central. If you are unable to meet our order acknowledgement requirements using the API, you must confirm your purchase orders using Vendor Central. Contact your Amazon business representative if you do not have a Vendor Central account.
Is it a requirement to provide every PO line item in the corresponding order acknowledgement?

Yes, so that Amazon can update the order status correctly.
If a line item is placed on backorder, is it required to provide the quantity in the order acknowledgement?

Yes, so that the Amazon system can update the status of the line item correctly.
How should invalid or obsolete items on an order be reported using the order acknowledgement?

Do not process or ship an item that arrived with an invalid item number on the order. Return the invalid item number on the acknowledgement and acknowledge it as invalid. The following acknowledgement codes indicate rejected due to the item being obsolete:

Rejected: Amazon's interpretation is that the quantity stated with this code will not be delivered to Amazon as part of this purchase order. You should send the appropriate rejection reason as obsolete in the acknowledgement. This indicates that due to the item being obsolete, the item should no longer be ordered. The Amazon nomenclature for this is "hard reject", meaning this item should not be re-ordered. If this code is received two consecutive times for the same project (separated by a time gap of at least 48 hours), the item will not be reordered.

📘
Note
Amazon expects an acknowledgement even if all the line items on the purchase order were invalid and did not produce an order or invoice. If a corresponding acknowledgement cannot be sent for a purchase order, Amazon requires manual notification of invalid items. You can notify your buying team through the Vendor Central Contact Us link.

Do I need to return the same product identifier in the acknowledgement that I received in the orders transaction?

Acknowledgements must return exactly the same product identifier that was sent in the purchase order.
Is it required to provide price in the acknowledgement?

Yes, you are required to return the unit cost price in the acknowledgement. The cost price should match the unit cost price that will be invoiced. Book vendors are required to provide a list price and discount multiplier.
Can the price in the purchase order be simply returned on the acknowledgement?

No. Regardless of the price submitted on the purchase order, Amazon requires the cost price in the acknowledgement. The cost price submitted on the acknowledgement should match the cost price submitted in the invoice. Amazon payment systems will compare the two and might delay payment if they do not match.
What does Amazon require if the price or availability change after the initial acknowledgement has been transmitted?

Provide manual notification regarding any changes to Amazon orders after the initial acknowledgement has been transmitted. Your Amazon business representative can advise on when, how, and who to notify.
Is it required to provide price data for items on backorder?

Yes, this is required so Amazon can update the status of the order correctly. If the price is omitted, this will cause the acknowledgement to be rejected.
How will I know if backorders are allowed or not?

You are required to read the value in the isBackOrderAllowed field in the purchase order. A value of true indicates that backorders are allowed. A value of false indicates that backorders are not allowed.
Is it required to provide an acknowledgement code for all line items regardless of status?

Yes, it is required so we can correctly update the status of the order. If the acknowledgement code is omitted, the acknowledgement will be rejected.
What is the Amazon policy on partial shipments? How should partial shipments be reported when submitting an order acknowledgement?

Partial shipments are allowed if the purchase order allows backorders (when isBackOrderAllowed is true). Amazon recommends that you indicate one acknowledgement loop using the code accepted with the corresponding date and another acknowledgement loop using the code backordered and the corresponding date.

Accepted: For the items that can be fulfilled immediately.

Backordered: For the remaining quantity that cannot be fulfilled immediately. The remaining quantity (ordered quantity minus all confirmed quantity) will be delivered later (back-ordered).
When should I use the listPrice segment?

The listPrice segment is only required if you sell books with a list price.

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 acknowledgement status of the items in purchase orders available to you for fulfillment. This operation returns the history for ordered quantity and acknowledgements of an item. You can view details of all the acknowledgements processed for an item in a purchase order. We have provided a wide range of query parameters to filter the list of POs 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 PO create date (createdBefore and createdAfter) or the PO update date (updatedBefore and updatedAfter) along with purchaseOrderStatus=OPEN.
You can use the getPurchaseOrdersStatus operation to filter the status of POs. For example, if itemConfirmationStatus=REJECTED, the response will return all the orders that have one or more items' status as rejected.
You can check the status of a specific PO by providing the PO number in the purchaseOrderNumber query parameter.
You can get the status of all the open POs raised for a specific vendor code by providing the vendor code value in orderingVendorCode and including purchaseOrderStatus=OPEN.
You can get the status of all the POs 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 Acknowledgement use cases

Invalid line item in the purchase order

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

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 Acknowledgement

{
  "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, you should reject the item with an acknowledgement 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 Acknowledgement

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

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 will be 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 Acknowledgement

{
  "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. You should always send full updates, with the total ordered quantity, for individual line items. Full updates provide explicit 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 acknowledgements to cancel initially accepted quantities

You can use this when you discover that you can't fulfill some or all of the units of an order that were initially accepted, and you want to inform Amazon that these units will 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 Acknowledgement

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 acknowledgement 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 POs 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 PO cancellation policies, outstanding PO shipments can be canceled. However, POs with accurate shipment confirmation alert our internal systems of in-transit status. This can help avoid unnecessary PO 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.

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 will completely overwrite the first shipment confirmation data.

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. 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 via Vendor Central > Orders > Shipments or by using the Transaction Status API. It can take the system up to 30 min 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 PO 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 PO 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 should 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 will result in the shipment confirmation being rejected. Ensure that the ID being sent has not been 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. This field should be provided 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/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) should 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 has been 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:

Canceling a shipment request is possible both before and after a carrier has been 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 should be submitted only when the corresponding PO is completely confirmed. If the PO has not yet been confirmed, the shipment request will fail 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 has been assigned.
Canceling a shipment request is possible both before and after a carrier has been assigned and routing is scheduled.

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 will result in the Transportation Request being rejected. Ensure that the ID being sent has not been 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 only provides a response if shipment creation is successful. The response contains the Amazon Reference Number (ARN) and other shipment details. The carrier assignment details are available only after the carrier assignment for the shipment. 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

Request example:

GET https://sellingpartnerapi-na.amazon.com/vendor/shipping/v1/shipments?vendorShipmentIdentifier=00050003

`GetShipmentDetails` Response

Response example:

{
  "payload": {
    "pagination": {
      "nextToken": "MDAwMDAwMDAwMQ=="
    },
    "shipments": [
      {
        "vendorShipmentIdentifier": "00050003",
        "buyerReferenceNumber": "1234567",
        "currentShipmentStatus": "CarrierAssigned",
        "currentshipmentStatusDate": "2019-08-09T19:56:45.632",
        "shipmentStatusDetails": [
          {
            "shipmentStatus": "CarrierAssigned",
            "shipmentStatusDate": "2019-08-09T19:56:45.632"
          },
          {
            "shipmentStatus": "TransportationRequested",
            "shipmentStatusDate": "2019-07-07T19:56:45.632"
          },
          {
            "shipmentStatus": "Created",
            "shipmentStatusDate": "2019-07-06T19:56:45.632"
          }
        ],
        "shipmentCreateDate": "2019-07-06T19:56:45.632",
        "shipmentFreightTerm": "Collect",
        "sellingParty": {
          "partyId": "998US"
        },
        "shipFromParty": {
          "address": {
            "name": "ABC electronics warehouse",
            "addressLine1": "DEF 1st street",
            "city": "Lisses",
            "stateOrRegion": "abcland",
            "postalCode": "91090",
            "countryCode": "DE"
          },
          "partyId": "ABCD12"
          },
          "shipToParty": {
          "partyId": "999US"
        },
        "shipmentMeasurements": {
          "totalCartonCount": 30,
          "totalPalletStackable": 30,
          "totalPalletNonStackable": 30,
          "shipmentWeight": {
            "unitOfMeasure": "Kg",
            "value": "120.45"
        },
        "shipmentVolume": {
            "unitOfMeasure": "CuFt",
            "value": "2.4"
          }
        },
        "collectFreightPickupDetails": {
          "requestedPickUp": "2019-08-10T19:56:45.632",
          "scheduledPickUp": "2019-08-10T19:56:45.632",
          "carrierAssignmentDate": "2019-08-09T19:56:45.632",
        },
        "purchaseOrders": [
          {
            "purchaseOrderNumber": "1BBBAAAA"
          }
        ],
        "transportationDetails": {
          "shipMode": "LessThanTruckLoad",
          "transportationMode": "Road",
          "shippedDate": "2019-08-07T19:56:45.632",
          "estimatedDeliveryDate": "2019-08-07T19:56:45.632",
          "shipmentDeliveryDate": "2019-08-07T19:56:45.632",
          "carrierDetails": {
            "name": "UPS",
            "phone": "1234567890",
            "email": "abc@xyz.com",
            "code": "string",
            "shipmentReferenceNumber": "TRACK001"
          },
          "billOfLadingNumber": "string"
        }
      }
    ]
  }
}

`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 will be 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 will be 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 should be same as the `sellingParty.partyId` in the Shipment. Type: string	No

Request example

GET /vendor/shipping/v1/transportLabels?vendorShipmentIdentifier=7822

GetShipmentLabels Response

{
  "payload": {
    "pagination": {
      "nextToken": "MDAwMDAwMDAwMQ=="
    },
    "transportLabels": [
      {
        "labelCreateDateTime": "2024-10-23T17:10:35Z",
        "shipmentInformation": {
          "vendorDetails": {
            "sellingParty": {
              "partyId": "WAD47"
            },
            "vendorShipmentIdentifier": "7822"
          },
          "buyerReferenceNumber": "14511336331",
          "shipToParty": {
            "partyId": "LAX9"
          },
          "shipFromParty": {
            "partyId": "0-55767831",
            "address": {
              "name": "Wheeler Bros., Inc. HQ",
              "addressLine1": "384 Drum Ave",
              "addressLine2": "Suite 123",
              "addressLine3": "DOOR 1",
              "city": "Somerset",
              "stateOrRegion": "PA",
              "postalCode": "15501",
              "countryCode": "US"
            }
          },
          "masterTrackingId": "1ZR873R70319165935",
          "totalLabelCount": 1,
          "shipMode": "SmallParcel"
        },
        "labelData": [
          {
            "labelSequenceNumber": 1,
            "labelFormat": "PDF",
            "carrierCode": "UPSN",
            "trackingId": "1ZR873R70319165935",
            "label": "Base 64 encoded string goes here."
          }
        ]
      }
    ]
  }
}

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

📘
Note
The submitInvoices operation can be used to submit credit notes in Europe.

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 should be invoiced only after they are confirmed and shipped to Amazon. Otherwise, the invoice will be rejected.

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

Invoices with incorrect information will be 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 POs and invoices.

The Amazon Accounts Payable (AP) team will contact 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 invoices via 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.

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 should never be reused (even after one year).
If an invoice sent by API fails due to incorrect data, but a Vendor Central invoice has the correct data, then you should 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 should be sent with a new Invoice ID.
No invoice with total amount = 0 should 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 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 should match the payment terms agreed upon with the Amazon buyer.
Item product identifier should match the order item product identifier that was sent to the vendor in the matching purchase order.
The invoice total amount should 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 should 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 should 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 should 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 will get the payment. Also called Supplier.	Tax and address details of the party (vendor) who will be receiving 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 will be receiving 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 should match the values in Amazon's systems.	Vendor code or warehouse code and address of the party from where items will be shipped.	Vendor code or warehouse code and address of the party from where items will be shipped.
Ship To Party	Ship to Address details along with the State ISO Code. Ship to party is required. Values should match the values in Amazon's systems.	Amazon ID or warehouse code and address of the party to which items will be shipped.	Amazon ID or warehouse code and address of the party to which items will be shipped.
Bill to Party	Bill to Party is required. It might be 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 will be 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 will be 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 PO number should be the same for all line items in one invoice. Required.	One invoice can have information for multiple orders. The PO number should 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 PO number should 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 only for invoices in India.	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 will fail. 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 Vendor Invoices API 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.

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 not supported in all locations.

`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 Acknowledgement and Shipment Confirmation via this API. We highly recommend that you check the status using this API to ensure that your transactions were processed successfully. If an error occurs the response will contain 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 will be always 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 about 2 months 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

Verification of successfully submitted order acknowledgements

Business requirements

📘Note

Country-specific business requirements

Get Purchase Orders status

Purchase Order and Acknowledgement use cases

Invalid line item in the purchase order

Purchase Order

Purchase Order Acknowledgement

Purchase Order Status

Obsolete line item in the purchase order

Purchase Order

Purchase Order Acknowledgement

Confirm partial item quantity and backorder the rest of the quantity

Purchase order – (Import Purchase Order)

Purchase Order Acknowledgement

Purchase Order Status

Multiple acknowledgements to cancel initially accepted quantities

Purchase Order

Purchase Order Acknowledgement

Full cancellation

Partial cancellation

Purchase order status after subsequent partial cancellation

What is the Vendor Shipments API?

SubmitShipmentConfirmations

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/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

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

GetShipmentDetails Response

GetShipmentLabels

Business requirements

Country specific business requirements

Query request

Request example

📘
Note

`getPurchaseOrders`

📘
Note

📘
Note

`getPurchaseOrder`

📘
Note

`submitAcknowledgement`

📘
Note

`SubmitShipmentConfirmations`

Small `LooseAssortmentCase` parcel with expiration and lot numbers

`SubmitShipments`

🚧
Important

📘
Note

📘
Note

`GetShipmentDetails`

🚧
Important

`GetShipmentDetails` request

`GetShipmentDetails` Response

`GetShipmentLabels`

📘
Note

❗
Warning

📘
Note

`submitInvoices` use cases