HomeDocumentationCode SamplesAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Orders API v0 Use Case Guide

Improve order inventory synchronization, workflows, and reporting tools.

API Version: v0

What is the Orders API?

Use the Orders API to programmatically retrieve and submit order information. This API is designed to help Selling Partners develop fast and flexible custom applications that facilitate order synchronization, order research, and demand-based decision support tools.

📘

Note

Orders more than two years old will not show in the API response, except for the SG, JP, and AU marketplaces, which support orders from 2016 and after.

For information about authentication and authorization, refer to Authorizing Selling Partner API Applications. For information about regulated orders, refer to the Regulated Orders guide.

Key features

  • Retrieve orders information with filtering criteria: The getOrders operation of the Orders API returns orders created or updated during the time frame or other filtering criteria indicated by the specified parameters. If NextToken is present, it is used to retrieve the orders instead of other criteria.
  • Retrieve specified order information: The getOrder operation of the Orders API returns order information that you specify.
  • Retrieve order item information for the specified order: The getOrderItems operation of the Orders API returns detailed order item information for the order that you specify. If NextToken is provided, it is used to retrieve the next page of order items.
  • Confirm shipment for the specified order: The confirmShipment operation of the Orders API confirms the shipment status for a specified order. It can also be used to edit shipment details of orders that have been shipped.

Tutorial 1: Retrieve orders information with filtering criteria

The getOrders operation of the Orders API returns orders created or updated during the time frame or other filtering criteria indicated by the specified parameters. If NextToken is present, that will be used to retrieve the orders instead of other criteria.

🚧

Warning

The getOrders operation has a systematic delay in data retrieval. Most updated orders data will be available 2 minutes after an order is created or last updated. To ensure that you retrieve the latest orders data, call the operation 2 minutes after the order is created or updated.

Prerequisites

To successfully complete this tutorial, you must have:

To access buyer and shipping address information, you must:

getOrders Request

Call the getOrders operation.

Query parameters

NameDescriptionRequired
CreatedAfterA date used for selecting orders created after (or at) a specified time. Only orders placed after the specified time are returned. You must provide either the CreatedAfter parameter or the LastUpdatedAfter parameter. If both are empty the call is invalid.No
CreatedBeforeA date used for selecting orders created before (or at) a specified time. Only orders placed before the specified time are returned. The date must be in ISO 8601 format.No
LastUpdatedAfterA date used for selecting orders that were last updated after (or at) a specified time. An update is defined as any change in order status, including the creation of a new order. Includes updates made by Amazon and by the seller. The date must be in ISO 8601 format. You must provide either the CreatedAfter parameter or the LastUpdatedAfter parameter. If both are empty the call is invalid.No
LastUpdatedBeforeA date used for selecting orders that were last updated before (or at) a specified time. An update is defined as any change in order status, including the creation of a new order. Includes updates made by Amazon and by the seller. The date must be in ISO 8601 format.No
OrderStatusesA list of OrderStatus values used to filter the results.

