---
title: "Marketplace API"
description: "Amazon, Shopify, Walmart, TikTok Shop and AliExpress through one set of operations and one response schema."
---

The Marketplace API serves four marketplaces through **the same operations and one response schema**. A
product from Amazon and a product from Shopify arrive as the same `Product`, so the code that reads one
reads all of them. The marketplace is a segment of the path:

```bash
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"
curl "https://gateway.apinoa.com/v1/walmart/search?query=wool+socks" -H "x-api-key: $APINOA_API_KEY"
```

## Operations

| Operation | Returns | What It Does |
|---|---|---|
| `search` | `SearchResult` | Products matching a keyword, with filters |
| `image-search` | `SearchResult` | Products matching a photo |
| `browse` | `SearchResult` | The products in one category, with no keyword |
| `categories` | `CategoryList` | One level of the category tree, to find ids `browse` accepts |
| `catalog` | `SearchResult` | Every product of one store |
| `product` | `Product` | One product in full: variants, images, specifications, seller, delivery |
| `reviews` | `ReviewPage` | A product's reviews, one page at a time |
| `shipping` | `ShippingQuote` | What shipping one item to a country costs, by carrier |

Every type is described field by field in the [Response Schema](/docs/api-reference/marketplaces/response-schema).

## Which Marketplace Has Which

| | search | image-search | browse | categories | catalog | product | reviews | shipping |
|---|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| [Amazon](/docs/api-reference/amazon) | ✓ | ✓ | ✓ | ✓ | | ✓ | | |
| [Shopify](/docs/api-reference/shopify) | ✓ | ✓ | | | ✓ | ✓ | ✓ | |
| [Walmart](/docs/api-reference/walmart) | ✓ | | ✓ | ✓ | | ✓ | ✓ | |
| [TikTok Shop](/docs/api-reference/tiktokshop) | ✓ | | ✓ | ✓ | ✓ | ✓ | ✓ | |
| [AliExpress](/docs/api-reference/aliexpress) | ✓ | ✓ | ✓ | ✓ | | ✓ | | ✓ |

An empty cell means the marketplace has no surface for that operation, not that it is planned. Amazon
reviews are not available. Shopify has no `browse` or `categories` because it is millions of independent
stores with no shared category tree; list one store with `catalog` instead.

eBay is **temporarily unavailable**. Its endpoints answer `404 UNKNOWN_MARKETPLACE` until it returns.

## What Is the Same, and What Differs

| | Identical Everywhere | Differs per Marketplace |
|---|---|---|
| Response **types** | ✓ `SearchResult`, `Product`, `ReviewPage` | |
| Field **names and meanings** | ✓ `price` is always what a buyer pays today | |
| Filter **names and units** | ✓ `priceMin` is always a decimal amount in major units | |
| Which **fields are filled** | | Only Amazon and Walmart return `reviewSummary`; only AliExpress states `stock` as a number |
| Which **operations** exist | | See the table above |
| Which **filters** are accepted | | Amazon charges 2 units for `brands`; AliExpress takes no `ratingMin` |
| **Paging** | | Shopify pages by `cursor`; the others by `page` |
| **Product id** format | | An ASIN, a numeric id, or `shop/handle` |

Write your parser once, but read the marketplace's page before you write the request: each lists exactly
what it accepts and how often each optional field actually arrives. The shared filter vocabulary is in
[Filters](/docs/api-reference/marketplaces/filters).

## Categories and Browsing

`browse` lists a category with no keyword; `categories` tells you which ids exist. Call `categories` with
no `categoryId` for the top level, and pass an id to list its children. What differs is the kind of id:
Amazon's departments are store slugs, Walmart's are numeric ids that browse as underscore-joined chains,
and AliExpress's are ordinary category ids.

Not every category lists products: many are navigation levels. `categories?browsableOnly=true` returns
only ids `browse` accepts. Where it is not known whether a category browses, `browsable` is absent rather
than `false`. A marketplace without that data answers `400 BROWSABLE_ONLY_UNAVAILABLE`.

## Finding Out at Runtime

`GET /v1/marketplaces` publishes the whole catalog: every platform, its operations, what each costs, and
the **JSON Schema of each operation's input**. Generate against it rather than hard-coding these pages.
Shortened:

```json
{
  "success": true,
  "data": {
    "marketplaces": [
      {
        "id": "walmart",
        "kind": "marketplace",
        "operations": ["search", "browse", "categories", "product", "reviews"],
        "regions": ["US"],
        "cost": { "search": { "base": 1, "max": 1 }, "product": { "base": 1, "max": 1 } },
        "params": {
          "search": {
            "type": "object",
            "required": ["query"],
            "properties": { "query": { "type": "string", "minLength": 1, "description": "Keywords to search for. …" } }
          }
        }
      }
    ],
    "pricing": {
      "currency": "USD",
      "unitPrice": { "marketplace": "0.001000", "image-translate": "0.003000" },
      "dayBoundary": "UTC",
      "dailyBrackets": [{ "fromUnits": 0, "ratePct": 100 }, { "fromUnits": 1000, "ratePct": 90 }]
    }
  }
}
```

Operation names are written exactly as in the URL (`image-search`), so each drops straight into
`/v1/{platform}/{operation}`. `kind` is `marketplace` or `sns`.

## Pricing

**$0.001 per unit** at list price, stepping down as the day's volume grows (see [Pricing](/pricing)). Most
calls are one unit. These can cost more, each up to a ceiling:

| Operation | Price | What Adds to It |
|---|---|---|
| Amazon `search`, `browse` | $0.001, up to $0.002 | `brands` or `facets` make it 2 units |
| Amazon `image-search` | $0.001, up to $0.002 | 2 units when the picture matches; 1 when it matches nothing |
| Amazon `product` | $0.002, up to $0.032 | Always 2 units: the product page and its lower half (specs, Best Sellers Rank, rating breakdown). `include=offers`: one more unit per page of ten offers, up to 30 pages |
| Shopify `reviews` | $0.001, up to $0.007 | A first page can take extra units; a `cursor` page does not |
| AliExpress `product` | $0.001, up to $0.002 | `include=shipping` makes it 2 units |
| AliExpress `shipping` | $0.001, up to $0.002 | 2 units unless `sku` is a numeric SKU id |

The catalog states the same figures in units: `cost.base` is what a call charges and `cost.max` the most it
can, and one unit is `pricing.unitPrice`. A call that fails is not billed.

## Reference

- [Response Schema](/docs/api-reference/marketplaces/response-schema): every field of every type
- [Filters](/docs/api-reference/marketplaces/filters): the filter vocabulary and which marketplace accepts what
- [Errors](/docs/errors): every error code