CSharpAmazonBusinessAPI 0.1.2

☕Amazon Business API C# 🚀

.NET C# library for the Amazon Business API. Wraps all 9 REST APIs (Document, Cart, Ordering, Product Search, Reconciliation, Reporting v2025-06-09 + v2021-01-08, User Management, Package Tracking, Application Management) behind a single AmazonBusinessConnection. LWA token refresh, rate-limit retry, regional endpoint routing, sandbox toggle, and debug logging are handled for you.

The generated clients are produced by NSwag from Amazon's published OpenAPI specs (fetched verbatim from developer-docs.amazon.com); the wrapper layer hides the per-spec type duplication so callers see Country.US instead of NSwag-generated Region2/Region3/etc.

Contents — Quick start · Configuration · Service surface · Onboarding (OAuth consent) · Roles · Status

Installation

Install-Package CSharpAmazonBusinessAPI

Quick start

using CSharpAmazonBusinessAPI;
using CSharpAmazonBusinessAPI.Utils;

var connection = new AmazonBusinessConnection(new AmazonBusinessCredential
{
    ClientId     = "amzn1.application-oa2-client.XXXX",
    ClientSecret = "XXXX",
    RefreshToken = "Atzr|XXXX",
    MarketPlace  = MarketPlace.UnitedStates,
});

// First call — token refresh, regional host, auth header are all handled.
var reports = await connection.Documents.GetReportsAsync(
    createdSince: DateTime.UtcNow.AddDays(-7));

See Configuration for proxy / sandbox / debug-logging options, Onboard a customer for the OAuth consent flow used during one-time customer onboarding, and Source/CSharpAmazonBusinessAPI.SampleCode/ for a per-API sample for every wrapper.

Status & roadmap

The roadmap below covers the full Amazon Business developer surface (docs index) and mirrors the structure used in the sister Amazon-SP-API-CSharp project. Foundation work is required before the per-API service wrappers can be built.

Foundation / scaffolding

• MarketPlace / Region / Country lookup tables — 11 supported markets (register-as-a-developer) across 3 regional hosts (ab-api-endpoints): na.business-api.amazon.com, eu.business-api.amazon.com, jp.business-api.amazon.com.
• AmazonBusinessCredential — LWA-only (ClientId, ClientSecret, RefreshToken, MarketPlace / MarketPlaceID, optional Proxy, IsDebugMode, Environment). No AWS keys.
• LWA token pipeline — LwaClient POSTs to https://api.amazon.com/auth/o2/token; per-credential AccessTokenCache (thread-safe via SemaphoreSlim, refreshes 60s before expiry); LwaAuthHandler DelegatingHandler injects x-amz-access-token and retries once on 401.
• LWA client-secret rotation — AmazonBusinessCredential.RotateClientSecret(newSecret) swaps the secret in place and invalidates the cache so the next call re-exchanges.
• AmazonBusinessConnection facade — validates credentials, resolves MarketPlaceID → MarketPlace, builds a configured HttpClient, exposes one property per API surface (Documents, Cart, Ordering, ProductSearch, Reconciliation, Reporting, ReportingLegacy, PackageTracking, Users, Applications).
• HTTP layer for NSwag-generated clients — chained handlers RateLimit → Auth → Debug → HttpClientHandler wrap a shared HttpClient whose BaseAddress comes from MarketPlace.Region. Generated clients consume the HttpClient in their constructor.
• Exception types — AmazonBusinessException base + Unauthorized, InvalidInput, NotFound, QuotaExceeded, InternalError subclasses. Each carries StatusCode + ResponseBody.
• Rate-limit handling — RateLimitHandler DelegatingHandler honors Retry-After (delta or HTTP-date), exponential-backoff fallback, capped by MaxThrottledRetryCount; throws AmazonBusinessQuotaExceededException if exhausted.
• Sandbox toggle — AmazonBusinessCredential.Environment (Sandbox/Production) switches BaseAddress between Region.HostUrl and Region.SandboxHostUrl.
• Debug logging — DebugLogHandler pretty-prints request/response (with masked sensitive headers) when IsDebugMode == true. Routes through ILogger if AmazonBusinessConnection was constructed with an ILoggerFactory, else falls back to Console.

API surfaces

