Marketplaces / Amazon SP API - Technical Scope / Amazon SP API - Vendor Technical Scope / Amazon SP API Vendor Procurement / Amazon Vendor Procurem...

Amazon Vendor Procurement Get Orders

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

Version Date Created / Updated Notes
v1.0 09.02.2024 Bogomil Pavlov First publish
v1.1 14.06.2024 Bogomil Pavlov Get Changed Orders amendments
v1.2 18.06.2024 Hristiyan Georgiev Clarification on how we store shipped orders when address is missing.
v1.3 25.06.2024 Bogomil Pavlov Closed status update
v1.4 15.04.2025 Bogomil Pavlov Additional Logic and mapping for SKU and Buyer mail
v1.5 02.05.2025 Bogomil Pavlov Mapping Changes
v1.6 14.05.2025 Bogomil Pavlov Get Order Status Changes

The Amazon Vendor flow allow us to download new orders for the last 90 days with the “changedAfter” and “changedBefore” parameters. We can get up to 100 orders per page in the response and use the “nextToken” to navigate through the response pages, nothing different form the currently established standards. However Amazon can change the order details any time until the order got shipped and by change the order I mean they can add additional products, change current products quantity and even remove products thus we will have to add addition flow in order to track all order changes initiated from Amazon. To make sure we are getting only changed order we will have to use additional parameter “isPOchanged” in order to filter all the orders. Get orders will be separated into Get New Order and Get Changed Orders since we will be using different request parameters.

The payments will be happening offline and the order will get paid after they are shipped and invoiced thus we want to add a payment row with status pending once the order reach Order Status > “Ready For Shipping”. Please note we may have a case where we have “Ready For Shipping” which is reverted to “Awaiting Acknowledge” in such cases we do not want to make duplicate payment rows.

<v1.6> In order to cover all cases we will need to have 3 separate crons which will do the following: Get New Orders - This will be the cron which will download only new orders Get Changed Orders - This will be responsible for tracking any product in order changes since Amazon can add or change the products Get Order Status Changes- Will be responsible for updating the order statuses to have the consistency between both systems. </v1.6>

All validations, triggers and standardizations which are not mentioned here are as per

Order management general requirements

Get New Orders

The first run of the cron will need to check for orders in the last 90 days and after successful run to store a new record in last_date_run table.

If we already have a record for the specific cron we will need to overlap 90 minutes from the last_date_run > date_created field. Please note Get New Orders will need to download only new order and not updating any existing orders.

API Call: GET /[vendor/orders/v1/purchaseOrders](https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/v1/purchaseOrders?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC&includeDetails=true)

Docs: https://developer-docs.amazon.com/sp-api/docs/vendor-orders-api-v1-reference#get-vendorordersv1purchaseorders

All available parameters:

Name Description
limit The limit to the number of records returned. Default value is 100 records.
Minimum : 1 Maximum : 100
createdAfter Purchase orders that became available after this time will be included in the result. Must be in ISO-8601 date/time format.
createdBefore Purchase orders that became available before this time will be included in the result. Must be in ISO-8601 date/time format.
sortOrder Sort in ascending or descending order by purchase order creation date.
nextToken Used for pagination when there is more purchase orders than the specified result size limit. The token value is returned in the previous API call
includeDetails When true, returns purchase orders with complete details. Otherwise, only purchase order numbers are returned. Default value is true.
changedAfter Purchase orders that changed after this timestamp will be included in the result. Must be in ISO-8601 date/time format.
changedBefore Purchase orders that changed before this timestamp will be included in the result. Must be in ISO-8601 date/time format.
poItemState Current state of the purchase order item. If this value is Cancelled, this API will return purchase orders which have one or more items cancelled by Amazon with updated item quantity as zero.
isPOChanged When true, returns purchase orders which were modified after the order was placed. Vendors are required to pull the changed purchase order and fulfill the updated purchase order and not the original one. Default value is false.
purchaseOrderState Filters purchase orders based on the purchase order state.
orderingVendorCode Filters purchase orders based on the specified ordering vendor code. This value should be same as 'sellingParty.partyId' in the purchase order. If not included in the filter, all purchase orders for all of the vendor codes that exist in the vendor group used to authorize the API client application are returned.

