HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQsBlogVideos
Developer HubAPI StatusSupport
Developer HubAPI StatusSupport

Vendor Retail Procurement APIs v1 Use Case Guide

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

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

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

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

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

Business processes you can fulfill using the Vendor Retail Procurement APIs

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

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

What is the Vendor Orders API?

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

The Vendor Orders API includes the following operations:

Operation HTTP Method Path Description
getPurchaseOrders GET /vendor/orders/v1/purchaseOrders Returns a list of purchase orders created or changed during the time frame that you specify. Data retrieval is possible for a maximum period of six months from the date the original POST call is made.
getPurchaseOrder GET /vendor/orders/v1/purchaseOrders /{purchaseOrderNumber} Returns a purchase order (PO) based on the purchaseOrderNumber value that you specify. Data retrieval is possible for a maximum period of six months from the date the original POST call is made.
submitAcknowledgement POST /vendor/orders/v1/acknowledgements Acknowledges (accepts or rejects) one or more purchase orders.
getPurchaseOrdersStatus GET /vendor/orders/v1/purchaseOrdersStatus Returns purchase order statuses based on the filters that you specify. Data retrieval is possible for a maximum period of six months from the date the original POST call is made.

You can use the getPurchaseOrders operation to access orders created or changed during a specified time period (within a rolling window of the last six months, after June 2020). To optimize response time, we recommend that you limit the time range to no more than seven days.

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

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

📘

Note

You can return complete purchase order details by calling the getPurchaseOrders operation, or return only the purchase order numbers with the includeDetails filter. The default value for this parameter is true, so if you don't include this query parameter, you will return the complete details of the purchase orders. If you use includeDetails=false, the response will include only a list of purchase order numbers and the current state of each purchase order.

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

The Vendor orders workflow.

getPurchaseOrders

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

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

Order changes and cancellations

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

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

📘

Note

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

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

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

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

  • Ship or delivery window change
  • PO item updates such as quantity change, item cancellation, or item cost change
  • New item added to PO
  • PO Canceled/Uncanceled
  • PO type change
  • PO Delivery Destination (Fulfillment Center) change
  • PO Freight information change

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

📘

Note

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

Purchase Order State and Vendor Code: The purchase order schema includes the current purchase order state and state update time. You can use the filter purchaseOrderState to filter orders based on the current state.

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

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

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

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

The Vendor orders workflow when retrieving purchase orders.

getPurchaseOrder

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

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

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

The Vendor orders workflow when retrieving a specific purchase order.

Business requirements

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

  • Are backorders acceptable for a line item?

    You must read the value in the isBackOrderAllowed field. When true, the order can be processed as a backorder. When false, backorders are not allowed.

  • Deal codes

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

  • Backorder cancelation policy

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

📘

Note

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

  • Use the API to change an order

    Submitting a change to an order using the API is not possible at this time. After an order has been placed, changing it is a manual process.
    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.

Country specific business requirements

FunctionalityIndiaEuropeNorth America
Net CostConditional, either Net Cost or List PriceConditional, either Net Cost or List PriceConditional, either Net Cost or List Price
List PriceConditional, either Net Cost or List PriceConditional, either Net Cost or List PriceConditional, either Net Cost or List Price
Back OrderNot ApplicableSupportedSupported
Buying PartyThe address of the Amazon Buying EntityThe assigned party ID for the buying partyNot Applicable
Selling PartyThe Amazon Vendor Code assigned to youThe Amazon Vendor Code assigned to the vendorThe Amazon Vendor Code assigned to you
Ship To PartyThe address of the Ship to EntityThe assigned party ID for the ship to partyNot Applicable
Bill to PartyThe address of the Bill to EntityThe address of the Bill to EntityNot Applicable

submitAcknowledgement

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

Amazon expects you to submit the acknowledgement as fast as possible; within 24 hours at the latest. The acknowledgement should be an accurate view of the actual shipment quantities and dates.

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

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

