Orders API v2026-01-01: Breaking Changes, Enhanced Features & Call Optimization Strategies🚀

[Tong8s]

The new Orders API v2026-01-01 represents a significant evolution in how developers interact with Amazon order data. With the introduction of usage-based pricing, migrating to this modern API isn't just about accessing new features—it's about dramatically reducing your API call volume through smarter, more efficient data retrieval.

Author: @Tong8s, Solutions Architect, Selling Partner Developer Services

---

⚡ Why Migrate? The Efficiency Advantage

Fewer GET Calls = Better Performance

The most compelling reason to migrate is significant reduction in API call volume. Under the new pricing model, you're charged based on GET call volume. The v2026-01-01 API is specifically designed to help you minimize these calls:

1. 📦 Consolidated Data Retrieval with includedData Parameter

The old Orders v0 API required multiple separate GET calls to retrieve complete order information:

• getOrder - Basic order details
• getOrderItems - Order items (separate call)
• getOrderItemsBuyerInfo - Item buyer info (separate call)

That's up to 3 GET calls per order!

The new v2026-01-01 API consolidates this into a single GET call using the includedData parameter. You can now request all necessary data in one operation:

GET /orders/2026-01-01/orders/{orderId}?includedData=BUYER,RECIPIENT,PROCEEDS,FULFILLMENT,PACKAGES

📊 Call Volume Impact: Reduce API calls by up to 65% for comprehensive order data retrieval.

2. 🔐 No More Restricted Data Tokens (RDT) for PII

The old API required generating a Restricted Data Token before accessing Personally Identifiable Information (PII), adding an extra API call to your workflow. The new API eliminates this requirement—PII access is now controlled through role-based permissions without additional token generation calls. Learn how to access PII data through our official guide.

📊 Call Volume Impact: Eliminate one additional API call per PII data request.

3. 🔍 SearchOrders with Simplified Filtering Mechanism

The new searchOrders API v2026-01-01 reduces filtering complexity from 20+ parameters to 10 core parameters, streamlining developer integration and reducing learning curve. Key improvements include:

• Modular Data Retrieval: The includedData parameter enables selective loading of data sets (BUYER, RECIPIENT, FULFILLMENT, PROCEEDS, EXPENSE, PROMOTION, CANCELLATION, PACKAGES), improving performance and reducing call volume by requesting only necessary information
• Eliminated Specialized Filters: Removes niche parameters (OrderStatuses, PaymentMethods, BuyerEmail, EasyShipShipmentStatuses, delivery date ranges, store-specific filters) in favor of simplified, broadly applicable filters (fulfillmentStatuses, fulfilledBy)
• Clearer Parameter Logic: Enforces mutually exclusive time filters (createdAfter OR lastUpdatedAfter), preventing API misuse and reducing integration errors
• Enhanced Pagination Flexibility: Allows dynamic adjustment of maxResultsPerPage and includedData between pagination calls, optimizing both developer experience and system efficiency
• Performance-First Design: Explicit guidance to request minimal data improves API response times and reduces infrastructure costs at scale

This strategic simplification aligns with modern API design principles—fewer, more powerful parameters that encourage efficient usage patterns while maintaining full functional coverage for order retrieval workflows.

📊 Call Volume Impact: Simplified filtering means fewer exploratory calls. Also, same as getOrder, searchOrders have includedData to reduce volume of extra GET calls.

---

🚀 Enhanced Capabilities Beyond Call Reduction

Simplified Data Access

• Single endpoint for complete data: Use includedData to specify exactly what you need (BUYER, RECIPIENT, PROCEEDS, EXPENSE, PROMOTION, CANCELLATION, FULFILLMENT, PACKAGES)
• Customizable responses: Only request the data you actually use, reducing payload size and processing time

Enhanced Order Information

• Order aliases: Support for seller-defined order identifiers
• New program support: Amazon Bazaar, Amazon Haul, Amazon EasyShip and Deliver by Amazon program identification
• Improved pricing data: Introduces a new attribute unitPrice to indicate selling price in Amazon Retail Website, also introduces structured multi-layer financial breakdowns with proceeds/expense separation and promotion tracking that transforms flat monetary values into actionable business intelligence
• Enhanced package tracking: Comprehensive package information for FBM orders in Order.packages, including carrier, tracking number, and status

Better Fulfillment Management

• Detailed shipping constraints: COD support via shippingConstraints.cashOnDelivery, substitution preferences supported through substitutionPreference with options like CUSTOMER_PREFERENCE, AMAZON_RECOMMENDED, DO_NOT_SUBSTITUTE, plus substitution alternatives, international shipping details supported through including iossNumber for EU VAT compliance
• Improved financial tracking: Detailed proceeds and expense breakdowns with multi-layer structure

Developer Experience Improvements