The parameters which we want to use are: includeDetails - always true

nextToken - used for pagination

createdAfter- Either 90 days or 90 minutes earlier from the last_date_run > date_created for this cron

limit - Always 100

Sample Request: GET [https://sellingpartnerapi-na.amazon.com/vendor/orders/v1/purchaseOrders?limit=100&changedAfter=2020-02-15T14:00:00-08:00&createdAfter=2020-02-20T00:00:00-08:00&sortOrder=DESC&includeDetails=true](https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/v1/purchaseOrders?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC&includeDetails=true)

Sample Response: Status 200

"orders": [
                  {
                    "purchaseOrderNumber": "L8266355",
                    "purchaseOrderState": "New",
                    "orderDetails": {
                      "purchaseOrderDate": "2019-05-23T10:00:00Z",
                      "purchaseOrderChangedDate": "2019-05-24T16:05:00Z",
                      "purchaseOrderStateChangedDate": "2019-05-23T10:00:00Z",
                      "purchaseOrderType": "RegularOrder",
                      "importDetails": {
                        "methodOfPayment": "PaidByBuyer",
                        "internationalCommercialTerms": "ExWorks",
                        "portOfDelivery": "YANTIAN, CHINA",
                        "importContainers": "1-40'HC, 1-20'",
                        "shippingInstructions": "PREFERENCE IS PALLET-LOAD, BUT IF CONTAINERS ARE FLOOR-LOADED, THEN PLEASE DO CLAMP-LOAD OR STRAIGHT FLOOR-LOAD. DO NOT USE SLIP SHEET FOR THIS FC DESTINATION. PAYMENT TERMS ARE PER CONTAINER."
                      },
                      "dealCode": "BTS",
                      "paymentMethod": "Invoice",
                      "buyingParty": {
                        "partyId": "ABCD",
                        "address": {
                          "name": "APPARIO RETAIL PVT.LTD.",
                          "addressLine1": "3APPARIO RETAIL PVT.LTD.- C/O. AMAZON SELLER SERVIC",
                          "city": "Siddhapudur",
                          "stateOrRegion": "Tamil Nadu",
                          "postalCode": "641044",
                          "countryCode": "IN",
                          "phone": "206-266-8000"
                        }
                      },
                      "sellingParty": {
                        "partyId": "TEST1"
                      },
                      "shipToParty": {
                        "partyId": "ABCD",
                        "address": {
                          "name": "APPARIO RETAIL PVT.LTD.",
                          "addressLine1": "3APPARIO RETAIL PVT.LTD.- C/O. AMAZON SELLER SERVIC",
                          "city": "Siddhapudur",
                          "stateOrRegion": "Tamil Nadu",
                          "postalCode": "641044",
                          "countryCode": "IN",
                          "phone": "206-266-8000"
                        }
                      },
                      "billToParty": {
                        "partyId": "ABCD",
                        "address": {
                          "name": "APPARIO RETAIL PVT.LTD.",
                          "addressLine1": "3APPARIO RETAIL PVT.LTD.- C/O. AMAZON SELLER SERVIC",
                          "city": "Siddhapudur",
                          "stateOrRegion": "Tamil Nadu",
                          "postalCode": "641044",
                          "countryCode": "IN",
                          "phone": "206-266-8000"
                        }
                      },
                      "taxInfo": {
                        "taxType": "GST",
                        "taxRegistrationNumber": "098522PCA6346DTEDD"
                      }
                    },
                    "deliveryWindow": "2019-05-23T10:00:00Z--2019-05-30T10:00:00Z",
                    "items": [
                      {
                        "itemSequenceNumber": "1",
                        "amazonProductIdentifier": "ABC123434",
                        "vendorProductIdentifier": "028877454078",
                        "orderedQuantity": {
                          "amount": 2,
                          "unitOfMeasure": "Cases",
                          "unitSize": 10
                        },
                        "isBackOrderAllowed": true,
                        "netCost": {
                          "amount": "1800",
                          "currencyCode": "INR"
                        },
                        "listPrice": {
                          "amount": "2000",
                          "currencyCode": "INR"
                        }
                      }
                    ]
                  }
                ]
              }
            }

