Overview

To reduce throttling and improve integration performance, use snapshot reports for bulk data, avoid redundant requests for daily-refreshed data, poll near-real-time endpoints only when needed, and monitor API usage regularly. These practices help keep API workflows efficient, reliable, and aligned with Walmart Connect rate-limit expectations.

If you frequently receive 429 errors, contact Walmart Connect support by logging a support case.

Walmart Connect enforces hourly rate limits for Sponsored Search APIs. To avoid throttling, design integrations to:

• Distribute API calls evenly throughout the day.
• Avoid repeated calls for data that refreshes once daily.
• Use snapshot reports for bulk data retrieval.
• Limit near-real-time polling to meaningful intervals.
• Run bid and keyword optimizations at a strategic cadence.
• Monitor API usage before reaching hourly thresholds.

Common Causes of Throttling

The most common causes of throttling include:

• Requesting snapshot performance reports multiple times per day.
• Calling the Stats API endpoint too frequently.
• Running bid or keyword optimizations every hour or multiple times per day.
• Fetching campaign entities individually instead of using snapshot reports.
• Repeatedly calling catalog or item-level APIs when bulk reporting options are available.

General Best Practices

Distribute API Load

Avoid sending large bursts of API traffic within a short period. Spread API requests evenly across available hourly windows to reduce the risk of exceeding rate limits.

Use Snapshot Reports for Bulk Retrieval

Use snapshot reports when you need to retrieve large sets of data. Snapshot reports reduce call volume by consolidating data into a single report instead of requiring separate API calls for each entity.

For example, instead of calling GET /api/v1/keywords repeatedly, use POST /api/v1/snapshot/entity with entityType: "keyword" to retrieve keywords at the advertiser level.

Avoid Repeated Requests for Daily-Refreshed Data

Performance report data refreshes once every 24 hours. Requesting the same report multiple times per day increases API usage without providing new data.

Use the Stats API Strategically

The Stats API provides near-real-time metrics such as clicks, impressions, ad spend, and budget capout data. However, frequent polling may produce minimal changes while increasing API volume.

Use the Stats API to monitor active campaign performance and inform optimization decisions, but avoid excessive polling.

Optimize Bids and Keywords at Meaningful Intervals

Avoid running bid and keyword optimizations every hour. Since performance data is refreshed once daily, hourly optimizations are generally not effective and can contribute to throttling.

A recommended optimization cadence is every 4 to 5 hours, using available Stats API data to inform decisions.

Monitor API Usage

Use the API Usage Analyzer to review API operation counts from the last hour for a given user. Integrating this check into your workflow can help you identify high-volume usage patterns and adjust request frequency before reaching hourly limits.

Recommended API Call Frequencies

Campaign Management

Reporting

Growth Opportunities

Insights, Audit, and Miscellaneous Reports

Endpoint-Specific Guidance

Snapshot Performance Reports

Use POST /api/v2/snapshot/report to request performance reports once per report type, per advertiser, per day.

Because performance data refreshes once every 24 hours, requesting the same report multiple times per day usually returns stale data and increases API usage unnecessarily.

Entity Snapshot Reports

Use POST /api/v1/snapshot/entity when you need campaign entity data such as campaigns, ad groups, ad items, keywords, placements, or bid multipliers.

Avoid using individual GET endpoints to retrieve large lists of entities. Entity Snapshot reports are more efficient because they return entity data in bulk.

Stats API

Use GET /api/v1/stats for near-real-time campaign performance monitoring. This endpoint is useful for checking active campaign health, including clicks, impressions, ad spend, and budget capout indicators.

Although the maximum recommended frequency is 1 call per hour per advertiser, use a lower frequency when your workflow does not require hourly updates.

Bid and Keyword Optimization

Run bid and keyword optimizations every 4 to 5 hours instead of hourly. Use Stats API data to guide optimization decisions, but avoid repeated optimization cycles that rely on unchanged performance-report data.

Advanced Insights

Use the Advanced Insights Snapshot Report to retrieve catalog, retail, inventory health, and consumer behavior insights in bulk.

Instead of pulling items individually through item-level APIs, use the advancedInsights report type to retrieve catalog items in a single report. Call this report only when onboarding an advertiser or when the item catalog changes.

Audit Snapshots

Use POST /api/v1/snapshot/audit when you need to audit campaign entity changes. Because audit needs vary by workflow, call this endpoint as needed based on business requirements.

Implementation Checklist

Use this checklist when designing or reviewing an API integration:

• API calls are distributed evenly across hourly timeframes.
• Snapshot performance reports are requested only once per report type, per advertiser, per day.
• Entity Snapshot reports are used instead of repeated individual entity GET calls.
• Stats API calls are limited to meaningful monitoring intervals.
• Bid and keyword optimizations run every 4 to 5 hours, not hourly.
• Advanced Insights reports are used for catalog-level data instead of repeated item-level calls.
• API Usage Analyzer is used to monitor recent API activity.
• Workflows avoid repeated calls for data that refreshes once daily.
• Review-status polling is limited to 1 call every 3 hours per unique ad group submitted for review.
• Support cases are logged if frequent 429 errors continue after applying these practices.