Verification of successfully submitted order acknowledgements

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

The following diagram shows the integration workflow when acknowledging orders.

The Vendor orders workflow when acknowledging orders.

Business requirements

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

    No, you cannot send a higher quantity in the acknowledgement than what was submitted in the purchase order.

  • Is it a requirement to send an order acknowledgement for each purchase order?

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

  • Is it a requirement to provide every PO line item in the corresponding order acknowledgement?

    Yes, so that Amazon can update the order status correctly.

  • If a line item is placed on backorder, is it required to provide the quantity in the order acknowledgement?

    Yes, so that the Amazon system can update the status of the line item correctly.

  • How should invalid or obsolete items on an order be reported using the order acknowledgement?

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

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

📘

Note

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

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

    Acknowledgements must return exactly the same product identifier that was sent in the purchase order.

  • Is it required to provide price in the acknowledgement?

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

  • Can the price in the purchase order be simply returned on the acknowledgement?

    No. Regardless of the price submitted on the purchase order, Amazon requires the cost price in the acknowledgement. The cost price submitted on the acknowledgement should match the cost price submitted in the invoice. Amazon payment systems will compare the two and might delay payment if they do not match.

  • What does Amazon.com 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.com 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 within the EDI system.

  • How will I know if backorders are allowed or not?

    You are required to read the value in the isBackOrderAllowed field in the purchase order. A value of true indicates that backorders are allowed. A value of false indicates that backorders are not allowed.

  • Is it required to provide an acknowledgement code for all line items regardless of status?

    Yes, it is required so we can correctly update the status of the order. If the acknowledgement code is omitted, the acknowledgement will be rejected in our EDI system.

  • What is the policy at Amazon.com on partial shipments? How should partial shipments be reported when submitting an order acknowledgement?

    Partial shipments are allowed. Amazon recommends that you indicate one acknowledgement loop using the code accepted with the corresponding date and another acknowledgement loop using the code backordered and the corresponding date.

    Accepted: For the items that can be fulfilled immediately.

    Backordered: For the remaining quantity that cannot be fulfilled immediately. The remaining quantity (ordered quantity minus all confirmed quantity) will be delivered later (back-ordered).

  • When should I use the listPrice segment?

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

Country specific business requirements

FunctionalityIndiaEuropeNorth America
Scheduled Ship DateConditional, depends on the freight terms and current business arrangement with the youOptionalOptional
Scheduled Delivery DateConditional, depends on the freight terms and current business arrangement with the youOptionalOptional
List PriceNeeded only for Book VendorsSupportedNeeded only for Book Vendors

Get Purchase Orders status

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

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

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

  • You can get the status of all open purchase orders within a specified date range by using either the PO create date (createdBefore and createdAfter) or the PO update date (updatedBefore and updatedAfter) along with purchaseOrderStatus=OPEN.

  • You can use the getPurchaseOrdersStatus operation to filter the status of POs. For example, if itemConfirmationStatus=REJECTED, the response will return all the orders that have one or more items' status as rejected.

  • You can check the status of a specific PO by providing the PO number in the purchaseOrderNumber query parameter.

  • You can get the status of all the open POs raised for a specific vendor code by providing the vendor code value in orderingVendorCode and including purchaseOrderStatus=OPEN.

  • You can get the status of all the POs created in a time range that need to be shipped to a specific Amazon FC by providing the fulfillment center (FC) code in shipToPartyId and the time period range in createdBefore and createdAfter.

Purchase Order and Acknowledgement use cases

Invalid line item in the purchase order

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

Purchase Order

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

Purchase Order Acknowledgement

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

Purchase Order Status

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

Obsolete line item in the purchase order

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

Purchase Order

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

Purchase Order Acknowledgement

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

Confirm partial item quantity and backorder the rest of the quantity

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

Purchase order – (Import Purchase Order)

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