Possible values:
- PendingAvailability (This status is available for pre-orders only. The order has been placed, payment has not been authorized, and the release date of the item is in the future.)
- Pending (The order has been placed but payment has not been authorized.)
- Unshipped (Payment has been authorized and the order is ready for shipment, but no items in the order have been shipped.)
- PartiallyShipped (One or more, but not all, items in the order have been shipped.)
- Shipped (All items in the order have been shipped.)
- InvoiceUnconfirmed (All items in the order have been shipped. The seller has not yet given confirmation to Amazon that the invoice has been shipped to the buyer.)
- Canceled (The order has been canceled.)
- Unfulfillable (The order cannot be fulfilled. This state applies only to Multi-Channel Fulfillment orders.)
No
MarketplaceIdsA list of MarketplaceId values. Used to select orders that were placed in the specified marketplaces.br>
Refer to Marketplace IDs for a complete list of marketplaceId values.
Max count : 50
Yes
FulfillmentChannelsA list that indicates how an order was fulfilled. Filters the results by fulfillment channel. Possible values: AFN (Fulfillment by Amazon); MFN (Fulfilled by the seller).No
PaymentMethodsA list of payment method values. Used to select orders paid using the specified payment methods. Possible values: COD (Cash on delivery); CVS (Convenience store payment); Other (Any payment method other than COD or CVS).No
BuyerEmailThe email address of a buyer. Used to select orders that contain the specified email address.No
SellerOrderIdAn order identifier that is specified by the seller. Used to select only the orders that match the order identifier. If SellerOrderId is specified, then FulfillmentChannels, OrderStatuses, PaymentMethod, LastUpdatedAfter, LastUpdatedBefore, and BuyerEmail cannot be specified.No
MaxResultsPerPageA number that indicates the maximum number of orders that can be returned per page. Value must be 1 - 100. Default 100.No
EasyShipShipmentStatusesA list of EasyShipShipmentStatus values. Used to select Easy Ship orders with statuses that match the specified values. If EasyShipShipmentStatus is specified, only Amazon Easy Ship orders are returned.

Possible values:
- PendingSchedule (The package is awaiting the schedule for pick-up.)
- PendingPickUp (Amazon has not yet picked up the package from the seller.)
- PendingDropOff (The seller will deliver the package to the carrier.)
- LabelCanceled (The seller canceled the pickup.)
- PickedUp (Amazon has picked up the package from the seller.)
- DroppedOff (The package is delivered to the carrier by the seller.)
- AtOriginFC (The packaged is at the origin fulfillment center.)
- AtDestinationFC (The package is at the destination fulfillment center.)
- Delivered (The package has been delivered.)
- RejectedByBuyer (The package has been rejected by the buyer.)
- Undeliverable (The package cannot be delivered.)
- ReturningToSeller (The package was not delivered and is being returned to the seller.)
- ReturnedToSeller (The package was not delivered and was returned to the seller.)
- Lost (The package is lost.)
- OutForDelivery (The package is out for delivery.)
- Damaged (The package was damaged by the carrier.)
No
ElectronicInvoiceStatusesA list of ElectronicInvoiceStatus values. Used to select orders with electronic invoice statuses that match the specified values.

Possible values:
- NotRequired (Electronic invoice submission is not required for this order.)
- NotFound (The electronic invoice was not submitted for this order.)
- Processing (The electronic invoice is being processed for this order.)
- Errored (The last submitted electronic invoice was rejected for this order.)
- Accepted (The last submitted electronic invoice was submitted and accepted.)
No
NextTokenA string token returned in the response of your previous request.No
AmazonOrderIdsA list of AmazonOrderId values. An AmazonOrderId is an Amazon-defined order identifier, in 3-7-7 format.
Max count : 50
No
ActualFulfillmentSupplySourceIdDenotes the recommended sourceId where the order should be fulfilled from.No
IsISPUWhen true, this order is marked to be picked up from a store rather than delivered.No
StoreChainStoreIdThe store chain store identifier. Linked to a specific store in a store chain.No

Request example

GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders?
    MarketplaceIds=ATVPDKIKX0DER
    &CreatedAfter=2020-10-10
    &MaxResultPerPage=2

Response

A successful response includes the following:

NameDescriptionRequired
OrdersA list of orders.
Type: Order array
Yes
NextTokenWhen present and not empty, pass this string token in the next request to return the next response page.No
LastUpdatedBeforeA date used for selecting orders that were last updated before (or at) a specified time. An update is defined as any change in order status, including the creation of a new order. Includes updates made by Amazon and by the seller. All dates must be in ISO 8601 format.No
CreatedBeforeA date used for selecting orders created before (or at) a specified time. Only orders placed before the specified time are returned. The date must be in ISO 8601 format.No

Response examples

The following is an example of a general response from the getOrders operation.

