# Amazon

> Seller, Vendor, Ads, DSP and AMC under one key, with every data set, its status and its freshness.

Status: Live

- Amazon: Reads: yes · Writes: yes

Every Amazon account you run, under one key. History is kept from the day you connect. Reads are on for every account; writes exist on Amazon only, with guardrails.

## Account types

| Account | Who it is for | What you grant | Access |
|---|---|---|---|
| Seller Central | Brands selling on Amazon | Orders, stock, returns | Read |
| Vendor Central | Brands Amazon buys from | Sales, inventory, POs | Read |
| Ads | Anyone running Sponsored ads | Campaigns, reports | Read; writes opt-in |
| DSP | Teams buying programmatic display | Campaign results | Read |
| AMC | Advertisers with an AMC instance | Queries, audiences | Read |

## Connect Amazon

About ten minutes.

1. **Sign in with Amazon**

   Ads: read campaigns and reports. Changes stay off until you turn them on.
2. **Add Seller or Vendor Central**

   Orders, stock, returns and sales: read only.
3. **Pick accounts, get data**

   A 60-day backfill starts, then history is kept. DSP and AMC join from the same screen.

_To write: screenshots of the three console screens, and the exact permissions each Amazon consent screen asks for_

## Data you get

Every data set with its status. Live means it is in your key now. Needs Brand Registry means Amazon gives it only to enrolled brands. Not available means Amazon does not share it.

**Ads**

| Data | Status | Freshness | History |
|---|---|---|---|
| Campaigns and ad groups | Live | hourly | Backfill 60 d, then kept |
| Targets and keywords | Live | hourly | Backfill 60 d, then kept |
| Search terms | Live | daily | Backfill 60 d, then kept past Amazon’s window |
| Placements | Live | hourly | Backfill 60 d, then kept |
| Advertised products | Live | hourly | Backfill 60 d, then kept |
| Search terms from before you connected | Not available | — | Only what Amazon still holds |

**Seller**

| Data | Status | Freshness | History |
|---|---|---|---|
| Orders and units | Live | every 15 min | Kept from connect |
| Inventory and inbound | Live | every 15 min | Kept from connect |
| FBA customer returns | Live | daily | Kept from connect |
| Catalog and listings | Live | daily | Kept from connect |
| Fees and settlements | Live | daily | Kept from connect |
| Buyer names and addresses | Not available | — | Never shared by Amazon |

**Vendor**

| Data | Status | Freshness | History |
|---|---|---|---|
| Sales performance | Live | daily | Kept from connect |
| Inventory by ASIN | Live | daily | Kept from connect |
| Rapid Retail Analytics: near-real-time sales and stock | Live | hourly | Kept from connect |
| Purchase orders | Live | daily | Kept from connect |

**Brand**

| Data | Status | Freshness | History |
|---|---|---|---|
| Search Query Performance | Needs Brand Registry | weekly | Weekly snapshots kept |
| Search Catalog Performance | Needs Brand Registry | weekly | Weekly snapshots kept |
| Brand Analytics: search terms, market basket, repeat purchase | Needs Brand Registry | weekly | Weekly snapshots kept |
| Other brands’ sales and ads | Not available | — | Not shared by Amazon |

**DSP**

| Data | Status | Freshness | History |
|---|---|---|---|
| Campaign and line-item results | Live | daily | Kept from connect |
| Orders and conversions | Live | daily | Kept from connect |

**AMC**

| Data | Status | Freshness | History |
|---|---|---|---|
| Path to conversion | Live | on request | Kept from connect |
| Time to conversion and attribution | Live | on request | Kept from connect |
| Audiences: size and create | Live | on request | Kept from connect |

## Read tools

POST https://build-api.sellermate.ai/v1/tools/get_campaign_performance — Spend, clicks, orders, sales and ACoS for each campaign. (writes: no; platforms: Amazon, Google Ads)

POST https://build-api.sellermate.ai/v1/tools/get_search_term_performance — Search terms with clicks, spend and orders, kept past Amazon's window. (writes: no; platforms: Amazon, Google Ads)

POST https://build-api.sellermate.ai/v1/tools/get_orders_report — Orders and units for a Seller account. (writes: no; platforms: Amazon)

POST https://build-api.sellermate.ai/v1/tools/get_inventory — Stock and inbound units. (writes: no; platforms: Amazon)

_To write: which data sets in the table each read tool returns, per account type (Seller, Vendor, Ads, DSP, AMC), and any read tool still to add to the API reference_

## Write tools and guardrails

> **Amazon only: Writes run on Amazon accounts only**
>
> You can change bids, budgets, negatives and campaigns. Changes stay off until you turn them on, and a key needs the read and write scope.