Each API has: (1) OpenAPI spec under Source/CSharpAmazonBusinessAPI/OpenAPIs/ (fetched by scripts/fetch_spec.py), (2) an <OpenApiReference> entry in the csproj, (3) a hand-written *Service wrapper exposed off AmazonBusinessConnection, (4) a sample under Source/CSharpAmazonBusinessAPI.SampleCode/, (5) sandbox-mode tests under Source/Tests/.

• Application Management API v1 — wired as connection.Applications. Single op (RotateApplicationClientSecretAsync) triggers Amazon to deliver a new LWA client secret to the developer's registered SQS queue.
• Cart API v1 — wired as connection.Cart. All 7 operations exposed (List/Get/AddItems/ModifyItems/DeleteItems/GetItems/EstimateCost). Overview · model · sandbox.
• Document API v1 — wired as connection.Documents. Invoice-report retrieval via GetReports/CreateReport/GetReport/CancelReport/GetReportDocument. Region-specific guides: NA invoices, EU/JP invoices. Sandbox.
• Ordering API v1 — wired as connection.Ordering (PlaceOrderAsync, OrderDetailsAsync). Overview. Workflow guides:
  • Placing an order
  • Order safeguards
  • Trial-mode validation
  • Order status retrieval
  • Multi-legal-entity configuration
  • e-Invoicing enablement
  • Delivery preferences
• Package Tracking API v1 — wired as connection.PackageTracking (GetPackageTrackingDetailsAsync). Push notifications are out-of-band (SNS); this API covers pull-based detail retrieval. Overview · push notifications · sandbox.
• Product Search API v1 — wired as connection.ProductSearch. 5 ops with very wide parameter lists (search/get-product/get-offers/by-asin/by-offer-ids); use .Client directly for full IntelliSense. Overview. Workflow guides:
  • Initiating a search
  • Refining results
  • Personalizing searches
  • Product detail pages
  • Guided buying
  • Sample queries, privileged fields, categories
• Reconciliation API v1 — wired as connection.Reconciliation (GetTransactions, GetBatchInvoicePaymentDetails, GetInvoiceDetailsByOrderLineItems). Overview. Workflow guides:
  • Retrieving business transactions
  • Retrieving invoice details
  • Invoice details (JP)
• Reporting API — both versions wired side-by-side; new is default, legacy still callable.
  • Reporting API v2025-06-09 (current) — wired as connection.Reporting (5 ops: order reports, order line items, order reports by PO, shipment reports, shipment line items). Use .Client directly. Model.
  • Reporting API v2021-01-08 (legacy) — wired as connection.ReportingLegacy (GetOrdersByOrderDateAsync, GetOrdersByOrderIdAsync). Model.
• User Management API v1 — wired as connection.Users (CreateBusinessUserAccountAsync). Overview · model.

Workflows & integrations

• REST cross-API sample — see CartToOrderSample.cs for Product Search → Cart → Ordering. Note: Amazon's Integrated Quoting workflow is a separate cXML/cert-auth integration, not a REST workflow — it's out of scope for this SDK.
• Third-party website authorization — LwaConsentHelper.BuildAuthorizationUrl() + ExchangeCodeForTokensAsync(). Use during one-time onboarding to collect a customer's refresh token, then persist it for AmazonBusinessCredential. Runnable demo: see Source/CSharpAmazonBusinessAPI.WebAuthSample — ASP.NET Core minimal-API project with the full consent flow.
• App Center authorization workflow — same LwaConsentHelper.ExchangeCodeForTokensAsync() covers the LWA token-exchange step. The Amazon-initiated callback dance (amazon_callback_uri, amazon_state echoing, step-3 ack POST, step-6 return-to-App-Center redirect) is wired in the demo at /appcenter/login-uri and /appcenter/oauth/callback — see Source/CSharpAmazonBusinessAPI.WebAuthSample for the working reference.
• Punch-in — out of scope (server-side cXML/SOAP-style endpoint your e-procurement system hosts, with TLS certs / shared-secret auth — same situation as Integrated Quoting). See Punch-in integration guide if you need to integrate the e-procurement side.
• Amazon Business Integrations MCP Server — Amazon-hosted MCP server for AI assistants. Out of scope for the SDK; mentioned here for discoverability.

Sample app & tests