{
  "payload": {
    "NextToken": "2YgYW55IGNhcm5hbCBwbGVhc3VyZS4",
    "Orders": [
      {
        "AmazonOrderId": "902-3159896-1390916",
        "PurchaseDate": "2017-01-20T19:49:35Z",
        "LastUpdateDate": "2017-01-20T19:49:35Z",
        "OrderStatus": "Pending",
        "FulfillmentChannel": "SellerFulfilled",
        "NumberOfItemsShipped": 0,
        "NumberOfItemsUnshipped": 0,
        "PaymentMethod": "Other",
        "PaymentMethodDetails": [
          "CreditCard",
          "GiftCertificate"
        ],
        "MarketplaceId": "ATVPDKIKX0DER",
        "ShipmentServiceLevelCategory": "Standard",
        "OrderType": "StandardOrder",
        "EarliestShipDate": "2017-01-20T19:51:16Z",
        "LatestShipDate": "2017-01-25T19:49:35Z",
        "IsBusinessOrder": false,
        "IsPrime": false,
        "IsAccessPointOrder": false,
        "IsGlobalExpressEnabled": false,
        "IsPremiumOrder": false,
        "IsSoldByAB": false,
        "IsIBA": false,
        "ShippingAddress": {
          "Name": "Michigan address",
          "AddressLine1": "1 Cross St.",
          "City": "Canton",
          "StateOrRegion": "MI",
          "PostalCode": "48817",
          "CountryCode": "US"
        },
        "BuyerInfo": {
          "BuyerEmail": "[email protected]",
          "BuyerName": "John Doe",
          "BuyerTaxInfo": {
            "CompanyLegalName": "A Company Name"
          },
          "PurchaseOrderNumber": "1234567890123"
        }
      }
    ]
  }
}

When an order is shipped to a Brazil address, you might also receive additional address fields, (for example, StreetName, StreetNumber, Complement, and Neighborhood) as shown in the following example.

{
      "ShippingAddress": {
        "Name": "Brazil address",
        "AddressLine1": "Street 9 450",
        "AddressLine2": "Suite 30 Central",
        "ExtendedFields": {
          "StreetName": "Street 9",
          "StreetNumber": "450",
          "Complement": "Suite 30",
          "Neighborhood": "Central"
        },
        "City": "Rio de Janeiro",
        "StateOrRegion": "RJ",
        "PostalCode": "48817",
        "CountryCode": "BR"
      } 
}

For more information on when shipping addresses contain extended fields, refer to the Order schema in the Orders API v0 reference.

For a list of possible extended fields, refer to AddressExtendedFields in the Orders API v0 reference.

Tutorial 2: Retrieve order information

The tutorial shows you how to use the getOrder operation of the Orders API to retrieve order information that you specify.

Prerequisites

To successfully complete this tutorial, you must have:

To access buyer and shipping address information, you must:

Request

Parameter Description Required
orderId An Amazon-defined order identifier, in 3-7-7 format.

Type: string

Yes

Request example

GET https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/

Response

A successful response includes the following:

NameDescriptionRequired
OrderOrder information.
Type: Order
Yes

Refer to Order in the API reference for details about the possible objects and properties in an order.

Response example