Mapping:

Amazon Field Hemi Field Comment
orders purchaseOrderNumber Order > Marketplace Order Id
purchaseOrderState Order > Marketplace Status Mapping provided below for our internal status.

<v1.3>Please note we do not want to store old orders with status Closed and cancelled.</v1.3> | | | orderDetails | | | | | | | | | purchaseOrderDate | | | Order > Order Created Time | ISO-8601 date/time format. | | | | purchaseOrderStateChangedDate | | | Order > Order Modified Time | ISO-8601 date/time format. New field within Order with Display Sequence Number under Order Created Time | | | | purchaseOrderType | | | Order Amazon > Purchase Order Type | New field under new tab “Amazon Vendor” RegularOrder A regular purchase order is a method for placing orders for a one-time purchase and payment for line item goods that have a specific quantity and unit price.

ConsignedOrder A consignment purchase order is an agreement with a vendor that allows the product to be received, but the inventory still belong to the vendor until the product is used.

NewProductIntroductionA purchase order where a new product is introduced.

RushOrderRush orders are purchases of goods that need to be processed and delivered by a certain date that is much sooner than the standard arrival date.

However we also want to add a new Order > Order Type value called “Purchase Order” and set every Amazon Purchase Order to this value

| | | | importDetails | | | | | | | | | methodOfPayment | | Order Amazon > Payment Method | New field under new tab “Amazon Vendor” | | | | | internationalCommercialTerms | | Order Amazon >Commercial Terms | New field under new tab “Amazon Vendor” | | | | | portOfDelivery | | Order Amazon > Port of Delivery | New field under new tab “Amazon Vendor” | | | | | importContainers | | Order Amazon > Import Containers | New field under new tab “Amazon Vendor” | | | | | shippingInstructions | | Order Amazon > Shipping Instructions | New field under new tab “Amazon Vendor”

Please note this is a long varchar. | | | | dealCode | | | Order > Discount Code | | | | | paymentMethod | | | Order > Order Payment Method | | | | | buyingParty | | | | | | | | | partyId | | Order > Buyer User ID | | | | | | address | | | | | | | | | name | N/A | | | | | | | addressLine1 | N/A | | | | | | | addressLine2 | N/A | | | | | | | addressLine3 | N/A | | | | | | | city | N/A | | | | | | | county | N/A | | | | | | | district | N/A | | | | | | | stateOrRegion | N/A | | | | | | | postalCode | N/A | | | | | | | countryCode | N/A | | | | | | | phone | N/A | | | | | | taxInfo | | | | | | | | | taxRegistrationType | N/A | | | | | | | taxRegistrationNumber | N/A | | | | | sellingParty | | | | | | | | | partyId | | Order Amazon >Purchase Order Selling Party | New field under new tab “Amazon Vendor” | | | | | address | | N/A | | | | | | | name | N/A | | | | | | | addressLine1 | N/A | | | | | | | addressLine2 | N/A | | | | | | | addressLine3 | N/A | | | | | | | city | N/A | | | | | | | county | N/A | | | | | | | district | N/A | | | | | | | stateOrRegion | N/A | | | | | | | postalCode | N/A | | | | | | | countryCode | N/A | | | | | | | phone | N/A | | | | | | taxInfo | | | | | | | | | taxRegistrationType | N/A | | | | | | | taxRegistrationNumber | N/A | | | | | shipToParty | | | | | | | | | partyId | | Order > Shipping Address ID | Additional mapping will be introduced here if for some reason we are not receiving the address in the payload we want to get it from a new table called “Amazon Delivery Locations” where we want to try and map Order > Shipping Address ID against Amazon Delivery Locations > Location Id and if we have a match we want to get the address from the Amazon Delivery Locations and store it in the order as Shipping Address.

