Integrated OrderAPI V2026-01-01

[Felix-From]

---

Orders API v2026-01-01 Migration

Summary

Migrates the Orders API from v0 to v2026-01-01 based on the official Amazon SP-API Migration Guide.

The new API consolidates 6 separate endpoints into 2, removes the RDT requirement for PII access, and introduces new features like package tracking and structured financial data.

---

Breaking Changes

• ParameterOrderList marked [Obsolete] – replaced by ParameterSearchOrders
• ParameterGetOrder marked [Obsolete] – replaced by ParameterGetOrder20260101
• ParameterSearchOrders and ParameterGetOrder20260101 no longer inherit from ParameterBased – custom getParameters() that serializes query parameters exactly as the new API expects (camelCase keys, [EnumMember] values, comma-separated collections)
• OrderStatuses → FulfillmentStatuses with new values: Shipped → SHIPPED, Canceled → CANCELLED (double L), PartiallyShipped → PARTIALLY_SHIPPED etc. (UPPER_SNAKE_CASE)
• FulfillmentChannels MFN/AFN → FulfilledBy MERCHANT/AMAZON
• NextToken → PaginationToken – token expires after 24 hours
• Removed v0 parameters: PaymentMethods, BuyerEmail, EasyShipShipmentStatuses, ActualFulfillmentSupplySourceId, IsISPU, SellerOrderId, StoreChainStoreId
• No more RDT: IsNeedRestrictedDataToken and RestrictedDataTokenRequest removed entirely – PII access is now role-based
• Boolean flags removed: IsPrime, IsBusinessOrder, IsPremiumOrder, IsISPU, IsTransparency etc. → programs[] array at order and item level
• Flat pricing fields removed: ItemPrice, ItemTax, ShippingPrice, ShippingTax, PromotionDiscount etc. → hierarchical proceeds.breakdowns[] structure with type/subtype
• SellerOrderId no longer a direct field → Order.OrderAliases with aliasType == "SELLER_ORDER_ID"
• IsReplacementOrder / ReplacedOrderId → Order.AssociatedOrders with associationType

---

Endpoint Consolidation

v0 Operation (deprecated)	v2026-01-01 Operation
GetOrders	searchOrders
GetOrder	getOrder with includedData
GetOrderItems	getOrder (items always included)
GetOrderBuyerInfo	getOrder with includedData=BUYER
GetOrderAddress	getOrder with includedData=RECIPIENT
GetOrderItemsBuyerInfo	getOrder with includedData=BUYER

---

New Features

• includedData parameter: Controls which data is returned (BUYER, RECIPIENT, FULFILLMENT, PROCEEDS, EXPENSE, PROMOTION, CANCELLATION, PACKAGES) – less data = better performance
• Package tracking (includedData=PACKAGES): Carrier, tracking number, status, detailed status, ship time, ship-from address
• New programs: AMAZON_HAUL, AMAZON_EASY_SHIP, DELIVERY_BY_AMAZON, AMAZON_BAZAAR
• unitPrice: Per-unit price as displayed on the Amazon product page
• GetOrderFullAsync() convenience method: Retrieves all data in a single call

---

New / Changed Files

Service & URLs:

• + OrderService20260101.cs – service with SearchOrders + GetOrder
• + OrdersApiUrls20260101.cs – base URL /orders/2026-01-01
• ~ AmazonConnection.cs – added Orders20260101 property

Parameters:

• + ParameterSearchOrders.cs – replaces ParameterOrderList with a standalone getParameters()
• ~ ParameterGetOrder.cs – v0 class marked [Obsolete], added ParameterGetOrder20260101 with standalone getParameters()
• ~ ParameterOrderList.cs – marked [Obsolete]

Models (namespace Orders20260101):

• + Order20260101.cs – Order, OrderAlias, SalesChannel, AssociatedOrder
• + OrderItem20260101.cs – OrderItem, Product, Condition, Price, Customization, Expense, Promotion, Cancellation
• + Fulfillment20260101.cs – OrderFulfillment, OrderItemFulfillment, DateTimeWindow, Packing, Shipping, Picking
• + BuyerRecipient20260101.cs – Buyer, Recipient, DeliveryAddress
• + Proceeds20260101.cs – OrderProceeds, OrderItemProceeds, ProceedsBreakdown, DetailedBreakdown
• + Package20260101.cs – Package, PackageStatus
• + Enums20260101.cs – IncludedData20260101, FulfillmentStatus20260101, FulfilledBy20260101
• + Responses20260101.cs – SearchOrdersResponse, GetOrderResponse20260101, error models
• + Money20260101.cs – Money (Amount + CurrencyCode)

Utils:

