Migrate to Orders API v2026-01-01: Interactive Developer Guide 🚀 #253
Replies: 12 comments 19 replies
-
|
Hey @chrisskhoury thanks for this release, great work and much appreciated! Any SDK Support out of the box? We're using the PHP SDK and would love to migrate ASAP but would prefer not to write the raw cURL calls only to have to re-write it back into the SDK again and I don't see mention of SDKs here, is it already parity or is there a timeline on that? |
Beta Was this translation helpful? Give feedback.
-
|
Hey @chrisskhoury Are there any plans for a dynamic sandbox to go with this new API. It’s something that’s currently missing on the orders side of the SP‑API, and it would make writing high quality tests a lot easier!
|
Beta Was this translation helpful? Give feedback.
-
|
Hi @chrisskhoury |
Beta Was this translation helpful? Give feedback.
-
|
@ShaneOH Update 🚀 We have released SP-API SDK v1.7.0, containing the new Orders API v2026-01-01 as well as all other changes from the January release. Make sure to check it out here: https://github.com/amzn/selling-partner-api-sdk/tree/main Best, |
Beta Was this translation helpful? Give feedback.
-
|
Hi @chrisskhoury With the "TaxCollection" object being This attribute is not support in Orders v2026-01-01 yet. Is it expected to use another api to get tax collection information adding additional calls that we didn't have to do before? Or should this be expected to be added before sunset of Orders v0 as the sunset date of one year doesn't give much headroom. |
Beta Was this translation helpful? Give feedback.
-
|
Hi, |
Beta Was this translation helpful? Give feedback.
-
|
Hi, since the "Buyer" data only entails a name and an email address, how are we supposed to use the "Buyer" data to create invoices for the users of our software? Currently I must import an additional feed to guarantee correct and complete information, which I'd love to cut out by getting the full address in the "Buyer" segment of the new API. 99% of our users do not want to use the amazon billing creation but want to create their own. |
Beta Was this translation helpful? Give feedback.
-
|
@chrisskhoury Important to note: this works completely fine: I have reviewed the Swagger model file and used the exact hardcoded sandbox test case values, but continue to receive an "InvalidInput" code with message "Could not match input arguments". Request: Response: Also tried the getOrder, but still same error (also tried with TEST_CASE_200 and TEST_CASE_400 values): I tried different regions, with different values, also using Amazon provided postman collections and environments. I am curious if this supports the sandbox calls or not? |
Beta Was this translation helpful? Give feedback.
-
|
Hey @chrisskhoury , we're in the middle of migrating to this now, but just noticed that the migration guide mentions the removal of the fulfillment source ID?
We don't understand this change -- we have multi-location inventory support and route fulfillment to stock fields properly as such with the old API, so this is a regression for us and would block the migration. We also use the old How are we supposed to handle these two breaking changes? |
Beta Was this translation helpful? Give feedback.
-
|
Nice improvement! One additional enhancement would be helpful: currently, when updating an item's lead_time_to_ship_max_days via a PATCH request to /listings/2021-08-01/items/, the handling time doesn't actually update unless the item's quantity is also provided. It would be great if the handling time could be updated independently of the quantity. |
Beta Was this translation helpful? Give feedback.
-
|
I am trying to send requests of both
GET 'https://sellingpartnerapi-na.amazon.com/orders/2026-01-01/orders?lastUpdatedAfter=2026-04-01T00%3A00%3A00Z&lastUpdatedBefore=2026-04-02T00%3A00%3A00Z&marketplaceIds=ATVPDKIKX0DER&includedData=BUYER%2CRECIPIENT%2CFULFILLMENT%2CPROCEEDS' \
--header 'Accept: application/json' \
--header 'x-amz-access-token: Atza|TOKEN'Error: {
"errors": [
{
"code": "InvalidInput",
"message": "The input you have submitted is not valid. Note that the error may be due to a systematic delay in data retrieval. The most updated data is 2 minutes after an order is created or last updated. If you set the CreatedBefore or LastUpdatedBefore parameters, please provide a date that is at least 2 minutes before current time and try again.",
"details": ""
}
]
}I am using Amazon provide Postman docs to send request, but I still got issue. I also try only pass createdAfter and marketplaceIds and includedData, but I still received error. TimeStamp I try: 2026-04-01T00%3A00%3A00Z and 2026-04-01T00%3A00%3A00.000Z and 2026-04-01T00:00:00Z
GET request 'https://sellingpartnerapi-na.amazon.com/orders/2026-01-01/orders/ORDER_ID?includedData=RECIPIENT%2CFULFILLMENT%2CPACKAGES' \
--header 'Accept: application/json' \
--header 'x-amz-access-token: Atza|TOKEN'Error: {
"errors": [
{
"code": "InternalFailure",
"message": "We encountered an internal error. Please try again.",
"details": ""
}
]
}I also try fewer parameters in includedData. |
Beta Was this translation helpful? Give feedback.
-
|
In the ordersV2026 there is no builder method to call the LWAAuthorizationCredentials to get the access token internally right so we need to make the separate HTTP post call to get the token. Is that correct? |
Beta Was this translation helpful? Give feedback.

Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
Migrate to Orders API v2026-01-01: Interactive Developer Guide 🚀
Every developer using the Orders API v0 needs to migrate to v2026-01-01. This guide walks you through the migration step-by-step with ready-to-run Postman requests at each stage. The new version consolidates multiple endpoints into streamlined operations, reduces API calls by an average of 65%¹, and eliminates the need for Restricted Data Tokens (RDT) for accessing PII.
Authored by: Chris Khoury - Solutions Architect, Selling Partner Developer Services
🎯 Get the Migration Collection
This is an interactive, hands-on migration guide. Instead of just reading about the changes, you can explore them step-by-step using real API calls in Postman. Each section below includes a▶️ Try It button that links directly to pre-configured requests you can run to see the differences between v0 and v2026-01-01 in action.
How it works:
Fork the collection to follow along with this guide:
📖 Need complete attribute mappings? Find the full field-by-field reference in the Orders API Migration Guide on our developer documentation.
💬 Like this interactive format? We'd love to hear your feedback! Let us know if this hands-on approach helped you understand the migration better by emailing orders-api-feedback@amazon.com.
Why Migrate? 💰
The new Orders API isn't just an upgrade with new features, it's also a call-optimization opportunity.
includedDataparameterReal Optimization Impact
Example:
Scenario: Processing 10,000 orders per day with complete order information
Result: 975,000 fewer API calls per month (65% reduction)
Early adopters are already seeing results—one pilot developer who completed a full migration achieved a 53% call reduction over matching year-over-year periods.
¹ Average reduction based on predicted savings for entities worldwide that made over 1MM calls to Orders v0 in 2025, accounting for 99.14% of total call volume.
💡 For more detailed information on the API changes and updates, check out the Orders API v2026-01-01: Breaking Changes, Enhanced Features & Call Optimization Strategies
Step 1: Understand the Consolidation 🔄
The Problem with v0
To get complete order data in v0, you needed 5 separate API calls:
The v2026-01-01 Solution
One call. Everything you need.
This single request returns:
[v0] getOrder→
[v0] getOrderItems→
[v0] getOrderBuyerInfo→
[v0] getOrderAddress→
[v0] getOrderItemsBuyerInfo[v2026-01-01] ✨ getOrder with custom included dataStep 2: Master the
includedDataParameter 🎛️The
includedDataparameter is your main tool for controlling what data you get back.Available Values
BUYERRECIPIENTFULFILLMENTPROCEEDSEXPENSEPROMOTIONCANCELLATIONPACKAGESRecommended Combinations
RECIPIENT,FULFILLMENT,PACKAGES,CANCELLATIONPROCEEDS,EXPENSE,PROMOTIONBUYER,RECIPIENT,FULFILLMENT,PACKAGESFULFILLMENTFulfillment: RECIPIENT,FULFILLMENT,PACKAGES,CANCELLATIONAccounting: PROCEEDS,EXPENSE,PROMOTIONSupport: BUYER,RECIPIENT,FULFILLMENT,PACKAGESStep 3: Update Your Search/Sync Workflows 🔍
Parameter Changes
Parameters are now camelCase:
MarketplaceIdsmarketplaceIdsLastUpdatedAfterlastUpdatedAfterMaxResultsPerPagemaxResultsPerPageNextTokenpaginationTokenOrderStatusesfulfillmentStatusesFulfillmentChannelsfulfilledByStatus Values
Values are now SCREAMING_SNAKE_CASE:
UnshippedUNSHIPPEDPartiallyShippedPARTIALLY_SHIPPEDShippedSHIPPEDCanceledCANCELLEDPendingPENDINGFulfillment Channel Values
MFNMERCHANTAFNAMAZONBoolean Flags → Programs Array
IsPrime = true"PRIME"IsBusinessOrder = true"AMAZON_BUSINESS"IsPremiumOrder = true"PREMIUM"IsISPU = true"IN_STORE_PICK_UP"New in v2026-01-01 🆕
programs[] = "AMAZON_BAZAAR"programs[] = "AMAZON_HAUL"orderItems[].product.price.unitPricepackages[]Deprecated⚠️
ShipServiceLevel,OrderChannel,IsGlobalExpressEnabled,IsSoldByABExample: Before & After
v0:
v2026-01-01:
[v0] getOrders - Basic[v2026-01-01] ✨ searchOrders - Complete[v0] Get Unshipped FBM Orders[v2026-01-01] ✨ Search Unshipped FBM OrdersStep 4: Migrate Real Workflows 🔄
Here are complete before/after patterns for common scenarios.
Pattern A: Daily Order Syncs
Pattern B: Order Detail Syncs
Pattern C: Fulfillment Queue Sync
Pattern A: Daily SyncPattern B: Order DetailPattern C: FBM QueueStep 5: Verify Before Go-Live ✅
Before switching production traffic, verify:
Official Documentation & Resources 📚
Now that Orders API v2026-01-01 is officially launched, here are the official resources:
Core Documentation
Additional Resources
Need Help? 🆘
Support Channels
Feedback & Suggestions 💭
We want to hear from you! Your feedback helps us improve the Orders API and our documentation.
📧 Email us at: orders-api-feedback@amazon.com
Share:
Did This Guide Help You?
Let us know what worked and what didn't! Send your feedback to orders-api-feedback@amazon.com.
Keywords: Orders API, Migration, v2026-01-01, SP-API, Postman, includedData, Call Optimization
Please note the publication date above. While we strive to keep our content current, the rapid evolution of this topic means some details may have changed since publication. For the most up-to-date information, we encourage readers to follow the announcements in SP-API developer documentation.

Last Updated: January 2026
4 votes ·
Beta Was this translation helpful? Give feedback.
All reactions