POST https://build-api.sellermate.ai/v1/tools/update_target — Change a target, behind caps, a dry run and undo. (writes: yes; platforms: Amazon)

- **Caps.** Nothing moves past your limit.
- **Dry run.** See it before it is applied.
- **Undo for 24 hours.** Roll back in one step.
- **Audit log.** Who, what, when, why.

The full rules are in [Writes and guardrails](https://build.sellermate.ai/docs/guides/writes-and-guardrails.md).

## Derived metrics

_To write: the derived metrics Build computes (ACoS, TACoS, contribution margin per SKU, days of stock) with the formula and the inputs of each_

## Freshness

> **Freshness figures (to confirm)**
>
> The figures below, and "Amazon sales move for up to 14 days", are the current site statements. Each is (to confirm) before launch. Every answer carries `data_as_of`.

| Data | Freshness | History | Status |
|---|---|---|---|
| Campaigns and ad groups | hourly | Backfill 60 d, then kept | Live |
| Targets and keywords | hourly | Backfill 60 d, then kept | Live |
| Search terms | daily | Backfill 60 d, then kept past Amazon’s window | Live |
| Placements | hourly | Backfill 60 d, then kept | Live |
| Advertised products | hourly | Backfill 60 d, then kept | Live |
| Search terms from before you connected | — | Only what Amazon still holds | Not available |
| Orders and units | every 15 min | Kept from connect | Live |
| Inventory and inbound | every 15 min | Kept from connect | Live |
| FBA customer returns | daily | Kept from connect | Live |
| Catalog and listings | daily | Kept from connect | Live |
| Fees and settlements | daily | Kept from connect | Live |
| Buyer names and addresses | — | Never shared by Amazon | Not available |
| Sales performance | daily | Kept from connect | Live |
| Inventory by ASIN | daily | Kept from connect | Live |
| Rapid Retail Analytics: near-real-time sales and stock | hourly | Kept from connect | Live |
| Purchase orders | daily | Kept from connect | Live |
| Search Query Performance | weekly | Weekly snapshots kept | Needs Brand Registry |
| Search Catalog Performance | weekly | Weekly snapshots kept | Needs Brand Registry |
| Brand Analytics: search terms, market basket, repeat purchase | weekly | Weekly snapshots kept | Needs Brand Registry |
| Other brands’ sales and ads | — | Not shared by Amazon | Not available |
| Campaign and line-item results | daily | Kept from connect | Live |
| Orders and conversions | daily | Kept from connect | Live |
| Path to conversion | on request | Kept from connect | Live |
| Time to conversion and attribution | on request | Kept from connect | Live |
| Audiences: size and create | on request | Kept from connect | Live |

Amazon sales keep moving for up to 14 days. Build re-pulls those days until they settle (to confirm).

## Limits and caveats

| Amazon's limit | What Build does |
|---|---|
| Search-term reports keep about 60 to 95 days, depending on the report. | Build keeps them from day one. |
| SQP and Brand Analytics need Brand Registry. | The status says so. No silent empty tables. |
| On a stock-out Amazon pauses only Sponsored Products. | One automation on Build pauses Brands and Display too. You can build it on the API. |
| Vendor reports lag about 48 hours. | Rapid Retail Analytics gives near-real-time vendor sales and stock. |

What is not available: buyer names, other brands' sales and ads, and search terms Amazon dropped before you connected. When you disconnect, your data is held for 30 days, then deleted.

## Five example calls

### 1. Last week's campaigns

**curl**

```bash
curl -X POST https://build-api.sellermate.ai/v1/tools/get_campaign_performance \
  -H "X-API-Key: $BUILD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account":"amz_northwind","start":"2026-10-22","end":"2026-10-28"}'
```

### 2. Stock by SKU

**curl**

```bash
curl -X POST https://build-api.sellermate.ai/v1/tools/get_inventory \
  -H "X-API-Key: $BUILD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account":"amz_northwind"}'
```

### 3. Search terms past Amazon's window

_To write: a get_search_term_performance call for a range older than 95 days, and a sample row_

### 4. Orders and units

_To write: a get_orders_report call for one week, and a sample row_

### 5. A change with a dry run

_To write: an update_target dry run and then the applied call, with the real field names_

## What the official connectors can't do

_To write: what Amazon's own tools cannot do that Build does: history past the platform window, one key across accounts, the same fields on other platforms, and guarded writes. Compare plainly and name no competitor claims you cannot back_

## Changelog

Changes to Amazon on Build are listed in the [changelog](https://build.sellermate.ai/docs/changelog.md).