CSharpAmazonBusinessAPI 0.1.4

☕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 · Troubleshooting · Status

Installation

Latest version is published on nuget.org. Install with the .NET CLI:

dotnet add package CSharpAmazonBusinessAPI

…or via the legacy Package Manager Console:

Install-Package CSharpAmazonBusinessAPI

…or in your .csproj directly:

<PackageReference Include="CSharpAmazonBusinessAPI" Version="*" />

Targets netstandard2.0 — runs on .NET Framework 4.6.1+, .NET Core 2.0+, and every modern .NET (.NET 5/6/7/8/9/10).

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,
    // Environment = AmazonBusinessCredential.Environments.Sandbox,  // for testing
});

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

Console.WriteLine($"Got {reports.Reports?.Count ?? 0} report(s)");

See Configuration for proxy / sandbox / debug-logging options, Onboard a customer for the OAuth consent flow used during one-time customer onboarding, Troubleshooting when something doesn't behave as expected, 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.

Troubleshooting

400 InvalidInput "Could not match input arguments" in sandbox

Amazon Business's static sandbox does exact parameter matching, not subset matching. Sending any extra query parameter — even a sensible-looking one like marketplaceIds — breaks the match. Each operation has a documented sandbox match block in its OpenAPI spec under responses.200.x-amzn-api-sandbox.static[].request.parameters; send only those parameters with their literal values to get a 200.

Common offenders this SDK fixes automatically:

• Repeated query keys (?foo=a&foo=b) — NSwag's default; sandbox needs csv (?foo=a,b). Handled by CsvArrayRewriteHandler.
• Bare ISO timestamps (2020-07-09T00:00:00) — NSwag's "s" format omits the timezone designator; sandbox needs the trailing Z. Handled by IsoDateTimeRewriteHandler.
• Auto-defaulted marketplaceIds in Documents.GetReports — defaults from your credential's marketplace, but the sandbox doesn't expect it. Pass marketplaceIds: Array.Empty<string>() explicitly to skip the default for sandbox testing.

500 InternalFailure with empty details

Amazon's sandbox returns generic 500s for several scenarios where you'd hope for a clearer error. Check, in order:

1. Role not granted on your sandbox app. Each API requires a specific role (see Roles required per API). Confirm in Solution Provider Portal → your app → Roles. The fastest signal: if some APIs work and others 500, it's role-shaped — APIs sharing a role will fail together.
2. Cart in particular is broken in sandbox. Even with the documented ?region=US and cart-123 values, all Cart ops return 500 InternalFailure. This is an Amazon-side issue (not the SDK); production calls work fine. If you need this fixed, open a ticket via SPP support.
3. Sandbox app not fully provisioned. If every API 500s, the sandbox refresh token may not be properly bound. Email Amazon Business Support with your applicationId and a failed x-amzn-RequestId.

Operations that don't actually work in sandbox (despite Amazon's docs claiming so)

These have no x-amzn-api-sandbox block in their OpenAPI spec — the sandbox doesn't mock them and will always 400:

• ProductSearch.SearchProducts and the rest of Product Search
• ReportingLegacy (Reporting v2021-01-08) — both operations

They work fine against production endpoints. For local validation, hit production with Environment.Production once you have approved production credentials.

Operations not available in sandbox at all

Per Amazon's sandbox docs, three APIs are intentionally not in sandbox because they're destructive:

• connection.Ordering — would place real orders
• connection.Applications.RotateApplicationClientSecretAsync — rotates your real production secret even from a sandbox-context call
• connection.Users.CreateBusinessUserAccountAsync — creates real Amazon Business users

The SDK exposes them; you just need to opt into testing them deliberately against production.

lwa-invalid-parameter-bad-scope on the OAuth consent page

You're sending the customer to https://www.amazon.com/ap/oa (the standard LWA endpoint) instead of https://www.amazon.<tld>/b2b/abws/oauth (the Amazon Business endpoint). Use LwaConsentHelper.BuildBusinessAuthorizationUrl(applicationId, redirectUri, state, country) — not BuildAuthorizationUrl. The Business endpoint takes the SPP applicationId (amzn1.sp.solution.*), not the LWA client_id, and accepts no scope parameter.

"We cannot connect this account" on Amazon's consent page

Your sandbox app doesn't go through the consent flow — the sandbox refresh token is generated directly in SPP (Action → Create token), not via OAuth. The website-authorization workflow is for production customer onboarding, where real Amazon Business admins authorize your app for their org. Sandbox apps lack the registration metadata to consent against real accounts.

NSwag-generated ApiException<ErrorList> leaks into application code

If you see this, you're on a build before the ErrorTranslationHandler was wired in (pre-0.1.1). Upgrade to the current package — non-2xx responses now throw AmazonBusinessException subclasses (InvalidInput / Unauthorized / NotFound / QuotaExceeded / InternalError) carrying StatusCode + ResponseBody + a parsed Amazon-error message.

Push protection blocks git push with "Repository contains secrets"

You committed real LWA credentials. Rotate them in SPP first (they're already exposed). Then either re-create the bad commit without the secret files (git rm --cached <file>, amend or rebase) or use git filter-repo to scrub the file from the entire history. Don't take the "allow this secret" escape hatch — secrets in git history are permanent.

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.