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.
-
|
Hello @ShaneOH! Glad you like it, what do you think of this guide? Do you find it helpful? Regarding the SDK, YES! We are planning to launch the New Orders API to the SDK very soon! Will update you here once we do :) Best, |
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.
-
|
Hey Robert! :) This is a good callout, let me check with the builder team if there is something in the making. I will keep you updated with new information. Thanks! |
Beta Was this translation helpful? Give feedback.
-
|
Hi @chrisskhoury |
Beta Was this translation helpful? Give feedback.
-
|
Hello @nhupham-commonservices ! You're right - they're different fields. ShipServiceLevel (e.g., "Std US D2D Dom") → ❌ Deprecated, no equivalent In v2026-01-01, only the category-level fulfillmentServiceLevel is available. The granular ShipServiceLevel details are not exposed. If you need detailed service info:
I will also share this feedback with the builder team:) Thank you, Chris Khoury |
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 , I am migrating from v0 to v2026-01-01. In v0, I used getOrderBuyerInfo and parsed buyerInfo.payload.BuyerTaxInfo.TaxClassifications[0].Value and the payment details from the order payload. In v2026-01-01, I am using: However, the buyerTaxInfo object is not appearing in the response, even for UNSHIPPED orders and with PII permissions enabled. Is BuyerTaxInfo and PaymentExecutionDetail still supported in v2026-01-01 for Brazil, or is there a new structure I should use? Thank you! |
Beta Was this translation helpful? Give feedback.
-
|
Hello again @ThalesGama :) We know this is critical for BR sellers so I want to give you a clear picture. On On Quick fix on your request: What to do now: The v0 endpoints will remain available during this transition, and the goal is to close these gaps in v2026-01-01 before v0 is sunset. We'll update this thread when there's news on timing |
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 @RobertThomasSage, I am facing the exact same issue for the Brazilian marketplace. Did you manage to find a solution or a workaround to get the TaxCollection information in v2026-01-01, or are you still relying on v0? Thanks |
Beta Was this translation helpful? Give feedback.
-
|
Hi both! You're right that The intent is to have parity on compliance-critical attributes like these before v0 is removed. We're treating tax-related fields as a priority precisely because of the invoicing and compliance dependencies in marketplaces like BR and TR What to do in the meantime: You do not need a separate API for this. Once We'll update this thread when there's more to share on timing. Thanks for flagging this, it helps us prioritize :) Best, |
Beta Was this translation helpful? Give feedback.
-
|
Hi, |
Beta Was this translation helpful? Give feedback.
-
|
Hello, in fact, confirmShipment doesn't exist yet; the documentation doesn't mention its replacement. |
Beta Was this translation helpful? Give feedback.
-
|
Correct! Thanks @ThalesGama haha you nailed it! stay tuned :) |
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.
-
|
Hello @KhorneHoly Have you tried using the Reports API to fetch Invoicing Reports? These reports have attributes there that should be able to help you. Here is the link: https://developer-docs.amazon.com/sp-api/docs/report-type-values-invoice-data Best, |
Beta Was this translation helpful? Give feedback.
-
|
@chrisskhoury We're currently using a report for that. But I don't get why this is the only solution provided. We're already fetching the orders, so why isn't there an option to add the buyer information into new API? Would decrease the amount of reports that would be needed. |
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.
-
|
It worked. I had to provide the params exactly the same mentioned in the swagger model, also the the sequence of includedData matters. Following curl worked perfectly; Changes I made are below; |
Beta Was this translation helpful? Give feedback.
-
|
Correct, Thanks @abdul-mangrio and apologies for the late reply here. Orders API only supports static sandbox which means only the sandbox requests defined in the swagger model will produce the static response. Any other input will result in a 4xx error. You should test using the same sandbox requests defined in the Swagger model file. Best, |
Beta Was this translation helpful? Give feedback.
-
|
Thanks @chrisskhoury, actually, Colombini, Kozue from Amazon assisted by replying to the email I sent to |
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.
-
|
Hello @ShaneOH , Let me look into this with the product team and get back to you. Best, |
Beta Was this translation helpful? Give feedback.
-
|
@chrisskhoury any updates on this? |
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.
-
|
Hi @umairge66! Thanks for the feedback! For the listings question, have you already tried using the Best, |
Beta Was this translation helpful? Give feedback.
-
|
nope used replace in op, let me try it I will let you know |
Beta Was this translation helpful? Give feedback.
-
I tried merge but |
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