If the shipping address is missing from the payload or we receive more than one and also there is nothing added on the seller we want to set the order as “Incomplete”. <v1.2>This is only valid for unshipped orders. If the order we are downloading already on a Shipped status, we do not want to set it as “Incomplete” but leave it on Shipped.</v1.2.> | | | | | address | | | | | | | | | name | Order > Shipping Buyer Name | If we have missing Order > Shipping Buyer Name we want to get it from Amazon Delivery Locations > Name | | | | | | addressLine1 | Order > Shipping Street 1

| If we have missing Order > Shipping Street 1 we want to get it from Amazon Delivery Locations >Street1 | | | | | | addressLine2 | Order > Shipping Street 2

| If we have missing Order > Shipping Street 2 we want to get it from Amazon Delivery Locations >Street2 | | | | | | addressLine3 | Order > Shipping Street 2

| Concatenate with addressLine2

If we have missing Order > Shipping Street 2 we want to get it from Amazon Delivery Locations >Street2 | | | | | | city | Order > Shipping City | If we have missing Order > Shipping City we want to get it from Amazon Delivery Locations >City | | | | | | county | N/A | | | | | | | district | N/A | | | | | | | stateOrRegion | Order > Shipping State Province | If we have missing Order > Shipping State Province we want to get it from Amazon Delivery Locations > County | | | | | | postalCode | Order > Shipping Postal Code

| If we have missing Order > Shipping Postal Code we want to get it from Amazon Delivery Locations >Postal Code | | | | | | countryCode | Order > Shipping Country Code | Based on the Country Code we want to populate the Order > Shipping Country Name

If we have missing Order > Shipping Country Code we want to get it from Amazon Delivery Locations >Country Code and Amazon Delivery Locations >Country Name | | | | | | phone | Order > Shipping Phone

| If we have missing Order > Shipping Phone we want to get it from Amazon Delivery Locations >Phone | | | | | taxInfo | | | | | | | | | taxRegistrationType | N/A | | | | | | | taxRegistrationNumber | N/A | | | | | billToParty | | | | | | | | | partyId | | Order > Billing Address ID | | | | | | address | | | If the billing address is missing we DO NOT want to get the shipping address | | | | | | name | Order > Billing Name | | | | | | | addressLine1 | Order > Billing Street 1 | | | | | | | addressLine2 | Order > Billing Street 2 | | | | | | | addressLine3 | Order > Billing Street 2 | Concatenate with addressLine2 | | | | | | city | Order > Billing City Name | | | | | | | county | N/A | | | | | | | district | N/A | | | | | | | stateOrRegion | Order > Billing State Province | | | | | | | postalCode | Order > Billing Postal Code | | | | | | | countryCode | Order > Billing Country Code | Based on the Country Code we want to populate the Order > Billing Country Name | | | | | | phone | Order > Billing Phone | | | | | taxInfo | | | | | | | | | taxRegistrationType | | N/A | | | | | | taxRegistrationNumber | | Order > Tax Number | | | | | shipWindow | | | Order > Ship By Date AND Order Amazon > Earliest Ship By Date | This indicates the ship window. Format is start and end date separated by double hyphen (--). For example, 2007-03-01T13:00:00Z--2007-03-11T15:30:00Z.

Since this is a window we want to store the end date in the Order Table and the start date in Orders Amazon. | | | | deliveryWindow | | | Order > Delivery By Date AND Order Amazon > Earliest Delivery By Date | This indicates the delivery window. Format is start and end date separated by double hyphen (--). For example, 2007-03-01T13:00:00Z--2007-03-11T15:30:00Z.

Since this is a window we want to store the end date in the Order Table and the start date in Orders Amazon