• SampleCode/Program.cs loads credentials from appsettings.json + User Secrets and prints the resolved region/host/marketplace. Live calls per API are pre-wired and commented — uncomment after dropping in real credentials.
• Tests/CSharpAmazonBusinessAPI.Tests — xUnit, 41 unit tests + 8 sandbox integration tests (read-only).
  • Unit: MarketPlace lookup + regional routing, AmazonBusinessConnection validation/marketplace resolution, AccessTokenCache (caching, invalidation, concurrent refresh, LWA failure), LwaAuthHandler (header injection, cache reuse, 401 retry-once with fresh token), RateLimitHandler (429 retry, Retry-After delta + HTTP-date, exhaustion → AmazonBusinessQuotaExceededException), RotateClientSecret flow, ApiException shape, LwaConsentHelper URL-builder + arg validation.
  • Integration: SandboxIntegrationTests.cs smoke-tests Documents, Reconciliation, ReportingLegacy, Reporting (GetOrderReports / GetShipmentReports), ProductSearch, Cart, PackageTracking against the real sandbox. Skipped automatically when AB_INTEGRATION_* env vars aren't set. Destructive ops (Ordering.PlaceOrder, Users.CreateBusinessUserAccount, Applications.RotateApplicationClientSecret) are intentionally not tested here — add a separate suite when you opt in.
  • Run with dotnet test (or dotnet test --filter Category=Integration for just the sandbox tests).
• Amazon Business roles reference — see the Roles required per API table in the Usage section. Roles are requested via the Developer Registration Access Form (DRAF) at app creation; the API surface won't authorize without the matching role.

Keys

Amazon Business uses Login with Amazon (LWA) only — no AWS IAM, no STS, no role ARN. Onboarding flow:

1. Register as a developer and request the roles your app needs (Developer Registration Access Form).
2. Create an app client in the Solution Provider Portal — you'll receive a ClientId + ClientSecret.
3. Authorize your app (or use the website-authorization workflow) to obtain a long-lived RefreshToken per Amazon Business customer.

Usage

Configuration

See Program.cs for a runnable example that loads credentials from appsettings.json and User Secrets.

var connection = new AmazonBusinessConnection(new AmazonBusinessCredential
{
    ClientId     = "amzn1.application-oa2-client.XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    ClientSecret = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    RefreshToken = "Atzr|XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    MarketPlace  = MarketPlace.UnitedStates,   // or: MarketPlaceID = "ATVPDKIKX0DER"
    Environment  = AmazonBusinessCredential.Environments.Sandbox,
    IsDebugMode  = true,
});

AmazonBusinessConnection exposes one property per API surface:

Each service exposes typed methods plus a .Client property for direct access to the NSwag-generated client when you need parameters not on the wrapper.

Configuration with a proxy

var connection = new AmazonBusinessConnection(new AmazonBusinessCredential
{
    ClientId = "...", ClientSecret = "...", RefreshToken = "...",
    MarketPlaceID = "ATVPDKIKX0DER",
    Proxy = new System.Net.WebProxy("http://xxx.xxx.xxx.xxx:xxxx")
    {
        Credentials = new System.Net.NetworkCredential("username", "password"),
    },
});

Onboard a customer (OAuth consent → refresh token)

For SaaS apps and App Center listings: send the customer to Amazon's consent page, then exchange the returned code for a long-lived refresh_token and persist it. A runnable end-to-end ASP.NET Core demo lives in Source/CSharpAmazonBusinessAPI.WebAuthSample — dotnet run from that folder, browse to https://localhost:7271, click Connect.

// 1. Generate a CSRF token, then redirect the customer's browser here:
var url = LwaConsentHelper.BuildAuthorizationUrl(
    clientId:    "amzn1.application-oa2-client.XXXX",
    redirectUri: "https://my.app/oauth/callback",
    state:       Guid.NewGuid().ToString());

// 2. On callback, verify state matches, then exchange the code:
var tokens = await LwaConsentHelper.ExchangeCodeForTokensAsync(
    code:         queryParams["code"],
    clientId:     "amzn1.application-oa2-client.XXXX",
    clientSecret: "...",
    redirectUri:  "https://my.app/oauth/callback");

// 3. Persist tokens.RefreshToken for this customer; pass it to AmazonBusinessCredential
//    going forward. (The access_token expires in 1h — the SDK handles renewal automatically.)

LWA client-secret rotation