{
  "payload": {
    "BuyerInfo": {},
    "AmazonOrderId": "026-1520163-6049104",
    "EarliestShipDate": "2022-03-10T00:00:00Z",
    "SalesChannel": "Amazon.co.uk",
    "AutomatedShippingSettings": {
      "HasAutomatedShippingSettings": false
    },
    "OrderStatus": "Canceled",
    "NumberOfItemsShipped": 0,
    "OrderType": "StandardOrder",
    "IsPremiumOrder": false,
    "IsPrime": false,
    "FulfillmentChannel": "MFN",
    "NumberOfItemsUnshipped": 0,
    "HasRegulatedItems": true,
    "IsReplacementOrder": false,
    "IsSoldByAB": false,
    "LatestShipDate": "2022-03-10T23:59:59Z",
    "ShipServiceLevel": "Std UK Dom_1",
    "IsISPU": false,
    "MarketplaceId": "A1F83G8C2ARO7P",
    "PurchaseDate": "2022-03-09T22:03:02Z",
    "IsAccessPointOrder": false,
    "IsBusinessOrder": false,
    "OrderTotal": {
      "CurrencyCode": "GBP",
      "Amount": "20.00"
    },
    "PaymentMethodDetails": [
      "Standard"
    ],
    "IsGlobalExpressEnabled": false,
    "LastUpdateDate": "2022-03-14T22:05:14Z",
    "ShipmentServiceLevelCategory": "Standard"
  }
}

Tutorial 3: Retrieve detailed order item information

The tutorial shows you how to use the getOrderItems operation of the Orders API to retrieve order information that you specify.

Prerequisites

To successfully complete this tutorial, you must have:

To access buyer and shipping address information, you must:

Request

Type Parameter Description Required
Path orderId An Amazon-defined order identifier, in 3-7-7 format.

Type: string

Yes
Query NextToken A string token returned in the response of your previous request.

Type: string

No

Request example

GET https://sellingpartnerapi-na.amazon.com/orders/v0/orders/902-9855239-8990202/orderItems

Response

A successful response includes the following:

NameDescriptionRequired
OrderItemsA list of order items.
Type: OrderItem array
Yes
NextTokenWhen present and not empty, pass this string token in the next request to return the next response page.No
AmazonOrderIdAn Amazon-defined order identifier, in 3-7-7 format.Yes

Response example

{
  "payload": {
      "OrderItems": [
          {
              "TaxCollection": {
                  "Model": "MarketplaceFacilitator",
                  "ResponsibleParty": "Amazon Services, Inc."
              },
              "ProductInfo": {
                  "NumberOfItems": "1"
              },
              "BuyerInfo": {},
              "ItemTax": {
                  "CurrencyCode": "USD",
                  "Amount": "1.13"
              },
              "QuantityShipped": 1,
              "BuyerRequestedCancel": {
                  "IsBuyerRequestedCancel": "false",
                  "BuyerCancelReason": ""
              },
              "ItemPrice": {
                  "CurrencyCode": "USD",
                  "Amount": "11.00"
              },
              "ASIN": "B004RKQM8I",
              "SellerSKU": "AN-M9GI-4QE5",
              "Title": "Sony MDR-ZX100 ZX Series Headphones (White)",
              "IsGift": "false",
              "ConditionSubtypeId": "Acceptable",
              "IsTransparency": false,
              "QuantityOrdered": 1,
              "PromotionDiscountTax": {
                  "CurrencyCode": "USD",
                  "Amount": "0.00"
              },
              "AmazonPrograms": {
                  "Programs": ["SUBSCRIBE_AND_SAVE"]
              },
              "ConditionId": "Used",
              "PromotionDiscount": {
                  "CurrencyCode": "USD",
                  "Amount": "0.00"
              },
              "OrderItemId": "43345934312798"
          }
      ],
      "AmazonOrderId": "902-0300094-5705429"
  }
}

Tutorial 4: Confirm a shipment

This tutorial shows you how to confirm a shipment with the confirmShipment operation after you receive a notification that your order is ready to be fulfilled. You will not need to confirm the shipment if you purchase a shipping label through the Shipping API or buy-shipping UI. The confirmShipment operation supports all use cases that were supported in the Order Fulfillment Feeds, including supporting multiple tracking IDs per order. To submit multiple package tracking IDs, you will need to send multiple requests with the same order ID but different package reference IDs.

Example:

Call OrderID PackageReferenceId
1st Call 902-0300094-570542 101
2st Call 902-0300094-570542 102