New field - Order Amazon > Earliest Delivery By Date under Vendor tab | | | | items | | | | | | | | | itemSequenceNumber | | Product In Order > Order Item Line ID | Numbering of the item on the purchase order. The first item will be 1, the second 2, and so on. | | | | | amazonProductIdentifier | | Product In Order > Channel Item ID | | | | | | vendorProductIdentifier | | Product In Order > SKU <v1.5>AND Product In Order > Item Transaction ID </v1.5> | <v1.4> We want to have additional logic where we want to compare first the vendorProductIdentifier against the Product > SKU and if we have a match we simply store the vendorProductIdentifier as Product in Order > SKU.

If there is no match we want to compare amazonProductIdentifier against the Listing > ChannelItemID and if we have a match to get the Product > SKU and store it as Product In Order > SKU. (We want to get the SKU of the first matched ChannelItemID )

If there is not match again we simply get vendorProductIdentifier as Product In Order > SKU </v1.4> | | | | | orderedQuantity | | | | | | | | | amount | Product In Order > Quantity | | | | | | | unitOfMeasure | N/A | | | | | | | unitSize | N/A | | | | | | isBackOrderAllowed | | Order Item Amazon > Backorder Allowed | New field under new tab “Amazon Vendor” | | | | | netCost | | | | | | | | | currencyCode | Order > Order Currency | We pick the currency from the first Item. ISO 4217 format | | | | | | amount | Product In Order > Item Price | The amount in the payload is Per Quantity

| | | | | listPrice | currencyCode | N/A | | | | | | | amount | N/A | |

Since we wont be receiving the Order > Total Amount and Order > Subtotal Amount we want to calculate it based on the Net Price. We need to calculate the total amount of the order and the subtotal by calculate the total netCost for every item and multiplying the orderedQuantity and SUM it for all items. We also want to add a new Order > Order Type value called “Purchase Order” and set every Amazon Purchase Order to this value.

There will be fields which we would like to set based on the Account setup and if we have activated the Automatic Acknowledgement when we download an order we want to set Order Acknowledgement > Status= Pending with all relevant fields and dependent tables if the Amazon Status = New. If the automatic acknowledgement is set as false when we download an order we do not want to create Order Acknowledgement since it will be manually handled.

<v1.4> Since the buyer email is also missing we want to add additional field in Amazon Delivery Locations called email where if we have a match we want to get the Orders > Buyer mail from the Amazon Delivery Locations > Email. This should apply even if we receive the shipping info from Amazon. </v1.4>

Status Mapping:

Amazon Status Hemi Status Comment
New Awaiting Acknowledge (new status) The purchase order is newly created and needs to be acknowledged by vendor..
Acknowledged Ready For Shipping The purchase order has been acknowledged by vendor.
Closed Shipped/Cancelled <v1.3>The purchase order is closed and no further action is required from the vendor.

PO can be in closed state for many reasons such as order is rejected by vendor, order is cancelled by Amazon or order is fully received by Amazon. The way we can understand if the order Closed and cancelled is we will need to check the order item quantity. If the order is Closed and cancelled we will have for all order items quantity 0. If the order Closed and shipped we will have the relevant quantities for the order items.</v1.3> |

Get Changed Orders

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

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

  • Ship or delivery window change
  • PO item updates such as quantity change, item cancelation, 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

So we want to be able to update all of the above information on already downloaded order.

<v1.6>This will be our get changed orders cron </v.1.6>which will be a separate flow because we will have to set additional parameter when requesting purchase orders. Please note we do NOT want Get Changed Orders to download new orders and<v1.3> we want to ignore all changed orders with state Closed.</v1.3>

API Call: GET /[vendor/orders/v1/purchaseOrders](https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/v1/purchaseOrders?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC&includeDetails=true)

The parameters which we want to use are includeDetails - always true

nextToken - used for pagination createdAfter- Either 90 days or 90 minutes earlier from the last_date_run > date_created for this cron

isPOChanged- When true, returns purchase orders which were modified after the order was placed. Vendors are required to pull the changed purchase order and fulfill the updated purchase order and not the original one. Default value is false.

limit - Always 100

