Marketplace API

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:

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

Every type is described field by field in the Response Schema.

Which Marketplace Has Which

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

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.

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:

{
  "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). Most calls are one unit. These can cost more, each up to a ceiling:

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: every field of every type
• Filters: the filter vocabulary and which marketplace accepts what
• Errors: every error code