The package reference ID supports any positive numerical value and is meant for the purpose of editing a shipment after you have confirmed a shipment. You can submit any numerical value as packageReferenceID and we will store the data. If you need to make an edit to the shipment, submit another confirmShipment operation with the same packageReferenceID. The other shipment details will be edited upon successful submission. If you do not put any ID when you submit, Amazon will automatically assign a packageReferenceID.

Prerequisites

To successfully complete this tutorial, you must have:

If you have been approved for the Direct-to-Consumer Delivery (Restricted) role, you will have access to the confirmShipmentoperation.

Step 1. Confirm a shipment for one order

Call the confirmShipment operation, passing the following parameters:

Path parameters

Parameter Description Required
orderId An Amazon-defined order identifier, in 3-7-7 format.

Type: string

Yes

Body parameters

NameDescriptionRequired
packageDetailProperties of packages
Type PackageDetail
Yes
codCollectionMethodThe cod collection method, support in JP only.
Type CodCollectionMethod
No
marketplaceIdThe unobfuscated marketplace identifier.
Type MarketplaceId
Yes

Request example

POST https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/shipmentConfirmation
{
  "marketplaceId": "ATVPDKIKX0DER",
  "codCollectionMethod": "",
  "packageDetail": {
    "packageReferenceId": "123",
    "carrierCode": "UPS",
    "carrierName": "UPS",
    "shippingMethod": "SHIPPING",
    "trackingNumber": "1Z86V8030385598957",
    "shipDate": "2022-11-30T16:15:30Z",
    "shipFromSupplySourceId": "057d3fcc-b750-419f-bbcd-4d340c60c430",
    "orderItems": [
      {
        "orderItemId": "60696125413094",
        "quantity": 1
      }
    ]
  }
}

Response

Response properties:

HTTP CodeDescriptionSchema
204Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
No Content

For error status codes, descriptions and schemas, refer to Confirm Shipment Error Response.

🌟

Tip

To confirm multiple orders, use the Feeds API v2021-06-30 and pass the POST_ORDER_FULFILLMENT_DATA feed type. For more information, refer to Confirm multiple orders through the Order Fulfillment feed.

Step 2. Edit shipping information for one order

After Step 1, a package is created for the order. You can edit the shipping information like Ship date, Carrier, Shipping service (or Ship method), Tracking ID (supplied by the carrier) by calling the confirmShipment operation again.

Parameters that need to be consistent

To ensure that you are editing the same shipment, do not change the following parameters.

Parameter Description In
orderId An Amazon-defined order identifier, in 3-7-7 format.

Type: string

Path
packageReferenceId A seller-supplied identifier that uniquely identifies a package within the scope of an order. Note that only a positive numeric value is supported."

Type: string

PackageDetail
orderItemId The unique identifier of the order item.

Type: string

ConfirmShipmentOrderItem
quantity The quantity of the item.

Type: integer

ConfirmShipmentOrderItem

Request example

POST https://sellingpartnerapi-eu.amazon.com/orders/v0/orders/205-1725759-9209952/shipmentConfirmation
{
  "marketplaceId": "ATVPDKIKX0DER",
  "codCollectionMethod": "",
  "packageDetail": {
    "packageReferenceId": "123",
    "carrierCode": "USPS",
    "carrierName": "USPS",
    "shippingMethod": "SHIPPING",
    "trackingNumber": "1Z86V8030385598957",
    "shipDate": "2022-11-30T20:15:30Z",
    "shipFromSupplySourceId": "057d3fcc-b750-419f-bbcd-4d340c60c430",
    "orderItems": [
      {
        "orderItemId": "60696125413094",
        "quantity": 1
      }
    ]
  }
}

Response

Response properties:

HTTP CodeDescriptionSchema
204Success.
Headers :
x-amzn-RateLimit-Limit (string) : Your rate limit (requests per second) for this operation.
x-amzn-RequestId (string) : Unique request reference identifier.
No Content

For error status codes, descriptions and schemas, refer to Error responses and schemas.