The Sneakers API.

Public storefront data, predictable JSON, explicit unknowns.

Authentication

Send Authorization: Bearer <key> on every data request. Health and these docs are public. In the preview, replace <YOUR_DEMO_KEY> with demo; the demo is accepted only when custom keys have not been configured.

curl 'https://sneakers.cx/v1/shopify/search?store=kith.com&query=nike' \
  -H 'Authorization: Bearer <YOUR_DEMO_KEY>'

Endpoints & credit costs

Use a bare public domain for store, such as shopnicekicks.com. Search returns up to ten predictive matches, not a complete catalog. Handles try canonical product JSON first, then Ajax only after a canonical 404, then a catalog of up to 250 products. Numeric IDs try an exact filtered lookup followed by at most four 250-product pages using since_id. Stores may block or ignore filters; incomplete lookup returns the existing error. Predictive-search failures fall back to an all-terms catalog match capped at ten results.

StockX accepts a query or product urlKey / ID. Its adapter is locked disabled in Phase 0 and returns 503 even if STOCKX_ENABLED is set to true. No live StockX availability is promised.

Response shape

Success is {"status":true,"data":...,"contractVersion":"hybrid-1","unavailable":[]}: an array for search and one product for detail. Both sources use the same fields.

{
  "id": "...", "source": "shopify", "title": "...",
  "brand": null, "handle": "...", "urlKey": null,
  "url": "https://store.example/products/...", "image": null,
  "retailPrice": null, "currency": null,
  "variants": [{"id": "...", "title": "...", "size": null,
                "price": null, "available": null}],
  "lowestPrice": null
}

Unknown values are null; missing variants are an empty array. Prices use major currency units. Currency is null when the source does not declare it. Shopify selling prices are not assumed to be manufacturer retail prices. Lowest price includes listed variants even when sold out; inspect variant availability before displaying an offer.

Phase 0 hybrid foundation

Identity, market, retailer and median layers exist as internal adapter interfaces. Alias, retailer identity, retailer asks, median proxy and StockX stay disabled pending licenses and applicable gates. All five feature flags default false; setting a flag alone cannot activate a source in this build. No market trio, licensed catalog or new external-data ingestion is available. Existing Shopify behavior remains reachable; technical access does not establish redistribution rights.

The canonical identity registry is an internal, NON-DURABLE synthetic reference. It issues no public canonical IDs. Durable infrastructure, approved mappings and release acceptance remain prerequisites. Existing source IDs keep their meaning.

Priced Shopify variants add priceProvenance; a product minimum adds lowestPriceProvenance. Legacy prices, nulls and fields stay unchanged. Provenance names provider shopify, the store domain, semantic type retailerOffer, fetch-time observedAt and separate ingestedAt. Region, currency, condition, fees, size system and audience are unknown when unsupported. The source size label is retained. Product minima have aggregate size scope; these are not comparable live market quotes or cross-size spreads. Cache hits retain original timestamps.

Optionally add include=market.alias,market.stockx,identity.retailers,retailers,proxies.median to a legacy product or search request. Each requested missing layer appears as {"layer":"market.alias","reason":"disabled"} in top-level unavailable. Unknown layer names report unsupported. Unrequested layers do not produce omissions. A partial Shopify success costs only the existing operation credit; disabled layers add no charge. Required-layer errors, layered billing, durable idempotency and new public layer routes remain future design.

contractVersion is hybrid-1. Strict clients that reject additional fields must refresh their schema before adopting this build; the previous OpenAPI used additionalProperties=false. The flat data shape and error envelopes remain unchanged.

Credits & freshness

Successful requests, including cache hits, cost the listed credits. Rejected requests and upstream failures cost zero. Search responses are cached for 60 seconds and products for 120 seconds within a warm instance. No stale response is served after expiration.

The preview tracks credits in memory with a UTC calendar-month reset. Restarts and separate instances have independent balances; this is not durable billing or a global rate limiter. The demo allowance is 25 credits per instance, shared by all demo callers.

• X-Sneakers-Request-Id: correlation UUID.
• X-Sneakers-Request-Cost: credits charged for this response.
• X-Sneakers-Cache-Status: hit for a cached success, otherwise live. On an error, live does not imply an upstream call succeeded.
• X-Sneakers-Rate-Limit-Remaining: remaining instance credits, or zero for anonymous responses.
• X-Sneakers-Rate-Limit-Reset: next UTC month boundary, in Unix seconds.

Errors

{"status":false,"message":"invalid credentials"}

401 means missing or unknown credentials; 404 means an unknown route or unavailable product; 405 requires GET; 422 means invalid inputs; 426 means exhausted instance credits; 503 means the source is disabled, blocked, timed out, or returned an unexpected payload; 500 means an internal error. No failed response consumes credits.

Health & source status

/v1/health preserves sources.shopify="live" and sources.stockx="disabled". Additive sources.details describes each source with enabled, state, layers, certifiedCapabilities, ingest/observation timestamps, coverage and a sanitized reason. States are disabled, blocked, healthy, degraded or stale. Shopify starts degraded/not_observed, updates from local calls, and becomes stale after 120 seconds without a fresh successful observation. This is process-local activity, not store-wide availability or licensed certification; certified capabilities remain empty. Health makes no upstream requests and never probes disabled vendors. Handle 503 responses and retry later with backoff.

OpenAPI 3.1 specification ↗