Sample Request: GET [https://sellingpartnerapi-na.amazon.com/vendor/orders/v1/purchaseOrders?limit=100&isPOChanged=true&includeDetails=true](https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/v1/purchaseOrders?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC&includeDetails=true)

Sample Response: Status 200

"orders": [
                  {
                    "purchaseOrderNumber": "L8266355",
                    "purchaseOrderState": "New",
                    "orderDetails": {
                      "purchaseOrderDate": "2019-05-23T10:00:00Z",
                      "purchaseOrderChangedDate": "2019-05-24T16:05:00Z",
                      "purchaseOrderStateChangedDate": "2019-05-23T10:00:00Z",
                      "purchaseOrderType": "RegularOrder",
                      "importDetails": {
                        "methodOfPayment": "PaidByBuyer",
                        "internationalCommercialTerms": "ExWorks",
                        "portOfDelivery": "YANTIAN, CHINA",
                        "importContainers": "1-40'HC, 1-20'",
                        "shippingInstructions": "PREFERENCE IS PALLET-LOAD, BUT IF CONTAINERS ARE FLOOR-LOADED, THEN PLEASE DO CLAMP-LOAD OR STRAIGHT FLOOR-LOAD. DO NOT USE SLIP SHEET FOR THIS FC DESTINATION. PAYMENT TERMS ARE PER CONTAINER."
                      },
                      "dealCode": "BTS",
                      "paymentMethod": "Invoice",
                      "buyingParty": {
                        "partyId": "ABCD",
                        "address": {
                          "name": "APPARIO RETAIL PVT.LTD.",
                          "addressLine1": "3APPARIO RETAIL PVT.LTD.- C/O. AMAZON SELLER SERVIC",
                          "city": "Siddhapudur",
                          "stateOrRegion": "Tamil Nadu",
                          "postalCode": "641044",
                          "countryCode": "IN",
                          "phone": "206-266-8000"
                        }
                      },
                      "sellingParty": {
                        "partyId": "TEST1"
                      },
                      "shipToParty": {
                        "partyId": "ABCD",
                        "address": {
                          "name": "APPARIO RETAIL PVT.LTD.",
                          "addressLine1": "3APPARIO RETAIL PVT.LTD.- C/O. AMAZON SELLER SERVIC",
                          "city": "Siddhapudur",
                          "stateOrRegion": "Tamil Nadu",
                          "postalCode": "641044",
                          "countryCode": "IN",
                          "phone": "206-266-8000"
                        }
                      },
                      "billToParty": {
                        "partyId": "ABCD",
                        "address": {
                          "name": "APPARIO RETAIL PVT.LTD.",
                          "addressLine1": "3APPARIO RETAIL PVT.LTD.- C/O. AMAZON SELLER SERVIC",
                          "city": "Siddhapudur",
                          "stateOrRegion": "Tamil Nadu",
                          "postalCode": "641044",
                          "countryCode": "IN",
                          "phone": "206-266-8000"
                        }
                      },
                      "taxInfo": {
                        "taxType": "GST",
                        "taxRegistrationNumber": "098522PCA6346DTEDD"
                      }
                    },
                    "deliveryWindow": "2019-05-23T10:00:00Z--2019-05-30T10:00:00Z",
                    "items": [
                      {
                        "itemSequenceNumber": "1",
                        "amazonProductIdentifier": "ABC123434",
                        "vendorProductIdentifier": "028877454078",
                        "orderedQuantity": {
                          "amount": 2,
                          "unitOfMeasure": "Cases",
                          "unitSize": 10
                        },
                        "isBackOrderAllowed": true,
                        "netCost": {
                          "amount": "1800",
                          "currencyCode": "INR"
                        },
                        "listPrice": {
                          "amount": "2000",
                          "currencyCode": "INR"
                        }
                      }
                    ]
                  }
                ]
              }
            }

The mapping will be same as above.

