retailerapi / docs

POST /v1/products/{id}/refresh

Force a fresh upstream fetch, bypassing cache. Same as &include_force_refresh=true on the GET endpoint.

Request

POST /v1/products/{id}/refresh
Authorization: Bearer rk_live_...

Response

Same shape as GET /v1/products/{id} with all data freshly fetched from upstream — every field below is repopulated from the live upstream call. Updates the cached row.

{
  "item_id": "19667262713",
  "upc": "086279195869",
  "ean": null,
  "isbn": null,
  "gtin": "00086279195869",
  "asin": null,
  "mpn": "EP-PC8",
  "model": "EP-PC8",
  "title": "12-in-1 Electric Pressure Cooker 6 QT...",
  "brand": "Cooks Essentials",
  "image_url": "https://i5.walmartimages.com/.../EP-PC8.jpg",
  "description": "12-in-1 multi-function pressure cooker...",
  "current_price": 49.0,
  "buybox_price": 49.0,
  "secondary_offer_price": null,
  "msrp": 79.99,
  "weight_lbs": 14.2,
  "dimensions": { "height_in": 13.4, "width_in": 12.6, "length_in": 13.0 },
  "offers_count": 1,
  "seller_id": "F55CDC31AB754BB68FE0B39041159D63",
  "seller_name": "Walmart",
  "average_rating": 4.3,
  "review_count": 1247,
  "categories": ["Kitchen", "Small Appliances", "Pressure Cookers"],
  "walmart_url": "https://www.walmart.com/ip/19667262713",
  "in_stock": true,
  "offers": [...],
  "price_history": [...],
  "stats": { "low_30d": 39.0, "high_30d": 59.0, "avg_30d": 47.2 },
  "review_summary": { "average_rating": 4.3, "total_reviews": 1247 },
  "tokens_consumed": 9,
  "tokens_remaining": 1991
}

Cost

+3 tokens above the base lookup cost (total = 1 base + 5 offers/reviews + 3 force_refresh = 9 tokens for a full refresh). Use sparingly; cached responses are much cheaper.

When to use

  • You suspect cached data is wrong (e.g. customer reports wrong price)
  • Pre-purchase price verification — you want today's data, not yesterday's
  • Repricer triggers on a price-change signal

When NOT to use

  • Routine lookups — the standard cache TTLs are tuned to keep data current enough
  • Bulk batch jobs — the +3 tokens × thousands of products gets expensive fast
  • Hot pages with short cache TTLs — they refresh themselves

Rate-limit notes

Force-refresh calls count against your throttle the same as regular calls. We additionally cap force-refresh at 100 calls per minute per organization to prevent upstream-stampede.