// 1. Trigger Amazon to send a new secret to your registered SQS queue.
await connection.Applications.RotateApplicationClientSecretAsync();

// 2. After picking up the new secret, swap it in place — the cached access
//    token is invalidated automatically, so the next API call re-exchanges.
connection.Credentials.RotateClientSecret(newSecret);

Document API — list and download invoice reports

For more, see DocumentSample.cs.

// List recent invoice reports (marketplaceIds defaults to credential).
var reports = await connection.Documents.GetReportsAsync(
    createdSince: DateTime.UtcNow.AddDays(-30));

// Create an invoice report, then poll for completion + download.
var reportId = (await connection.Documents.CreateReportAsync(new CreateReportSpecification
{
    ReportType    = "GET_FLAT_FILE_VAT_INVOICE_DATA_REPORT",
    DataStartTime = DateTime.UtcNow.AddDays(-30),
    DataEndTime   = DateTime.UtcNow,
})).ReportId;

var report = await connection.Documents.GetReportAsync(reportId);
if (report.ProcessingStatus == ProcessingStatus.DONE)
{
    var doc = await connection.Documents.GetReportDocumentAsync(report.ReportDocumentId);
    // doc.Url is a 5-minute presigned URL; doc.CompressionAlgorithm == GZIP if compressed.
}

Cart API — list, get, add items

For more, see CartSample.cs. The country parameter defaults to the connection's marketplace — pass Country.X explicitly only to override per call.

// Country defaults from connection.Credentials.MarketPlace.Country.
var carts = await connection.Cart.ListCartsAsync(
    customerEmail: "buyer@example.com",
    pageSize: 25);

await connection.Cart.AddItemsAsync("cart-123", new AddItemsRequest
{
    Items = new List<AddItemRequest>
    {
        new AddItemRequest { ProductIdentifier = "B07HMBFZCZ", Quantity = 2 },
    },
});

Reporting API v2025-06-09

For more, see ReportingSample.cs. The 5 ops have wrapper methods (country defaults from connection); .Client is also there for the raw generated surface.

var orderReports = await connection.Reporting.GetOrderReportsAsync(
    orderStartDate: DateTimeOffset.UtcNow.AddDays(-7),
    orderEndDate:   DateTimeOffset.UtcNow);

Reconciliation API — pull transactions

For more, see ReconciliationSample.cs.

var transactions = await connection.Reconciliation.GetTransactionsAsync(
    feedStartDate: DateTimeOffset.UtcNow.AddDays(-30),
    feedEndDate:   DateTimeOffset.UtcNow);

Package Tracking

For more, see PackageTrackingSample.cs.

// Country defaults from the connection's marketplace.
var details = await connection.PackageTracking.GetPackageTrackingDetailsAsync(
    orderId:    "114-2589187-9801025",
    shipmentId: "401971789238301",
    packageId:  "1");

Product Search

For more, see ProductSearchSample.cs. The two most common ops have wrappers; the other three (SearchOffersRequest, GetProductsByAsins, GetOffersByOfferIds) are reachable via .Client.

var results = await connection.ProductSearch.SearchProductsAsync(
    keywords:      "office chair",
    customerEmail: "buyer@example.com",
    pageSize:      24,
    sortKey:       SortKey.RELEVANCE);

var product = await connection.ProductSearch.GetProductByAsinAsync(
    asin:          "B07HMBFZCZ",
    customerEmail: "buyer@example.com");

Other surfaces

• Ordering — OrderingSample.cs
• Reporting Legacy v2021-01-08 — ReportingLegacySample.cs
• User Management — UserManagementSample.cs
• Application Management — ApplicationManagementSample.cs

Enable debug mode

Set IsDebugMode = true on the credential. Pretty-prints request and response (with sensitive headers masked) for every outbound call. Pass an ILoggerFactory to AmazonBusinessConnection to route through ILogger instead of Console.

Roles required per API

Each API call needs a specific Amazon Business role granted at app-creation time via the Developer Registration Access Form. Calling without the matching role returns 403. (Source.)

All roles are available across NA, EU, and FE marketplaces.

Out of scope: Integrated Quoting

Amazon's Integrated Quoting workflow is a separate cXML over HTTPS integration with digital-certificate auth, used by enterprise eProcurement sourcing modules — it does not use the REST APIs this SDK wraps. If you need that flow, integrate it via your cXML stack alongside this library.