In order to handle this correctly we will have to update the order in real time which means we may add new products, update totals, address etc. There will be cases where we want to make additional calculations when “PO item updates such as quantity change, item cancelation, or item cost change” or “New item added to PO” in such cases we want to recalculate the Order >Order Total Amount, Order >Order Subtotal Amount and Order Payment > Total Amount. If we receive a purchase order with missing items because they were removed we want to set the Product in Order > Quantity in Hemi as 0 for the missing order items and update their Internal Payment Status-es as “Fully Refunded”. <v1.1> When we have a cases of changes in the Product in Order > Quantity in any of the order items we want to update all of the Order Item Lines and update them in order to have consecutive Order Item Line > Line Ids for the ones which we no longer have quantity we want to delete them. So basically every time we have quantity drop change we want to delete the lines for the removed quantities and update all of the rest with the consecutive Order Item Line > Line Ids</v1.1> If the removed Item is bundle product in Hemi we will have to keep in mind the components and update their quantity and statuses as well. If the order is updated after we have downloaded it in Hemi we want to set Order Modified Time we want to populate this field only if we modify the order after we download it.

If we receive an updated order which is already acknowledged in Hemi and we have additional product added from Amazon we want to store new product/quantity as not yet acknowledged. In order to allow the user to acknowledge the new product/quantity we will have to revert back the Order > Status from “Ready For Shipping” to “Awaiting Acknowledge” this way we will enable the acknowledge flow and the user can accept/reject only the new product/quantity. It is not as per our standards but this way we allow the user to manipulate the order without any status changes and additional twists. If for some reason Amazon remove product/quantity the expectations are we do not have to make any additional acknowledgment.

Limits:

Rate (requests per second) Burst
10 10

<v1.6> Get Orders Status Changes

The first run of the cron will need to check for order status changes in the last 90 days and after successful run to store a new record in last_date_run table.

If we already have a record for the specific cron we will need to overlap 5 days from the last_date_run > date_created field. Please note Get Order Status Changes will need to update only existing orders and not adding any new orders.

API Call: GET /[vendor/orders/v1/purchaseOrders](https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/v1/purchaseOrders?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC&includeDetails=true)

Docs: https://developer-docs.amazon.com/sp-api/docs/vendor-orders-api-v1-reference#get-vendorordersv1purchaseorders

All available parameters:

Name Description
limit The limit to the number of records returned. Default value is 100 records.
Minimum : 1 Maximum : 100
createdAfter Purchase orders that became available after this time will be included in the result. Must be in ISO-8601 date/time format.
createdBefore Purchase orders that became available before this time will be included in the result. Must be in ISO-8601 date/time format.
sortOrder Sort in ascending or descending order by purchase order creation date.
nextToken Used for pagination when there is more purchase orders than the specified result size limit. The token value is returned in the previous API call
includeDetails When true, returns purchase orders with complete details. Otherwise, only purchase order numbers are returned. Default value is true.
changedAfter Purchase orders that changed after this timestamp will be included in the result. Must be in ISO-8601 date/time format.
changedBefore Purchase orders that changed before this timestamp will be included in the result. Must be in ISO-8601 date/time format.
poItemState Current state of the purchase order item. If this value is Cancelled, this API will return purchase orders which have one or more items cancelled by Amazon with updated item quantity as zero.
isPOChanged When true, returns purchase orders which were modified after the order was placed. Vendors are required to pull the changed purchase order and fulfill the updated purchase order and not the original one. Default value is false.
purchaseOrderState Filters purchase orders based on the purchase order state.
orderingVendorCode Filters purchase orders based on the specified ordering vendor code. This value should be same as 'sellingParty.partyId' in the purchase order. If not included in the filter, all purchase orders for all of the vendor codes that exist in the vendor group used to authorize the API client application are returned.

The parameters which we want to use are: includeDetails - always true

nextToken - used for pagination

createdAfter- Either 90 days or 5 days earlier from the last_date_run > date_created for this cron

limit - Always 100

