Gentic Amazon — Documentation

1. Getting Started

Sign Up & Get Your API Key

Before you can use Gentic Amazon, you need an API key to authenticate your requests.

1. Go to gentic.co/amazon and create an account.
2. Create an organization from your dashboard. API keys and billing are scoped to the organization.
3. Generate an API key and use it as a Bearer token in your MCP client.

2. Connecting to the MCP Server

The server is available at https://mcp.gentic.co/amazon. For Claude Code:

claude mcp add gentic-amazon \
  --transport http \
  https://mcp.gentic.co/amazon \
  --header "Authorization: Bearer YOUR_API_KEY"

For Claude Web and ChatGPT you can also connect via OAuth — no API key needed. See the connect section on the landing page for other MCP clients (n8n, OpenClaw).

3. Agent Skill

For the best results, pair the MCP server with the Gentic Amazon agent skill. The MCP server gives your agent tool access; the skill teaches it the optimal workflow order. Both the raw SKILL.md and a ready-to-upload .skill bundle are generated on demand from the live manifest, so they always reflect the current tools and pricing.

Add the skill directly via URL:

https://gentic.co/amazon/SKILL.md

Or upload a .skill bundle to Claude Managed Agents:

https://gentic.co/amazon/gentic-amazon.skill

Download this file and upload it wherever Claude Managed Agents asks for a .skill file. It's a zip bundle generated on demand from the latest SKILL.md.

4. When to Apply

• User wants to check whether their Amazon Seller account is connected and which marketplaces it covers.
• User wants their agent to pull recent Amazon orders or the line items on a specific order.
• User wants aggregated sales metrics — units ordered, order count, total sales, average price — over a date range.
• User wants to know which SKUs or ASINs are low on FBA stock (fulfillable, inbound, reserved quantities).
• User wants Amazon financial events — shipments, refunds, fees, adjustments, ads — over a window.
• User wants Brand Analytics data (search-query performance, search terms, catalog performance) or a bulk export loaded into a queryable table.
• User wants their Amazon seller data available to an agent for analysis rather than exported by hand from Seller Central.

5. Workflow

1. 1. Connect once, then work without credentials

   The Amazon server sources the connection from the org's saved Selling Partner API credentials (Gentic dashboard → Integrations → Amazon). The user pastes their LWA client ID, client secret, and refresh token once and picks a default marketplace; the secrets are encrypted at rest and the server resolves the connection on every call. Your agent never passes a credential — it just asks for data. Start with `amazon_connection_status`: it returns `{ connected: false }` when nothing is connected (tell the user to connect in the dashboard) and otherwise lists the marketplaces the account participates in.

2. 2. Read orders with get_amazon_orders

   `get_amazon_orders` lists orders over a date window and status, or returns a single order's line items when you pass `order_id`. It defaults to the last 30 days. Use `last_updated_after` rather than `created_after` to catch orders whose status changed (e.g. shipped) without re-listing everything. Buyer PII (name, address) requires extra Amazon authorization and is omitted in v1 — don't promise it. It's paginated; follow `next_token` for more.

3. 3. Summarize sales with get_amazon_order_metrics

   `get_amazon_order_metrics` returns aggregated sales — ordered units, order count, total sales, average unit price — bucketed by Hour, Day, Week, Month, Year, or Total. It defaults to the last 14 days at Day granularity. For Day-and-larger granularity Amazon requires a timezone (`granularity_timezone`, an IANA name like America/Los_Angeles) — set it so buckets align to the seller's day. Reach for this over listing every order when the user wants a trend, not individual transactions.

4. 4. Check stock with get_amazon_fba_inventory

   `get_amazon_fba_inventory` returns FBA inventory summaries per SKU/ASIN for a marketplace — fulfillable, inbound, reserved, and researching quantities — optionally filtered to specific `seller_skus`. Use it to answer "what's about to run out" or "what's stuck inbound." It's paginated; follow `next_token` to walk the full catalog.

5. 5. Read finances with get_amazon_financial_events

   `get_amazon_financial_events` returns financial events — shipments, refunds, fees, adjustments, ads — over a date window (defaults to the last 30 days), with per-category counts plus the raw events, paginated. It's the API view for recent activity. When the user wants a flat, tabular finances export to analyze in bulk, use the settlement report through the report tools instead.

6. 6. Request a report with request_amazon_report

   `request_amazon_report` submits an Amazon report for generation and returns a `report_id` — it does not return data directly (Amazon generates reports asynchronously). Supported types include the Brand Analytics search-query, search-terms, and catalog-performance reports, the all-orders flat file, and the merchant-listings report. Brand Analytics reports need `report_options` (e.g. SQP: `{ asin, reportPeriod: 'WEEK' }`) and, for a WEEK period, a Sunday→Saturday window and a single marketplace. Requesting is free.

7. 7. Load it with get_amazon_report

   `get_amazon_report` polls the `report_id` from `request_amazon_report`. While Amazon is still generating it you get a status back (free); once it's DONE the rows are written into a SQL-queryable data lakehouse table and you get `{ table, row_count }`. Poll until done, then query the table for analysis. Loading is billed per row written, so it scales with the report's size.

8. 8. Present results clearly

   Don't dump raw API JSON or whole report files. Summarize the numbers the user asked for — "412 units across 380 orders last week, $9,840 in sales" — call out what's actionable (SKUs low on stock, a refund spike), and when a report loads, name the table and row count so the user can query it. Note when results are paginated and more pages are available.

6. Tool Reference

10 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.

7. Pricing

Pricing is pulled live from the Gentic MCP manifest. All prices are per call and deducted from your Gentic credits.

8. Notes

• Organization-scoped: the Seller account, credentials, and default marketplace come from the org's connection (dashboard → Integrations → Amazon). The server only ever reads the account your org connected.
• Read-only: every tool reads from the Selling Partner API — none create, modify, or cancel anything in your Amazon account.
• Credentials are encrypted: your LWA client secret and SP-API refresh token are encrypted server-side (AES-256-GCM, per-secret IV) and never round-tripped to the browser or your agent. Only the non-secret client ID, marketplace, and region are stored in plaintext.
• Reports are asynchronous: `request_amazon_report` submits and returns a `report_id`; `get_amazon_report` polls it and, when ready, loads the rows into a SQL-queryable data lakehouse table. Brand Analytics reports require report options and (for WEEK) a Sunday→Saturday window and a single marketplace.
• v1 covers the NA region — US (ATVPDKIKX0DER), CA (A2EUQ1WTGCTBG2), and MX (A1AM78C64UM0Y8). Buyer PII on orders requires extra Amazon authorization and is omitted.
• Connection checks and report requests are free; data reads are a few cents per call and report loads are billed per row — pricing is pulled live from the Gentic MCP manifest so it always matches what you'll be charged.