Orders API Migration Guide

Learn how to migrate order management from the Orders API v0 to the Orders API v2026-01-01.

Benefits

The Orders API v2026-01-01 includes following benefits:

• Reduction in API calls: Consolidated endpoints eliminate the need for multiple calls per order.
• Simplified PII access: Role-based permissions replace Restricted Data Token (RDT) generation.
• Flexible data retrieval: The includedData parameter lets you retrieve only the data you need.
• Enhanced order information: Access to package tracking, detailed financial breakdowns, and new program support.
• Program integration: Support for Amazon Bazaar, Amazon Haul, EasyShip, and Deliver by Amazon programs.
• Pagination: Token handling with 24-hour expiration.

Migration steps

Migrate to v2026-01-01.

Step 1: Assess your current integration

Identify which v0 endpoints your application currently uses:

📘

Note

The searchOrders operation supports the includedData parameter, which allows you to retrieve order items, buyer info, and recipient address data from the searchOrders response without a separate getOrder call. This is useful for bulk order sync workflows.

Step 2: Update application roles for PII access

Restricted Data Tokens (RDTs) are not required to access Personally Identifiable Information (PII) in v2026-01-01. To access PII in v2026-01-01, you only need the appropriate roles assigned.

For more information, refer to Access Orders PII.

Step 3: Refactor API calls with the includedData parameter

Replace multiple v0 calls with single v2026-01-01 calls using the includedData parameter. The includedData parameter determines what data the response includes. Use it with both getOrder and searchOrders.

The less data you request, the better the performance will be.

Step 4: Test and validate

Verify functional parity by comparing v0 vs v2026-01-01 results for the same orders, and plan staged rollouts per seller or per workload.

Order attribute mapping

Map order attributes from the Orders API v0 to the Orders API v2026-01-01.

Query parameter mappings

The following table maps v0 parameters to searchOrders parameters.

Status value mappings

Fulfillment status (formerly order status)

Fulfillment channel

Package Tracking (New in v2026-01-01)

The packages[] array is a new feature providing comprehensive FBM package tracking information.

Boolean flags

In v0, several order characteristics were represented as boolean flags or specific field values. In v2026-01-01, these are consolidated into a programs[] array at either the order level or order item level.

Order-level programs

Order item-level programs

Programs list

The Programs List will continuously be updated with the latest programs supported

Order-level programs (v2026-01-01)

• AMAZON_BAZAAR
• AMAZON_BUSINESS
• AMAZON_EASY_SHIP
• AMAZON_HAUL
• DELIVERY_BY_AMAZON
• FBM_SHIP_PLUS
• IN_STORE_PICK_UP
• PREMIUM
• PREORDER
• PRIME

Order item-level programs (v2026-01-01)

• TRANSPARENCY
• SUBSCRIBE_AND_SAVE

Order-Level attribute mappings

Order attributes (from getOrders and getOrder)

OrderBuyerInfo attributes (from GetOrderBuyerInfo)

OrderAddress attributes (from GetOrderAddress)

Order Item Attribute Mappings

OrderItem attributes (from GetOrderItems)

OrderItemBuyerInfo attributes (from GetOrderItemsBuyerInfo)

Pricing

The pricing structure has changed between v0 and v2026-01-01.

Unit price

v2026-01-01 introduces a new unitPrice attribute that represents the price that displays on the Amazon retail website

Item price tax treatment

Pricing attribute mappings

The v2026-01-01 API introduces a multi-layered financial breakdown structure that replaces the flat monetary values in v0. This provides more granular and actionable financial data.

v0 structure (flat):

{
  "OrderItem": {
    "ItemPrice": { "Amount": "25.00" },
    "ItemTax": { "Amount": "2.00" },
    "ShippingPrice": { "Amount": "5.00" },
    "ShippingTax": { "Amount": "0.40" },
    "PromotionDiscount": { "Amount": "3.00" },
    "PromotionDiscountTax": { "Amount": "0.24" }
  }
}

v2026-01-01 structure (hierarchy):

{
  "orderItems": [{
    "proceeds": {
      "proceedsTotal": { "amount": "29.16", "currencyCode": "USD" },
      "breakdowns": [
        {
          "type": "ITEM",
          "subtotal": { "amount": "25.00", "currencyCode": "USD" }
        },
        {
          "type": "SHIPPING",
          "subtotal": { "amount": "5.00", "currencyCode": "USD" }
        },
        {
          "type": "DISCOUNT",
          "subtotal": { "amount": "3.00", "currencyCode": "USD" },
          "detailedBreakdowns": [
            {
              "subtype": "ITEM",
              "value": { "amount": "3.00", "currencyCode": "USD" }
            }
          ]
        },
        {
          "type": "TAX",
          "subtotal": { "amount": "2.16", "currencyCode": "USD" },
          "detailedBreakdowns": [
            {
              "subtype": "ITEM",
              "value": { "amount": "2.00", "currencyCode": "USD" }
            },
            {
              "subtype": "SHIPPING",
              "value": { "amount": "0.40", "currencyCode": "USD" }
            },
            {
              "subtype": "DISCOUNT",
              "value": { "amount": "0.24", "currencyCode": "USD" }
            }
          ]
        }
      ]
    }
  }]
}