Sample Request: GET [https://sellingpartnerapi-na.amazon.com/vendor/orders/v1/purchaseOrders?limit=100&createdAfter=2020-02-20T00:00:00-08:00&sortOrder=DESC&includeDetails=true](https://sellingpartnerapi-na.amazon.com/vendor/directFulfillment/orders/v1/purchaseOrders?limit=2&createdAfter=2020-02-15T14:00:00-08:00&createdBefore=2020-02-20T00:00:00-08:00&sortOrder=DESC&includeDetails=true)

Sample Response: Status 200

"orders": [
                  {
                    "purchaseOrderNumber": "L8266355",
                    "purchaseOrderState": "New",
                    "orderDetails": {
                      "purchaseOrderDate": "2019-05-23T10:00:00Z",
                      "purchaseOrderChangedDate": "2019-05-24T16:05:00Z",
                      "purchaseOrderStateChangedDate": "2019-05-23T10:00:00Z",
                      "purchaseOrderType": "RegularOrder",
                      "importDetails": {
                        "methodOfPayment": "PaidByBuyer",
                        "internationalCommercialTerms": "ExWorks",
                        "portOfDelivery": "YANTIAN, CHINA",
                        "importContainers": "1-40'HC, 1-20'",
                        "shippingInstructions": "PREFERENCE IS PALLET-LOAD, BUT IF CONTAINERS ARE FLOOR-LOADED, THEN PLEASE DO CLAMP-LOAD OR STRAIGHT FLOOR-LOAD. DO NOT USE SLIP SHEET FOR THIS FC DESTINATION. PAYMENT TERMS ARE PER CONTAINER."
                      },
                      "dealCode": "BTS",
                      "paymentMethod": "Invoice",
                      "buyingParty": {
                        "partyId": "ABCD",
                        "address": {
                          "name": "APPARIO RETAIL PVT.LTD.",
                          "addressLine1": "3APPARIO RETAIL PVT.LTD.- C/O. AMAZON SELLER SERVIC",
                          "city": "Siddhapudur",
                          "stateOrRegion": "Tamil Nadu",
                          "postalCode": "641044",
                          "countryCode": "IN",
                          "phone": "206-266-8000"
                        }
                      },
                      "sellingParty": {
                        "partyId": "TEST1"
                      },
                      "shipToParty": {
                        "partyId": "ABCD",
                        "address": {
                          "name": "APPARIO RETAIL PVT.LTD.",
                          "addressLine1": "3APPARIO RETAIL PVT.LTD.- C/O. AMAZON SELLER SERVIC",
                          "city": "Siddhapudur",
                          "stateOrRegion": "Tamil Nadu",
                          "postalCode": "641044",
                          "countryCode": "IN",
                          "phone": "206-266-8000"
                        }
                      },
                      "billToParty": {
                        "partyId": "ABCD",
                        "address": {
                          "name": "APPARIO RETAIL PVT.LTD.",
                          "addressLine1": "3APPARIO RETAIL PVT.LTD.- C/O. AMAZON SELLER SERVIC",
                          "city": "Siddhapudur",
                          "stateOrRegion": "Tamil Nadu",
                          "postalCode": "641044",
                          "countryCode": "IN",
                          "phone": "206-266-8000"
                        }
                      },
                      "taxInfo": {
                        "taxType": "GST",
                        "taxRegistrationNumber": "098522PCA6346DTEDD"
                      }
                    },
                    "deliveryWindow": "2019-05-23T10:00:00Z--2019-05-30T10:00:00Z",
                    "items": [
                      {
                        "itemSequenceNumber": "1",
                        "amazonProductIdentifier": "ABC123434",
                        "vendorProductIdentifier": "028877454078",
                        "orderedQuantity": {
                          "amount": 2,
                          "unitOfMeasure": "Cases",
                          "unitSize": 10
                        },
                        "isBackOrderAllowed": true,
                        "netCost": {
                          "amount": "1800",
                          "currencyCode": "INR"
                        },
                        "listPrice": {
                          "amount": "2000",
                          "currencyCode": "INR"
                        }
                      }
                    ]
                  }
                ]
              }
            }

From the response we want to track any status changes purchaseOrderState and process the orders as per our abstraction. For example if we have an order with Awaiting Acknowledgment status in Hemi but the order is actually acknowledged on Amazon Vendor we want to update the status with the relevant fields and add the acknowledgment. </v1.6>

Is this article helpful?
0 0 0