Purchase Order Acknowledgement

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

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

Purchase Order Status

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

Multiple acknowledgements to cancel initially accepted quantities

You can use this when you discover that you can't fulfill some or all of the units of an order that were initially accepted, and you want to inform Amazon that these units will not be shipped.

Purchase Order

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

Purchase Order Acknowledgement

Vendor initially accepted the quantity.

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

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

Full cancellation

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

Partial cancellation

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

Purchase order status after subsequent partial cancellation

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

What is the Vendor Shipments API?

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

The following operations are included in the Shipments API:

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

SubmitShipmentConfirmations

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

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

  • Amazon can collaborate more effectively with carriers in tracking and receiving your shipments. This allows us to effectively plan our labor resources and helps ensure quicker and more efficient receipt of your shipment, which means you can invoice your POs faster.

  • Amazon can keep track of incoming inventory and create automated orders to ensure that items do not go out of stock.

  • Greater visibility into in-transit products, which enables us to more accurately reflect item availability (deliver by period) to end customers.

  • With Amazon's PO cancellation policies, outstanding PO shipments can be canceled. However, POs with accurate shipment confirmation alert our internal systems of in-transit status. This can help avoid unnecessary PO cancellations, chargebacks, and freight refusals.

The lack of a valid shipment confirmations can result in:

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

Shipment Confirmation - Replace

SPAPIDoc-2610_vendor-retail-blog-sunset

When a shipment confirmation has a shipmentConfirmationType of Replace, you can correct previously submitted shipment confirmations by sending an updated version. The second shipment confirmation call will completely overwrite the first shipment confirmation data.

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

How does it work?

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

Scope of Shipment Confirmation - Replace

  • All shipment confirmation values can be edited except for the shipmentIdentifier and sellingParty.partyId, which need to remain identical for a successful Shipment Confirmation - Replace.

  • Pallet, carton, and shipped quantity cannot be increased but only reduced. In order to increase volumes, you must send a second shipment confirmation with a new shipmentIdentifier. You can use the same Bill of Lading (BOL) reference, if the additional units are to be delivered with the same shipment.

  • A shipment confirmation submitted using the API can only be edited by submitting another shipment confirmation using the API. A shipment confirmation created in Vendor Central cannot be edited using the API.

  • Replacing a shipment confirmation is only possible within seven days after the initial shipment confirmation, and then only if the shipment has not yet reached the Amazon fulfillment center.

Verification of successfully submitted shipment confirmations

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

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

The Vendor shipments workflow when submitting shipment confirmations.

