HomeDocumentationCode SamplesAPI ReferenceAnnouncementsModelsRelease 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 helps you develop custom applications that facilitate order synchronization, order research, and demand-based decision support tools.

📘

Note

Orders more than two years old don't show in the API response, except for the SG, JP, and AU marketplaces, which support orders from 2016 onwards.

For information about 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. NextToken, when provided, overrides other criteria to retrieve orders.
  • 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. Use NextToken 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. You can also use this operation 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. NextToken, when provided, overrides other criteria to retrieve orders.

🚧

Warning

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

Prerequisites for tutorial one

To successfully complete this tutorial, you must have:

To access buyer and shipping address information, you must:

getOrders request

Call the getOrders operation.

getOrders request example

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

getOrders 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 a list of possible extended fields and information on when shipping addresses contain extended fields, refer to 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 for tutorial two

To successfully complete this tutorial, you must have:

To access buyer and shipping address information, you must:

getOrder request example

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

getOrder 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 for tutorial three

To successfully complete this tutorial, you must have:

To access buyer and shipping address information, you must:

getOrderItems request example

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

getOrderItems 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"
              },
              "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 don't 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 must 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. If you need to make an edit to the shipment, submit another confirmShipment operation with the same packageReferenceID. The other shipment details are edited upon successful submission. If you do not put any ID when you submit, Amazon automatically assigns a packageReferenceID.

Prerequisites for tutorial four

To successfully complete this tutorial, you must have:

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

Step 1. Confirm a shipment for one order

Call the confirmShipment operation, passing an orderId in the path and the following parameters in the body:

  • packageDetail
  • codCollectionMethod
  • marketplaceId

confirmShipment request example (shipment confirmation step)

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

confirmShipment response (shipment confirmation step)

For error status codes, descriptions and schemas, refer to confirmShipment.

🌟

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:

  • orderId
  • packageReferenceId
  • orderItemId
  • quantity

confirmShipment request example (shipment information editing step)

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

confirmShipment response (shipment information editing step)

For error status codes, descriptions, and schemas, refer to confirmShipment.

Updated 2 days ago

OSZAR »