• Higher precision timestamps: Millisecond-level precision (yyyy-MM-ddTHH:mm:ss.SSSZ) for all date-time fields, enabling more accurate order tracking and synchronization
• Cleaner API design: More intuitive object model and consistent naming conventions
• Better pagination: Enhanced token handling with clear 24-hour expiration
• Comprehensive documentation: Improved guides and examples for faster integration

---

⭐ Full List of API and Attribute Changes

Please refer to our migration guide: https://developer-docs.amazon.com/sp-api/docs/orders-api-migration-guide attribute mapping part

---

🎯 Migration Benefits Summary

Benefit Category	Old API (v0)	New API (v2026-01-01)	Impact
API Calls per Order	3+ separate calls	1 consolidated call	Up to 65% reduction in GET calls
PII Access	Requires RDT generation	Role-based, no token needed	Eliminates extra API call
Data Customization	Fixed response structure	Flexible includedData parameter	Fetch only what you need
Simplification on Filtering	Complex filtering with 20+ parameters spanning order lifecycle, fulfillment, payment, and program-specific states	Shifts to a simplified time-based retrieval model focused on either creation time or update time windows	Cleaner, more predictable query patterns that reduce integration errors and improve performance
Package Tracking	Limited information	Comprehensive FBM package details	Better fulfillment visibility
Program Support	Basic programs	Amazon Bazaar, Amazon Haul, Amazon EasyShip and DeliverBy Amazon programs support	Future-proof integration
Pricing Data	Order-level and OrderItem-level pricing without clear structure and breakdown	Order-level and OrderItem-level pricing are grouped under proceeds attribute with clear breakdowns	Enhanced financial reporting

---

🛠️ Getting Started with Migration

1. Review the new API documentation in the attached user guide
2. Update your application roles to use the new permission model
3. Refactor API calls to use the new searchOrders, getOrder API with consolidated includedData parameter
4. Test thoroughly with the new endpoints
5. Monitor your API usage to verify call volume reduction

For step-by-step migration guidance with postman collection try-out, please check out: Migrate to Orders API v2026-01-01: Complete Developer Guide 🚀

---

💡 The Bottom Line

Migrating to Orders API v2026-01-01 is not just a technical upgrade—it's a strategic efficiency improvement opportunity. By consolidating multiple API calls into single requests and eliminating unnecessary token generation, you can reduce your SP-API call volume by up to 65% while gaining access to enhanced features and better data quality.

With usage-based pricing now in effect, every API call counts. The new Orders API is designed from the ground up to help you do more with less, making it the smart choice for developers who want to maintain excellent service quality while optimizing their API budget.

Start your migration today!

---

📚 Official Documentation & Resources

Now that Orders API v2026-01-01 is officially launched, here are the official resources to help you get started:

Core Documentation

• Orders API v2026-01-01 Announcement - Official launch announcement with key highlights
• Orders API Reference - Complete API specification with endpoints, parameters, and response schemas
• Orders API Migration Guide - Comprehensive migration documentation from v0 to v2026-01-01
• Orders API Use Case Guides - Implementation patterns for common scenarios

Additional Resources

• SP-API Documentation - Complete Selling Partner API documentation hub
• Usage Plans and Rate Limits - Understanding API quotas and throttling
• Selling Partner API Changelog - Latest updates and announcements

---

🆘 Need Help?

Support Channels

• 📖 SP-API Documentation - Comprehensive guides and references
• 💬 GitHub Discussions - Community support and discussions
• 🎫 Developer Support - Official technical support

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:

• ✅ Success stories and positive experiences
• ⚠️ Issues or challenges you encountered
• 💡 Suggestions for improvements
• 📝 Documentation feedback

---

🏷️ Related Topics

• Migrate to Orders API v2026-01-01: Complete Developer Guide 🚀
• Orders API Rate Limits and Throttling

---

Last Updated: January 2026

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.

[RobertThomasSage]

@Tong8s Are the related topics articles that are going to be created, currently it just links to this same discussion as I'm interested in how rate limiting will change between v0 and v2026-01-01 👀

Thanks!

[Tong8s]

Hi @RobertThomasSage ,

Thanks for raising your questions! The links in this doc are fixed. For rate limiting, please see this page: https://developer-docs.amazon.com/sp-api/docs/orders-api-rate-limits.

[ThalesGama]

"Hi team, I am migrating from v0 to v2026-01-01.
I am using the Brazilian marketplace and I need the CPF (buyer's tax ID) to issue the invoice (NF-e).

In v0, I used getOrderBuyerInfo and parsed buyerInfo.payload.BuyerTaxInfo.TaxClassifications[0].Value.

In v2026-01-01, I am using GET /orders/2026-01-01/orders/{orderId}?includedData=buyerInfo.

However, the buyerTaxInfo object is not appearing in the response, even for UNSHIPPED orders and with PII permissions enabled.

Is BuyerTaxInfo still supported in v2026-01-01 for Brazil, or is there a new structure I should use? Thank you!"