Business requirements

  • There is a limit of 100 shipment confirmations for every truckload shipment. 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 (TL) or less than truckload (LTL) shipment. We recommend that you send a single shipment confirmation for the entire TL 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, since appointments are only provided if a valid shipment confirmation is found in the Amazon systems. For exceptions, refer to the local shipment confirmation **Help** pages to understand the available options. For parcels, the shipment confirmation needs to be submitted before items are shipped. Missing or delayed shipment confirmation will result in chargebacks.
    • A shipment confirmation must be for one delivery, from one vendor and for only one truck. Shipments in multiple trucks, to multiple Amazon fulfillment centers, from multiple vendor accounts, or with arrivals on multiple days require multiple shipment confirmations.
    • If several smaller shipments for the same vendor account are combined in a larger shipment, and multiple shipment confirmations are required, you can use the umbrella BOL option as shown in the following example:

    Shipment Confirmation 1

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

    Shipment Confirmation 2

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

    Country specific business requirements

    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 Bill of Lading as a reference number for a shipment.

    		 Conditional

    		Mandatory for all shipment confirmations. Mandatory for TL 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 pure 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. Recommended with Tl or 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 related purchase order 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 every carton, optional for pallets.
    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 (BOL#)

    The Bill of Lading (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#, the BOL:

    • Must be unique for every shipment and cannot be repeated.

    • Can be the physical bill of lading reference, but if it is not, to ensure its uniqueness:

      • Create the BOL# with a minimum of eight digits.

      • Use the Amazon vendor code as a prefix (for example: ABCD193939393).

    • Must not be a date/time.

    Shipment Identification

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

    Shipped Date

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

    Estimated Delivery Date

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

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

    Serial Shipment Container Code (SSCC)

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

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

    For additional details and the requirements for the physical shipment, refer to the License Plate Receive manual in the Vendor Central Resource Center.

    Expiration Date

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

    Manufacturing Date

    The date the goods were packaged or manufactured. This field should be provided if an item is perishable or has a defined shelf life.

    Lot Number

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

    Use of Expiration Date/Manufacturing Date/Lot Numbers in the shipment confirmation

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

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

    • Expiration Dates, Manufacturing Dates, or Lot Numbers must be sent on item level.

    • A case or pallet can have multiple items (ASINs), each with individual Expiration Dates, Manufacturing Dates, or Lot Numbers.

    • One item (ASIN) should not have multiple Expiration Dates, Manufacturing Dates, or Lot Numbers within the same Case or Pallet.

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

    Shipment Confirmation use cases

    Small parcel standard case with expiration and lot numbers

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

    Small LooseAssortmentCase parcel with expiration and lot numbers

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

    Palletized truck load with multiple items

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

    Less than truck load shipment with palletized standard cases

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

    Less than truck load shipment of single ASIN Pallets

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

    GetShipmentDetails

    You can use the GetShipmentDetails operation to retrieve scheduled pickup and carrier assignment information. This operation only returns a response after carrier assignment, which occurs either on the same day as the scheduled pickup or one day prior to the pickup date.

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

    The following diagram shows the Vendor Get shipment integration workflow.

    The Vendor Get shipment workflow.

    Business requirements

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

    Country specific business requirements

    This API operation is available only in NA and EU.

    GetShipmentDetails request

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

    Query parameters:

    Name Description Required
    limit The limit to the number of records returned.

    Type: int

    		 No
    sortOrder Sort the list by shipment creation date in ascending or descending order.

    Type: string

    Type: enum ( SortOrder )

    		No
    nextToken Use for pagination when there are more shipments than the specified result size limit. The token value is returned in the previous API call.

    Type: string

    		 No
    createdAfter Shipments created after this time will be included in the result. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    createdBefore Shipments created before this time will be included in the result. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    shipmentConfirmedBefore Use to provide the date to retrieve Shipment Details of all shipments confirmed before this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    shipmentConfirmedAfter Use to provide the date to retrieve Shipment Details of all shipments confirmed after this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    packageLabelCreatedBefore Use to provide the date to fetch Shipment Details of all shipments for which package labels were created before this date. This field must be in ISO 8601 date/time format.

    Type: string (Boolean)

    		 No
    packageLabelCreatedAfter Use to provide the date to retrieve Shipment Details of all shipments for which package labels were created after this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    shippedBefore Use to provide the date to retrieve Shipment Details of all shipments for which shipped date is before this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    shippedAfter Use to provide the date to retrieve Shipment Details of all shipments for which the shipped date is after this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    estimatedDeliveryBefore Use to provide the date to retrieve Shipment Details of all shipments for which estimated delivery date is before this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    estimatedDeliveryAfter Use to provide the date to retrieve Shipment Details of all shipments with estimated delivery date after this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    shipmentDeliveryBefore Use to provide the date to retrieve Shipment Details of all shipments with shipment delivery date before this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    shipmentDeliveryAfter Use to provide the date to retrieve Shipment Details of all shipments for which shipment delivery date is after this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    requestedPickUpBefore Use to provide the date to retrieve Shipment Details of all shipments for which requested pickup date is before this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    requestedPickUpAfter Use to provide the date to retrieve Shipment Details of all shipments for which requested pickup date is after this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    scheduledPickUpBefore Use to provide the date to retrieve Shipment Details of all shipments for which scheduled pickup date is before this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    scheduledPickUpAfter Use to provide the date to retrieve Shipment Details of all shipments for which scheduled pickup date is after this date. This field must be in ISO 8601 date/time format.

    Type: string (date-time)

    		 No
    currentShipmentStatus Get Shipment Details by passing Current shipment status.

    Type: string

    		 No
    vendorShipmentIdentifier Get Shipment Details by passing Vendor Shipment ID.

    Type: string

    		 No
    buyerReferenceNumber Get Shipment Details by passing buyer Reference ID.

    Type: string

    		 No
    buyerWarehouseCode Get Shipping Details based on buyer warehouse code. This value should be same as the shipToParty.partyId in the Shipment.

    Type: string

    		 No
    sellerWarehouseCode Get Shipping Details based on vendor warehouse code. This value should be same as the sellingParty.partyId in the Shipment.

    Type: string

    		 No

    Request example:

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

    GetShipmentDetails Response

    Response example:

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

    SubmitShipments

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

    📘

    Note

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

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

    Scope of update shipment:

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

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

    Scope of Cancel Shipment:

    • Canceling a shipment request is possible both before and after a carrier has been assigned and routing is scheduled.

    Verification of successfully submitted shipment requests

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

    📘

    Note

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

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

    The Vendor Submit shipment workflow.

    Business requirements

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

    Country specific business requirements

    This operation is only available in NA and EU.

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

    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:

    OperationHTTP MethodPathDescription
    submitInvoicesPOST/vendor/payments/v1/invoicesSubmits one or more vendor invoices to Amazon

    📘

    Note

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

    Submit Invoices

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

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

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

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

    Parallel testing of invoice submission

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

    When you begin sending invoices using the API, the parallel testing phase begins. During the parallel testing phase, you send both paper and API invoices for all orders shipped. You are required to parallel test until the content of at least five to 10 EDI 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 paper invoices. From that moment on, you can process payments by sending invoices using the API.

    Verification of successfully submitted invoices

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

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

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

    Business requirements

    • 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 paper 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 paper and API), then the invoice is canceled, and a new invoice should be sent with a new Invoice ID.

    • No invoice with total amount = 0 should be sent, as this would cause the invoice to fail.

    • Amazon requires the full address details in the address segments for tax compliance reasons. This is especially important for the bill to party. For this segment the Amazon Payee system requires an exact match.

    • 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)

    Country specific business requirements

    Functionality India Europe North America
    Invoice Type Invoice type CreditNote is not supported. Invoice type should always be Invoice. Invoice types Invoice and CreditNote are supported. Vendors need to send the invoice type accordingly. Invoice type CreditNote is not supported. Invoice type should always be Invoice.
    Credit Note References Not used Vendors are required to send these references at the item level if the invoice type is CreditNote. Not used
    Date Must be now or before. Must be now or before. Must be now or before.
    HSN Number The Harmonized System of Nomenclature (HSN) code is mandatory for Tax Compliant Invoices. Maximum length allowed is eight characters. Not used Not used
    Tax Type at line and header level The following are allowed for tax type:
    • SGST & CGST
    • SGST & CGST & CESS
    • UTGST & CGST
    • UTGST & CGST & CESS
    • IGST
    • IGST & CESS

    If no tax information is provided the invoice is rejected.

    		 Tax type to be sent. Not used
    Tax Registration Number A 15 character long GST ID must be provided. VAT Number VAT Number
    Tax Details at line and header level If multiple taxes are applicable for an item, the Tax details section must be sent multiple times with the appropriate tax type for that item.

    The same applies to the total amount of the invoice.

    		 If multiple taxes are applicable for an item, the Tax details section must be sent multiple times with the appropriate tax type for that item.

    The same applies to the total amount of the invoice.

    There is also an additional tax type called DomesticVAT, which can be used to submit the tax amount in the local currency. In order to process the Domestic VAT you must use the same TaxRate used on tax Type VAT.

    		 If multiple taxes are applicable for an item, the Tax details section must be sent multiple times with the appropriate tax type for that item.

    The same applies to the total amount of the invoice.
    Remit To Party The party who supplies goods to Amazon and will get the payment. Also called Supplier. Tax and address details of the party (vendor) who will be receiving payment for the shipped items (in the case of an invoice) or the returned items (in case of a credit note). This is required. Tax and address details of the party (vendor) who will be receiving payment for the shipped items. This is required.
    Ship From Party Ship From Address details, along with the State ISO Code.

    GST ID must be sent in the Tax registration number. Ship From Party is required. Values should match the values in Amazon's systems.

    		 Vendor code or warehouse code and address of the party from where items will be shipped. Vendor code or warehouse code and address of the party from where items will be shipped.
    Ship To Party Ship to Address details along with the State ISO Code. Ship to party is required.

    Values should match the values in Amazon's systems.

    		 Amazon ID or warehouse code and address of the party to which items will be shipped. Amazon ID or warehouse code and address of the party to which items will be shipped.
    Bill to Party Bill to Party is required. It might be same as Ship to party. If so, the vendor is required to send the same information in both segments. Tax and Address details of the party (Amazon) who will be billed for the shipped items (in case of an Invoice) or the returned items (in case of a credit note). For a complete list of Amazon bill to party addresses and JSON code examples, refer to SP-API bill to party addresses.

    This field is required.

    		Tax and Address details of the party (Amazon) who will be billed for shipped items.

    This field is required.

    Amazon Product Identifier and External Product Identifier At least one of these values is required. The identifier must be the same as what is received in order. At least one of those values is required. The identifier must be the same as what is received in order. At least one of those values is required. The identifier must be the same as what is received in order.
    Net Cost This field is required. This field is required. This field is required.
    Purchase Order Number One invoice can contain information for only one order. Therefore the PO number should be the same for all line items in one invoice.

    Required.

    		 One invoice can have information for multiple orders. The PO number should be sent accordingly for different line items. This field is required if the invoice type is Invoice and is not used when the invoice type is CreditNote. One invoice can have information for multiple orders. The PO number should be sent accordingly for different line items.

    Required.
    Additional Details Not used This field is used when the selling party has to submit additional details for special purposes. For example, in the case of Polish split payment invoices, the selling party must send in the detail "mechanizm podzielonej płatności" of type SUR and languageCode "PL". Not used
    referenceNumber A unique invoice reference number generated by Government of India for every invoice. This field is mandatory only for invoices in India. Not used Not used

    Bill to party addresses

    When submitting an invoice, bill to party address details must be complete and formatted correctly, or the API call will fail. If you do not know the Amazon Tax ID for a bill to location, go to Vendor Central and from the Support page, select the Contact Us button to create a case.

    For a complete list of Amazon bill to party addresses and JSON code examples, refer to SP-API bill to party addresses.

    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.
    Credits for freight

    A charge paid for carriage or transportation of goods by air, land, or sea.

    📘

    Note

    Credit notes are not supported in all locations.

    submitInvoices use cases

    Invoice with multiple items with no tax

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

    Invoice with single tax on an item

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

    Invoice with multiple taxes on an item

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

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

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

    EU credit note with tax

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

    What is the Vendor Transaction Status API?

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

    The following operations are included:

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

    Get Transaction Status

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

    Amazon offers the final processed status for POST API transactions such as Order Acknowledgement and Shipment Confirmation via this API. We highly recommend that you check the status using this API to ensure that your transactions were processed successfully. If an error occurs the response will contain error information. You can then correct the transaction and resubmit it.

    Transaction StatusDefinition
    ProcessingThe 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.
    SuccessThis 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.
    FailureThe 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 9 days ago