Guides

API Best Practices Guide - Sponsored Search

Overview

This guide outlines best practices to make efficient API requests to avoid throttling. If frequent 429 errors occur, contact Walmart Connect support by logging a support case.

Key Reasons for API Throttling

  • Calling snapshot performance reports multiple times a day
  • Calling the Stats API endpoint more than twice every hour
  • Running bid and keyword optimizations every hour or multiple times a day

Best Practices

  • Distribute API Load: Walmart Connect enforces hourly rate limits for Sponsored Search APIs.
    • Recommendation: Distribute API calls evenly across different hourly timeframes to avoid exceeding limits.
  • Snapshot Performance Reports: One of the most common reasons for API throttling is requesting performance reports multiple times a day.
    • Recommendation: Pull these reports only once every 24 hours via POST /api/v2/snapshot/report. WMC refreshes data once every 24 hours, so multiple calls result in stale data and high API usage.
  • Stats API Endpoint: This near real-time endpoint provides campaign performance data (e.g., clicks, impressions, adSpend, budget runout indicator).
    • Recommendation: Pull this report once every couple of hours. Frequent calls (e.g., every 15 minutes) yield minimal data changes.
  • Strategic Cadence for Bid Optimizations: Frequent bid adjustments for items and keywords can trigger 429 errors.
    • Recommendation: Make optimizations every 4-5 hours. Since performance data is refreshed once every 24 hours, hourly optimizations are not effective. Use the Stats API to gather data and make informed decisions.
  • Entity Snapshot Reports: Requesting campaign entities individually increases API call volume.
    • Recommendation: Use Entity Snapshot performance reports to fetch all entities in a single report. Example: Instead of using GET /api/v1/keywords, use POST /api/v1/snapshot/entity (entityType: "keyword") to fetch keywords at the advertiser level. This approach reduces call volume and consolidates data retrieval.

Tips

  • API Usage Analyzer: This endpoint provides a count of all API operations recorded in the last hour for a given user, offering real-time visibility into usage patterns. By integrating this check into your workflow, you can monitor call volumes and adjust request frequency before reaching the hourly threshold imposed by Walmart Connect. This not only helps prevent throttling errors (429s) but also ensures smoother operation and better system performance across your applications.
  • Advanced Insights API: The Advanced Insights report provides retail data, inventory health, and consumer behavior insights.
    • Recommendation: Use the advancedInsights report type to generate comprehensive reports. Instead of pulling items individually via itemSearch API, use the Advanced Insights Snapshot Report to retrieve all catalog items in one call.

Updated 13 days ago