getPurchaseOrders

get https://sellingpartnerapi-na.amazon.com/vendor/orders/v1/purchaseOrders

Returns a list of purchase orders created or changed during the time frame that you specify. You define the time frame using the createdAfter, createdBefore, changedAfter and changedBefore parameters. The date range to search must not be more than 7 days. You can choose to get only the purchase order numbers by setting includeDetails to false. You can then use the getPurchaseOrder operation to receive details for a specific purchase order.

Usage Plan:

Rate (requests per second)	Burst
10	10

The x-amzn-RateLimit-Limit response header returns the usage plan rate limits that were applied to the requested operation, when available. The preceding table indicates the default rate and burst values for this operation. Selling partners whose business demands require higher throughput may have higher rate and burst values than those shown here. For more information, refer to Usage Plans and Rate Limits in the Selling Partner API.

Query Params

limit

int64

1 to 100

The limit to the number of records returned. Default value is 100 records.

createdAfter

date-time

Purchase orders that became available after this time will be included in the result. Must be in ISO-8601 date/time format.

createdBefore

date-time

Purchase orders that became available before this time will be included in the result. Must be in ISO-8601 date/time format.

sortOrder

string

Sort in ascending or descending order by purchase order creation date.

nextToken

string

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

string

When true, returns purchase orders with complete details. Otherwise, only purchase order numbers are returned. Default value is true.

changedAfter

date-time

Purchase orders that changed after this timestamp will be included in the result. Must be in ISO-8601 date/time format.

changedBefore

date-time

Purchase orders that changed before this timestamp will be included in the result. Must be in ISO-8601 date/time format.

poItemState

string

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

string

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

string

Filters purchase orders based on the purchase order state.

orderingVendorCode

string

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.

Responses

Response body

object

payload

object

A list of orders returned as response.

pagination

object

The pagination elements required to retrieve the remaining data.

orders

array of objects

Represents an individual order within the OrderList.

orders

object

purchaseOrderNumber

string

required

The purchase order number for this order. Formatting Notes: 8-character alpha-numeric code.

purchaseOrderState

string

required

This field will contain the current state of the purchase order.

New Acknowledged Closed

Show Details

New	The purchase order is newly created and needs to be acknowledged by vendor.
Acknowledged	The purchase order has been acknowledged by vendor.
Closed	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.

orderDetails

object

Details of an order.

errors

array of objects

A list of error responses returned when a request is unsuccessful.

errors

object

code

string

required

An error code that identifies the type of error that occurred.

message

string

required

A message that describes the error condition.

details

string

Additional details that can help the caller understand or fix the issue.

Headers

object

x-amzn-RateLimit-Limit

string

Your rate limit (requests per second) for this operation.

x-amzn-RequestId

string

Unique request reference identifier.

Language


xxxxxxxxxx
1
curl --request GET \
2
     --url https://sellingpartnerapi-na.amazon.com/vendor/orders/v1/purchaseOrders \
3
     --header 'accept: application/json'


xxxxxxxxxx
140
}
1
{
2
  "payload": {
3
    "pagination": {
4
      "nextToken": "string"
5
    },
6
    "orders": [
7
      {
8
        "purchaseOrderNumber": "string",
9
        "purchaseOrderState": "New",
10
        "orderDetails": {
11
          "purchaseOrderDate": "2025-04-04T09:05:43.576Z",
12
          "purchaseOrderChangedDate": "2025-04-04T09:05:43.576Z",
13
          "purchaseOrderStateChangedDate": "2025-04-04T09:05:43.576Z",
14
          "purchaseOrderType": "RegularOrder",
15
          "importDetails": {
16
            "methodOfPayment": "PaidByBuyer",
17
            "internationalCommercialTerms": "ExWorks",
18
            "portOfDelivery": "string",
19
            "importContainers": "string",
20
            "shippingInstructions": "string"
21
          },
22
          "dealCode": "string",
23
          "paymentMethod": "Invoice",
24
          "buyingParty": {
25
            "partyId": "string",

200Success.

400Request has missing or invalid parameters and cannot be parsed.

403Indicates that access to the resource is forbidden. Possible reasons include Access Denied, Unauthorized, Expired Token, or Invalid Signature.

404The resource specified does not exist.

415The request payload is in an unsupported format.

429The frequency of requests was greater than allowed.

500An unexpected condition occurred that prevented the server from fulfilling the request.

503Temporary overloading or maintenance of the server.