Wayfair Rank Intelligence — SONGMICS HOME

API reference

Wayfair Rank Data API v1

Interface specification prepared for SONGMICS HOME / Ziel Home Furnishing: authentication, endpoints, parameters, pagination, response schemas, rate limits and webhooks. Sandbox credentials against real Wayfair data are provisioned at signature, so your team can validate end to end before any production commitment.

Base URL

/v1

https://api.plottdata.com

Auth

Bearer

API key in the Authorization header

Pagination

Cursor

Stable cursor, max 1,000 rows per page

Rate limit

600req/min

Burst 60; 429 with Retry-After

Getting started

Authentication

Request header

Required on every request

curl https://api.plottdata.com/v1/wayfair/rankings \
  -H "Authorization: Bearer $PLOTT_API_KEY" \
  -G --data-urlencode "category_slug=shoe-racks-cubbies" \
     --data-urlencode "date=2026-09-01"

Error codes

Standard HTTP semantics; body carries a machine-readable code

`400`	invalid_parameter
`401`	invalid_api_key
`403`	not_entitled — dataset outside your subscription
`404`	not_tracked — category or SKU not in scope
`429`	rate_limited — see Retry-After
`503`	snapshot_pending — that day's run is still in flight

Core surface

Endpoints

GET/v1/wayfair/rankings

Daily rank snapshot for a category and date — one row per ranked listing.

`category_slug`	string	required, repeatable
`date`	date	YYYY-MM-DD; defaults to latest snapshot
`date_from / date_to`	date	range query, instead of date
`include_sponsored`	bool	default true; false returns organic only
`cursor / limit`	string / int	pagination, limit max 1000

GET/v1/wayfair/keywords

Rank rows for on-site keyword search, same shape as category rankings.

`keyword`	string	required, repeatable
`date / date_from / date_to`	date	as above
`cursor / limit`	string / int	pagination

GET/v1/wayfair/weekly

Weekly roll-ups: average rank, volatility, review deltas and unit estimates.

`week_start`	date	Monday of the week
`category_slug / sku`	string	filter on either dimension
`review_rate`	float	override the default 0.03 review-rate assumption

GET/v1/wayfair/products/{sku}

Full history for one SKU — rank, price, rating and review count over time.

date_from / date_to date defaults to last 90 days

GET/v1/wayfair/categories

Sub-categories currently tracked under your subscription, with collection status.

The collection_mode field marks whether a category uses the standard HTML or browser-rendered path.

GET/v1/exports

Returns a signed bulk download URL (CSV or Parquet) for warehouse loads.

`date`	date	snapshot date
`format`	enum	csv \| parquet \| jsonl
`dataset`	enum	rankings \| keywords \| weekly \| products

Signed URLs are valid for one hour and need no further auth to fetch.

Example

Response schema

GET /v1/wayfair/rankings

200 OK

{
  "object": "list",
  "snapshot_date": "2026-09-01",
  "collection_completed_at": "2026-09-01T06:14:22Z",
  "has_more": true,
  "next_cursor": "c3RhcnQ9MTAwMA",
  "data": [
    {
      "collection_date": "2026-09-01",
      "category_slug": "shoe-racks-cubbies",
      "category_name": "Shoe Racks & Cubbies",
      "department": "Storage & Organization",
      "sku": "W005401895",
      "product_name": "Abbi 48-60 Pair Stackable Shoe Rack",
      "brand": "Rebrilliant",
      "brand_type": "wayfair_house",
      "organic_rank": 6,
      "slot_position": 9,
      "page_number": 1,
      "is_sponsored": false,
      "price": 114.99,
      "original_price": 189.99,
      "discount_pct": 39.5,
      "price_type": "sale",
      "listing_flag": "Labor Day Deal",
      "rating": 4.8,
      "review_count": 2330,
      "shipping_text": "FREE Delivery",
      "available_colors": "Black, White",
      "product_url": "https://www.wayfair.com/...",
      "image_url": "https://secure.img1-fg.wfcdn.com/..."
    }
  ]
}

Webhooks (optional)

Fires when each daily snapshot completes, so you pull on an event rather than a timer

POST https://your-endpoint.example.com/plott
X-Plott-Signature: sha256=<hmac>

{
  "event": "snapshot.completed",
  "marketplace": "wayfair_us",
  "snapshot_date": "2026-09-01",
  "categories": 25,
  "keywords": 50,
  "rows": 4_560,
  "export_url": "https://api.plottdata.com/v1/exports/..."
}

Signed with HMAC-SHA256 using a secret issued at provisioning. Five retries with exponential backoff.

Conventions

Worth knowing before you integrate

· All timestamps are UTC, ISO-8601.
· Sponsored rows carry organic_rank: null — filter on is_sponsored.
· Daily snapshots are idempotent — the same (date, category_slug, sku) always returns the same row.
· Fields are only ever added, never removed; breaking changes ship a new version prefix.
· review_count is cumulative and can occasionally decrease when Wayfair removes reviews.

Next step

Provisioning

This is the v1 specification prepared for this engagement. Once the target category list is agreed we issue a sandbox key — against real Wayfair data, not mocks — so your data team can validate the full integration before any production commitment. Production keys, rate-limit allocation and webhook secrets are provisioned at contract start.