Guides

Display API Sandbox Quick Start

This guide helps developers make their first successful API call.

Overview

This guide helps you validate your Walmart Connect Display API integration by making a successful API request in Sandbox including:

  • Authentication
  • Header formatting
  • Signature generation
  • Advertiser permissions
  • Asynchronous workflow handling

Once this validation is complete, you can confidently move on to campaign, creative, audience, and reporting workflows.

What this validates

Authentication

Confirms credentials, request signing, timestamps, and required headers are configured correctly.

Permissions

Confirms your advertiser account and API access permissions are configured correctly.

Async Workflows

Confirms your integration can submit jobs, poll status endpoints, and handle asynchronous responses.

Sandbox validation workflow

1. Confirm credentials

Verify Consumer ID, Auth Token, private key, and advertiser ID.

2. Generate signature

Create the authentication signature and timestamp.

3. Submit snapshot request

Send an authenticated reporting request.

4. Receive snapshot ID

Confirm the request was accepted successfully.

5. Poll status

Monitor the asynchronous job until processing completes.

6. Validate success

Confirm authentication, permissions, and async workflows are functioning correctly.

Step 1: Confirm prerequisites

Before continuing, verify you have:

  • Consumer ID
  • Auth Token
  • Private key (.pem)
  • Sandbox advertiserId

If any of these are missing, review:

before proceeding.

Step 2: Generate authentication values

Generate the following values:

  • WM_SEC.AUTH_SIGNATURE
  • WM_CONSUMER.INTIMESTAMP

Important requirements:

  • Timestamp must be Unix epoch in milliseconds
  • Signature validity window is short (typically 300 seconds)
  • Server clocks should be NTP synchronized

See Authentication & Headers for complete examples.

Step 3: Submit a snapshot request

Why this endpoint?

This endpoint is recommended because it validates:

  • Authentication
  • Reporting permissions
  • Request signing
  • Asynchronous job creation
  • Polling behavior

Using a single request, partners can validate several core integration components.

Endpoint

POST /api/v1/snapshot/report

View technical specifications

Requirements

  • Valid authentication
  • Valid advertiserId
  • Valid reportType

Sample request

Snapshot reporting request
curl -X POST \
'https://developer.api.us.stg.walmart.com/api-proxy/service/display/api/v1/api/v1/snapshot/report' \
--header 'Authorization: Bearer <auth_token>' \
--header 'WM_SEC.AUTH_SIGNATURE: ***********' \
--header 'WM_SEC.KEY_VERSION: 1' \
--header 'WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff' \
--header 'WM_CONSUMER.INTIMESTAMP: 1565309779' \
--header 'accept: application/json' \
--data '{ "advertiserId": 600001, "startDate": "2024-07-19", "endDate": "2024-07-24", "reportType": "bid"
}'

Step 4: Validate the response

A successful response should return:

  • snapshotId
  • jobStatus

Expected response

[ { "code": "success", "snapshotId": "17", "details": "", "jobStatus": "pending" }
]

Receiving a valid snapshotId confirms:

  • Authentication succeeded
  • Headers were formatted correctly
  • Permissions are valid
  • The request was accepted for processing

Step 5: Validate polling behavior

Use the status endpoint to monitor report generation.

GET /api/v1/snapshot/report

View technical specifications

Continue polling until the report reaches a terminal state.

This validates:

  • Async job handling
  • Polling logic
  • Reporting permissions

Recommended polling interval

Use a polling interval of 30-60 seconds. Polling more aggressively may result in unnecessary API traffic.

Step 6: Validate permissions

A successful reporting request confirms reporting access only.

If reporting succeeds but campaign creation fails:

  • Confirm the advertiser granted Campaign Management access
  • Confirm the advertiser account supports the requested workflow
  • Review Account Access & Permissions
📌

Common scenario

Reporting-only access successfully authenticates and retrieves reporting data but cannot create or update campaigns, ad groups, audiences, or creatives.

Confirm success

You have successfully completed Sandbox validation when:

  • A valid JSON response is returned
  • A snapshotId is generated
  • Polling requests succeed
  • No authentication errors occur
  • No authorization errors occur

At this point:

✅ Authentication is working

✅ Headers are configured correctly

✅ Reporting permissions are validated

✅ Async workflows are functioning

You are ready to begin implementing Display API workflows.

Common sandbox issues

IssueLikely Cause
401 UnauthorizedIndicates that authentication credentials are missing or invalid, requiring the client to provide valid credentials.
403 ForbiddenOccurs when the client has valid credentials but lacks the necessary permissions to access the resource
400 Invalid payloadMissing required parameter
5xx Server side issues
Empty responseNo data available for the advertiser
Snapshot remains pendingPolling too frequently or processing delay
Reporting succeeds but campaign APIs failReporting-only access granted

What happens next

After completing Sandbox validation:

  1. Review Campaign Management Overview
  2. Review Creative Management Overview
  3. Review Audience Overview
  4. Review Reporting Overview
  5. Begin implementing your first production workflow

Related pages

Updated about 4 hours ago

Did this page help you?