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 |
getPurchaseOrdersReturns a list of purchase orders created or changed during the time frame that you specify. |
|
| Check purchase order status |
getPurchaseOrdersStatusReturns purchase order statuses based on the filters that you specify. |
|
| Submit purchase order acknowledgement |
submitAcknowledgementSubmits acknowledgements for one or more purchase orders. |
|
| Check Order Confirmation transaction status |
getTransactionReturns the status of the transaction that you specify. |
|
| Shipments | ||
| Submits shipment requests |
SubmitShipmentsSubmits one or more shipment request for vendor Orders. |
|
| Get shipment status or shipment / transport labels |
GetShipmentDetailsReturns 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 |
SubmitShipmentConfirmationsSubmits one or more shipment confirmations for vendor orders. |
|
| Check Shipment Confirmation transaction status |
getTransactionReturns the status of the transaction that you specify. |
|
| Get shipment labels |
GetShipmentLabelsReturns small parcel shipment labels based on the filters that you specify. |
|
| Invoices and credit notes | ||
| Submit vendor invoices |
submitInvoicesSubmit 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
getPurchaseOrdersoperation, or return only the purchase order numbers with theincludeDetailsfilter. 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 useincludeDetails=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.
getPurchaseOrders
getPurchaseOrdersThe 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:
getPurchaseOrder
getPurchaseOrderThe 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:
Business requirements
-
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
isBackOrderAllowedfield. 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
dealCodefield 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
submitAcknowledgementYou 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.
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 indicaterejecteddue 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
obsoletein 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
isBackOrderAllowedfield 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
isBackOrderAllowedistrue). Amazon recommends that you indicate one acknowledgement loop using the codeacceptedwith the corresponding date and another acknowledgement loop using the codebackorderedand 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
listPricesegment?The
listPricesegment 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 (
createdBeforeandcreatedAfter) or the PO update date (updatedBeforeandupdatedAfter) along withpurchaseOrderStatus=OPEN. -
You can use the
getPurchaseOrdersStatusoperation to filter the status of POs. For example, ifitemConfirmationStatus=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
purchaseOrderNumberquery parameter. -
You can get the status of all the open POs raised for a specific vendor code by providing the vendor code value in
orderingVendorCodeand includingpurchaseOrderStatus=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
shipToPartyIdand the time period range increatedBeforeandcreatedAfter.
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
SubmitShipmentConfirmationsYou 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
shipmentIdentifierandsellingParty.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.
Business requirements
- 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:
- Use a minimum of eight digits.
- Set the Amazon vendor code as a prefix (for example: ABCD193939393).
- Don't use a date or time.
-
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.
- All shipment request values are editable, except
vendorShipmentIdentifier,buyerReferenceNumber, andsellingParty.partyIdwhich 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.
- Canceling a shipment request is possible both before and after a carrier has been assigned and routing is scheduled.
- 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
requestedPickUpin the Shipment request, must be a minimum of two business days after the current date. - All shipment request values are editable, except
vendorShipmentIdentifier,buyerReferenceNumber, andsellingParty.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.
- The
GetShipmentDetailsoperation will only return a response for shipments with completed carrier assignments. Carrier assignment occurs on the same day as the scheduled pickup or one day prior to the pickup date. - The
GetShipmentDetailsoperation will not provide details for shipments submitted through Vendor Central. - Call the
GetShipmentLabelsonly after a carrier is assigned. - If
GetShipmentLabelsdoes not return a label or returnsResource Not Found, verify that a carrier has been assigned. Alternatively, you can callGetShipmentDetailsto 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.
-
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 = 0should 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)
- SGST & CGST
- SGST & CGST & CESS
- UTGST & CGST
- UTGST & CGST & CESS
- IGST
- IGST & CESS
Shipment Confirmation 1
"billOfLadingNumber": "BOL1"
"shipmentIdentifier": "SHIPMENT CONFIRMATION_ID1"
Shipment Confirmation 2
"billOfLadingNumber": "BOL1"
"shipmentIdentifier": "SHIPMENT CONFIRMATION_ID2"
Country-specific business requirements
| Functionality | Business Definition | India | Europe | North America |
|---|---|---|---|---|
|
Bill of Lading Number/Delivery Quote
|
BOL number is the unique number assigned by the vendor. The BOL present in the shipment confirmation ideally matches the paper BOL provided with the shipment, but that is not required. Refer to Additional field explanations for more information. The BOL reference is used for appointment booking and shipment label creation.
The Delivery Quote number is an alternative to a BOL as a reference number for a shipment. |
Conditional
|
Mandatory for all shipment confirmations. | Mandatory for FTL or LTL shipments. |
| Carrier Shipment Reference Number (PRO#) | The PRO number (Pro Number) is a unique number assigned by the carrier. It is used to identify and track the shipment that goes out for delivery. | Mandatory for all shipment confirmations. | Optional | Mandatory for all shipment confirmations. |
| Shipped Date |
Date on which the shipment leaves the vendor's warehouse.
|
Mandatory for all shipment confirmations.
|
Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. |
|
Estimated Delivery Date
|
Date on which the shipment is expected to reach Amazon's fulfillment center. This must be an estimate based on the average transit time between the ship from location and the destination. The exact appointment time will be provided by Amazon and is potentially not known when creating the shipment.
|
Mandatory for all shipment confirmations.
|
Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. |
| Carton Count | Number of cartons present in the shipment. Units that are stacked on the pallet without the outer carton are counted as one unit = one carton. The carton count is required at the shipment level. | Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. |
| Pallet Count | Number of pallets present in the shipment. For small parcel shipments the value zero needs to be indicated, all volumes that reach the FC on a pallet need to have a minimum of one stated in this segment. The information is required at shipment level. | Mandatory for all shipment confirmations for palletized deliveries. | Mandatory for all shipment confirmations. | Mandatory for FTL and LTL shipments. |
| Standard carrier Alpha Code (SCAC) | Code that identifies the carrier for the shipment. The Standard Carrier Alpha Code (SCAC) is a unique two-to-four-letter code used to identify a carrier. Carrier SCAC codes are assigned and maintained by the NMFTA (National Motor Freight Association). | Optional | Optional | Mandatory for all shipment confirmations. |
| Shipping Location (Ship To) | Party Id/Warehouse Code of the location where the products are being shipped to. API schema field name is "shipToParty" | Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. |
| Supplier Identification | Supplier identification of the supplier who ships the goods to Amazon. API schema field name is "sellingParty". | Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. | Optional |
| Ship From | Address (ZIP code) and country reference of the location the products are physically shipped from. | Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. |
| Amazon Reference Number (only for WePay Shipments). | Amazon Reference Number as received in the routing instructions (GetShipmentDetails response) for a WePay Shipment. |
Mandatory only for shipment confirmations
(for WePay Shipments). |
Mandatory only for shipment confirmations
(for WePay Shipments). |
Mandatory for Collect Shipments. |
| Purchase Order Number | The Amazon Purchase Order Number. Written authorization for a supplier to ship products at a specified price, which becomes a legally binding contract after the supplier accepts it. | Mandatory on header or line item level. | Mandatory on header or line item level. | Mandatory on header or line item level. |
| Serial Shipping Container Code (SSCC) | Unique 18-digit Serial Shipment Container Code (SSCC) to be included to define a pallet or carton. | Recommended for all shipment confirmations within the packaging unit. | Mandatory for all shipment confirmations within the packaging unit. | Mandatory for all shipment confirmations within the packaging unit. |
| Item Identification | Vendor SKU of the product. | Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. |
| Lot Number | The batch or lot number associates an item with information the manufacturer considers relevant for traceability of the trade item to which the Element String is applied. The data can refer to the trade item itself or to items contained. | Mandatory for Perishable Items. | Mandatory for Perishable Items. | Mandatory for Perishable Items. |
| Expiry Date | The date that determines the limit of consumption or the use of a product. Its meaning is determined based on the trade item context. | Mandatory for Perishable Items. | Mandatory for Perishable Items. | Either Expiry or Manufacturer Date and Shelf Life is required. |
| Manufacture Date | Production, Packaging or Assembly Date determined by the manufacturer. Its meaning is determined based on the trade item context. | Optional | Optional | Either Expiry or Manufacturer Date and Shelf Life is required. |
| Quantity | Number of units shipped for a specific item. | Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. | Mandatory for all shipment confirmations. |
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:
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.
Amazon accepts SSCCs in the following symbology: GS1 128, Code128, C39, C93, ITL25. For more information on GS1 128 standards and implementation, refer to http://www.gs1.eu. To be compliant with Amazon License Plate requirements, an 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.
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:
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
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
SubmitShipmentsImportant
SubmitShipmentsis 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
SubmitShipmentsoperation 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:
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:
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
ProcessingandFailurestatus values for submitted Cancel Shipment requests.
The following diagram shows the integration workflow when submitting shipment requests.
Business requirements
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
GetShipmentDetailsImportant
GetShipmentDetailsis 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.
Business requirements
GetShipmentDetails request
GetShipmentDetails requestTo 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 (
|
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
GetShipmentDetails ResponseResponse 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": "[email protected]",
"code": "string",
"shipmentReferenceNumber": "TRACK001"
},
"billOfLadingNumber": "string"
}
}
]
}
}
GetShipmentLabels
GetShipmentLabelsYou 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.
Business requirements
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 (
|
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
submitInvoicesoperation 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.
Business requirements
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:
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 |
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
submitInvoices use casesInvoice 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/transactions/{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:
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 12 days ago