• + OrderConverter.cs – OrderProgramInfo / OrderItemProgramInfo helper for programs mapping
• ~ RateLimitType.cs – added rate limit definitions for new endpoints

Samples & Tests:

• + OrdersSample.cs – usage examples covering all new endpoints

---

Migration Notes

• The OrderConverter.OrderProgramInfo() + OrderConverter.OrderProgramInfoEx() utilitys provides a convenient way to extract program flags from the new programs[] array into familiar boolean properties.
  • (Ex)tended = Gets Program Infos from Items aswell.
• Pagination tokens in v2026-01-01 expire after 24 hours – long-running sync jobs need to account for this.
• PII access no longer requires RDT generation. Ensure your application has the appropriate roles assigned before migrating PII workflows.

Quick Guide

GetOrder

var parameter = new ParameterGetOrder20260101
{
    OrderId = "SomeOrderID",
};
var order = amazonConnection.Orders.GetOrder(parameter);

SearchOrder

var parameter = new ParameterSearchOrders
{
    CreatedAfter = DateTime.UtcNow.AddDays(-7),
    FulfillmentStatuses = new List<FulfillmentStatus20260101>
    {
        FulfillmentStatus20260101.SHIPPED
    }
};

var orders = amazonConnection.Orders.SearchOrders(parameter);

FullUsage

var order = amazonConnection.Orders.GetOrderFull("SomeOrderID");

Buyer? BuyerInfo = order?.Buyer;
Recipient? RecipientInfo = order?.Recipient;
OrderFulfillment? FulfillmentInfo = order?.Fulfillment;
OrderProceeds? ProceedsInfo = order?.Proceeds;
// Item Specific Classes (For Demo we use `FirstOrDefault()`
OrderItemExpense? Expenses = order?.OrderItems.FirstOrDefault()?.Expense;
OrderItemPromotion? PromotionInfo = order?.OrderItems.FirstOrDefault()?.Promotion;
OrderItemCancellation? CancellationInfo = order?.OrderItems.FirstOrDefault()?.Cancellation;
List<Package>? PackagesList = order?.Packages.ToList();

OrderConverter.OrderProgramInfo allProgramsInfos = OrderConverter.OrderProgramInfoEx(order); // Extended so ItemProgramInfos is added aswell.
bool isPrime = allProgramsInfos.isPrime;
bool isPremium = allProgramsInfos.isPremium;
bool isInStorePickUp = allProgramsInfos.isInStorePickUp;
bool isFBMShipPlus = allProgramsInfos.isFBMShipPlus;
bool isDeliveryByAmazon = allProgramsInfos.isDeliveryByAmazon;
bool isAmazonHaul = allProgramsInfos.isAmazonHaul;
bool isAmazonEasyShip = allProgramsInfos.isAmazonEasyShip;
bool isAmazonBusiness = allProgramsInfos.isAmazonBusiness;
bool isAmazonBazaar = allProgramsInfos.isAmazonBazaar;
bool isPreorder = allProgramsInfos.isPreorder;

List<OrderConverter.OrderItemProgramInfo> AllOrderItemInfos = allProgramsInfos.orderItems;
foreach (OrderConverter.OrderItemProgramInfo item in AllOrderItemInfos)
{
    bool isTransparent = item.isTransparency;
    bool isSubscribeAndSave = item.isSubscribe_And_Save;
}

Footer

Infos from:

https://developer-docs.amazon.com/sp-api/docs/orders-api-migration-guide
https://developer-docs.amazon.com/sp-api/reference/searchorders
https://developer-docs.amazon.com/sp-api/reference/getorder-3
'+ Some inspiration from the code of the Python Respository:
https://github.com/saleweaver/python-amazon-sp-api/tree/master

Commit Messages Generated by the VS-Plugin (prob. Copilot)

Pull Message Generated by Claude (I suck at long texts so for better readability)

PS: I never did a pull request for a external project so please if something is wired just tell me.

[sonarqubecloud]

Quality Gate passed

Issues
75 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.9% Duplication on New Code

See analysis details on SonarQube Cloud

[ferrumjames]

Is anything pending to get this merged?

[Felix-From]

Sadly i dont know anything about the merge process for this repo.
Personally i give it till tomorrow then i switch to my version to make code adjustments in my projects.
I can't wait until OrdersV0 is depricated, and then start with migration.

Edit 27.03.2026: i am stupid, i misread the email and thought the deprication will be today but it will be turned off on the 27.03.2027. Therefore there is still time to merge it.

[dansharpe83]

@abuzuhri any chance you can give this a check, it looks good i think?

[dansharpe83]

@Felix-From did you end using your own forked branch for this? does it run ok? we are considering forking yours as we want to run with this too

[ddplus-gmbh]

We are currently using the fork of @Felix-From for our own order service. Till now we didn't get any big problems.