Platforms & marketplaces

Which retailers and storefronts are live, what their item ids look like, and how to discover coverage from the API.

Platforms

A platform is a retailer. Every item endpoint takes a platform field and returns the same envelope whichever one you pick; only the ids you send and the platform-specific extras differ.

platform defaults to amazon for compatibility with older integrations. Send it explicitly in new code.

Marketplaces

A marketplace is one regional storefront of a platform, such as us or ca. Each call reads exactly one. Prices come back in that marketplace's currency, named beside every price.

• marketplace defaults to the platform's default (us on every live platform).

• A coming-soon marketplace answers 501 NOT_IMPLEMENTED with "coming_soon": true. Nothing is charged.

• An unknown platform or marketplace is a 400 INVALID_PARAM; the message lists the valid values.

Item ids

Send each platform's own product identifier in ids. On Amazon, asins is accepted as an alias.

• Ids are trimmed (and upper-cased on Amazon). Empty strings are ignored.

• Duplicates are fetched and charged once; each unique id comes back exactly once.

• An id that does not match the format is a 400 INVALID_PARAM with param set to ids[i], and nothing is charged.

Discover coverage

GET /v1/platforms lists every platform, its marketplaces and endpoints, each live or coming_soon, with tiers and prices. It needs no API key, so SDKs and dashboards can read coverage instead of hard-coding it.

cURL

curl "https://api.scrapelyserp.com/v1/platforms"

Response

{
  "object": "list",
  "data": [
    {
      "id": "bestbuy",
      "object": "platform",
      "name": "Best Buy",
      "status": "live",
      "id_field": "ids",
      "id_name": "SKU",
      "default_marketplace": "us",
      "endpoints": [
        {
          "id": "products",
          "name": "Product data",
          "route": "POST /v1/products",
          "status": "live",
          "tiers": [
            {
              "id": "standard",
              "name": "Standard",
              "credits_per_item": 1,
              "max_items_per_call": 1000
            }
          ]
        }
      ],
      "marketplaces": [
        {
          "code": "us",
          "name": "Best Buy US",
          "country": "US",
          "currency": "USD",
          "status": "live",
          "endpoints": {
            "products": "live"
          }
        },
        {
          "code": "ca",
          "name": "Best Buy Canada",
          "country": "CA",
          "currency": "CAD",
          "status": "coming_soon",
          "endpoints": {
            "products": "coming_soon"
          }
        }
      ]
    },
    {
      "…": "one entry per platform"
    }
  ]
}

Coming soon

• Platforms: Google, eBay and AliExpress.

• Amazon marketplaces: uk, de, fr, it, es, ca, mx, jp, au, in, br, nl, se, pl.

• Best Buy marketplaces: ca.

Anything announced answers 501 NOT_IMPLEMENTED with "coming_soon": true until it launches, and is never charged.