Entity Snapshot – Advertising Partners – US – API Doc

Overview

The Entity Snapshot API provided functionality to retrieve the campaign structure of all the ad campaigns for a given advertiser.

Note:
Snapshot IDs expire after 24 hours post generation.

Create Entity Snapshot

Description:

You can create file-based snapshot for all the campaign entities for an advertiser using this method.

URL: POST/api/v1/snapshot/entity

Query Parameters

Parameter	Description	Type	Required	Possible Values
auth_token	The token will provide you the access to the API. It is same for all advertisers you access through the API.	string	Y	Please utilize the generated auth_token shared with you at the time of partner onboarding from the Getting Started Guide
advertiserId	The ID of the advertiser	integer	Y	Unique numeric identifier
entityStatus	The status of the entity Note: The default status is “enabled”. Disabled entities won’t be part of the snapshot unless you request “disabled” and/or “all”	string	Y	Possible values: enabled, disabled, all
entityTypes	The type of entity for which the snapshot should be generated.	string array	Y	Possible values: 1. campaign 2. adGroup 3. keyword 4. adItem 5. bidMultiplier 6. placement: If you select this value, the entity snapshot will return which placements have been included or excluded for a given keyword campaign. The placements are: For a keyword campaign: Search In-grid, Carousel, Buybox, Others For an Auto campaign: Search In-grid, Carousel, Buybox, Browse In-Grid, Stock Up, Home Page, Others sbaProfile: only for Sponsored Brands (earlier known as Search Brand Amplifier or SBA) adGroupMedia: only for Sponsored Videos campaigns category: only for Sponsored Brand campaigns
format	Choose the format type for your snapshot	string	N	Types of Format: gzip, zip Note: gzip allows decompression while file is being transferred over the network, hence it is a faster and simpler way to download the reports. You will receive snapshot in zip format if no specific format is selected

Note: There is no limit on number of snapshot requests for an advertiser.

Sample Requests for Create Entity Snapshot

Headers

Header Name	Description	Required	Values
WM_CONSUMER.ID	We will provide you the consumer ID to access the API. It is same for all advertisers you access through the API.	Y	Please use the generated ConsumerId shared with you at the time of partner onboarding. Refer to the Getting Started Guide for further explanation on this
WM_SEC.AUTH_SIGNATURE	Auth signature as an API key	Y	Use the signature generator code from Getting Started Guide to generate this value
WM_CONSUMER.intimestamp	Timestamp for which the auth signature is generated. Use Unix epoch format for the timestamp	Y	Use the signature generator code (Getting Started Guide) to generate this value

Sample Request 1

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/entity?auth_token=1234" \
-H "accept: application/json" \
-H "WM_SEC.AUTH_SIGNATURE: **************"\
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" \
-H "WM_CONSUMER.intimestamp: 1565309779"\
-d " [ 
		{ 
           "advertiserId": 600001,
           "entityStatus": "enabled",
           "entityTypes": ["campaign", " adGroup"],
            "format": "zip"
         } 
      ] "

Sample Request 2

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/entity?auth_token=1234" \
-H "accept: application/json" \
-H "WM_SEC.AUTH_SIGNATURE: **************"\
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" \
-H "WM_CONSUMER.intimestamp: 1565309779"\
-d " [ 
 	{ 
           "advertiserId": 600003,
           "entityStatus": "enabled",
           "entityTypes" : ["bidMultiplier" , "adItem"]
        } '
     ] "

Sample Request 3

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/entity?auth_token=1234" \
-H "accept: application/json" \
-H "WM_SEC.AUTH_SIGNATURE: **************"\
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" \
-H "WM_CONSUMER.intimestamp: 1565309779"\
-d " [ 
        { 
          "advertiserId": 600004,
          "entityStatus": "enabled",
          "entityTypes" : ["campaign", "adGroup", "keyword", "adItem", "bidMultiplier", "placement" ],
           "format": "gzip"
	}
     ] "

Sample Request 4

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/entity?auth_token=1234" \
-H "accept: application/json" \
-H "WM_SEC.AUTH_SIGNATURE: **************"\
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" \
-H "WM_CONSUMER.intimestamp: 1565309779"\
-d " [
       { 
        "advertiserId": 600004,
        "entityStatus": "enabled",
        "entityTypes" : ["campaign", "adGroup", "keyword", "adItem", "bidMultiplier", "placement"],
         "format": "gzip"
        } 
     ] "

Sample Request 5

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/entity?auth_token=1234" \
-H "accept: application/json" \
-H "WM_SEC.AUTH_SIGNATURE: **************"\
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" \
-H "WM_CONSUMER.intimestamp: 1565309779"\
-d " [
      { 
        "advertiserId": 600005,
        "entityStatus": "enabled",
        "entityTypes" : ["category", "sbaProfile"],
         "format": "gzip"
      } 
    ] "

Sample Request 6

curl -X POST \ 
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot/entity?auth_token=1234" \
-H "accept: application/json" \
-H "WM_SEC.AUTH_SIGNATURE: **************"\
 -H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" \
 -H "WM_CONSUMER.intimestamp: 1565309779"\
 -d "[
       { 
          "advertiserId": 600005,
          "entityStatus": "enabled",
          "entityTypes" : [ "campaign","adGroup","keyword","adItem", 
                           "adGroupMedia"],
          "format": "gzip"
       } 
  ]"

Sample Responses for Create Entity Snapshot

Response

Element	Description	Type
code	The response code can have following values: success, failure	string
details	Details of the error if value of response code is failure	string
snapshotId	ID of the snapshot	string
jobStatus	It is an indicator to confirm status of snapshot generation. The possible values of jobStatus are: `pending`, `processing`, `done`, `failed`, `expired`	string

Sample Response 1

[
  {
    "code": "success",
    "snapshotId": "1",
    "details": "https://advertising.walmart.com/file/1 ",
    " jobStatus ": "done"
  }
]

Sample Response 2

[
  {
    "code": "success",
    "snapshotId": "2",
    "details": "https://advertising.walmart.com/file/2",
    "jobStatus": "done"
  }
]

Sample Response 3

[
  {
    "code": "success",
    "snapshotId": "3",
    "details": "https://advertising.walmart.com/file/3",
    " jobStatus ": "done"
  }
]

Sample Response 4

[
  {
    "code": "success",
    "snapshotId": "4",
    "details": "https://advertising.walmart.com/file/4",
    " jobStatus ": "done"
  }
]

Sample Response 5

[
  {
    "code": "success",
    "snapshotId": "5",
    "details": "https://advertising.walmart.com/file/5",
    " jobStatus ": "done"
  }
]

Sample Response 6

[
  {
     "code" : "success",
     "snapshotId": "6",
     "details" :  "https://advertising.walmart.com/file/6",
    " jobStatus ": "done"
  }
]

Retrieve Campaign Entity Snapshots

Description:

You can retrieve entity by providing snapshot id and advertiser id for an advertiser.

Note:

The output is generated in a “zip/gzip” file depending upon format chosen
The file type in zip file will be JSON

URL: GET/api/v1/snapshot

Sample Request

curl -X GET\
"https://developer.api.stg.walmart.com/api-proxy/service/WPA/Api/v1/api/v1/snapshot?advertiserId=600001&snapshotId=1&auth_token=1234"  \
-H "accept: application/json" \
-H "WM_SEC.AUTH_SIGNATURE: ***********" \
-H "WM_CONSUMER.ID: adfwe-v23-faasd2r-afs-asdfqeff" \
-H "WM_CONSUMER.intimestamp: 1565309779" \

Response

Element	Description	Type
snapshotId	Id of the snapshot to be retrieved	string
jobStatus	It is an indicator to confirm status of snapshot generation. The possible values of jobStatus are: `pending`, `processing`, `done`, `failed`, `expired`	string
details	URL of the snapshot file once jobStatus reaches to state “`done`”	string
code	The response code can have following values: `success`, `failure`	string

Note:

TTL (Time to Live) for files generated is one day

Sample Response 1

[
  {
    "code": "success",
    "snapshotId": "1",
    "details": "https://advertising.walmart.com/file/1 ",
    " jobStatus ": "done"
  }
]

The snapshot file is in JSON format that includes response for each entity type. You can request multiple entity types in one request; however, the response would be captured in one zip/gzip file as requested. It will have single JSON file returning response for all entities.

Example of the content of snapshot with id “1”. The file format is “json”:

{
  "campaigns": [
    {
      "name": "camp1",
      "campaignType": "sponsoredProducts",
      "targetingType": "auto",
      "status": "enabled",
      "budgetType": "both",
      "startDate": "2019-03-15",
      "endDate": "2019-04-15",
      "totalBudget": 1000,
      "dailyBudget": 100,
      "rollover": true,
      "advertiserId": 600001,
      "campaignId": 200001
    },
    {
      "name": "camp2",
      "campaignType": "sponsoredProducts",
      "targetingType": "auto",
      "status": "enabled",
      "budgetType": "both",
      "startDate": "2019-04-15",
      "endDate": "2019-05-15",
      "totalBudget": 1000,
      "dailyBudget": 100,
      "rollover": true,
      "advertiserId": 600001,
      "campaignId": 219032
    }
  ],
  "adGroups": [
    {
      "adGroupId": 15718,
      "name": "AG_FOR_CAMPAIGN_14758",
      "status": "enabled",
      "campaignId": 100002
    },
    {
      "adGroupId": 10625,
      "name": "01_ABB_A6019",
      "status": "enabled",
      "campaignId": 106063
    }
  ]
}

Sample Response 2

[
  {
    "code": "success",
    "snapshotId": "2",
    "details": "https://advertising.walmart.com/file/2",
    "jobStatus": "done"
  }
]

Example of the content of snapshot with id “2”. The file format is “json”:

{
  "placementBidMultipliers": [
    {
      "campaignId": 170621,
      "placementType": "Buy-Box",
      "multiplier": 0
    },
    {
      "campaignId": 170621,
      "placementType": "Search In-grid",
      "multiplier": 0
    }
  ],
  "platformBidMultipliers": [
    {
      "campaignId": 17062,
      "platformType": "Desktop",
      "multiplier": 0
    },
    {
      "campaignId": 17062,
      "platformType": "App",
      "multiplier": 0
    }
  ],
  "adItem": [
    {
      "campaignId": 106061,
      "adGroupId": 106250,
      "itemId": "46492243",
      "adItemId": 52196,
      "bid": 2,
      "status": "enabled",
      "itemImageUrl": "http://i5.walmartimages.com/dfw/dce07b8c-4e1d/k2-_0175c3dd-7c6a-4088-bf9c-f1cd5b9209d8.v1.jpg",
      "itemPageUrl": "https://www.walmart.com/ip/46492243",
      "name": "TV Console"
    }
  ]
}

Sample Response 3

[
  {
    "code": "success",
    "snapshotId": "3",
    "details": "https://advertising.walmart.com/file/3",
    " jobStatus ": "done"
  }
]

Example of the content of snapshot with id “3”. The file format is “json”:

{
  "campaigns": {
    "name": "camp3",
    "campaignType": "sponsoredProducts",
    "targetingType": "auto",
    "status": "enabled",
    "budgetType": "both",
    "startDate": "2019-02-01",
    "endDate": "2019-03-01",
    "totalBudget": 899999,
    "dailyBudget": 100,
    "rollover": true,
    "advertiserId": 600003,
    "campaignId": 183000
  },
  "adGroups": {
    "adGroupId": 157181,
    "name": "AG_FOR_CAMPAIGN_14758",
    "status": "enabled",
    "campaignId": 147581
  },
  "keywords": {
    "campaignId": 170910,
    "adGroupId": 181590,
    "keywordId": 36511789533,
    "state": "enabled",
    "keywordText": "pedialyte",
    "keywordCategory": null,
    "status": "awaiting_approval",
    "matchType": "exact",
    "bid": 2
  },
  "adItem": {
    "campaignId": 106061,
    "adGroupId": 106250,
    "itemId": "46492243",
    "adItemId": 52196,
    "bid": 2,
    "status": "enabled",
    "itemImageUrl": "http://i5.walmartimages.com/dfw/dce07b8c-4e1d/k2-_0175c3dd-7c6a-4088-bf9c-f1cd5b9209d8.v1.jpg",
    "itemPageUrl": "https://www.walmart.com/ip/46492243",
    "name": "TV Console"
  },
  "placementBidMultipliers": {
    "campaignId": 170621,
    "placementType": "Buy-Box",
    "multiplier": 0
  },
  "platformBidMultipliers": {
    "campaignId": 17062,
    "platformType": "Desktop",
    "multiplier": 0
  }
}

Sample Response 4

[
  {
    "code": "success",
    "snapshotId": "4",
    "details": "https://advertising.walmart.com/file/4",
    " jobStatus ": "done"
  }
]

Example of the content of snapshot with id “4”. The file format is “json”:

{
  "campaigns": {
    "name": "camp3",
    "campaignType": "sponsoredProducts",
    "targetingType": "auto",
    "status": "enabled",
    "budgetType": "both",
    "startDate": "2019-02-01",
    "endDate": "2019-03-01",
    "totalBudget": 899999,
    "dailyBudget": 100,
    "rollover": true,
    "advertiserId": 600003,
    "campaignId": 183000
  },
  "adGroups": {
    "adGroupId": 157181,
    "name": "AG_FOR_CAMPAIGN_14758",
    "status": "enabled",
    "campaignId": 147581
  },
  "keywords": {
    "campaignId": 170910,
    "adGroupId": 181590,
    "keywordId": 36511789533,
    "state": "enabled",
    "keywordText": "pedialyte",
    "keywordCategory": null,
    "status": "awaiting_approval",
    "matchType": "exact",
    "bid": 2
  },
  "adItem": {
    "campaignId": 106061,
    "adGroupId": 106250,
    "itemId": "46492243",
    "adItemId": 52196,
    "bid": 2,
    "status": "enabled",
    "itemImageUrl": "http://i5.walmartimages.com/dfw/dce07b8c-4e1d/k2-_0175c3dd-7c6a-4088-bf9c-f1cd5b9209d8.v1.jpg",
    "itemPageUrl": "https://www.walmart.com/ip/46492243",
    "name": "TV Console"
  },
  "placementBidMultipliers": {
    "campaignId": 170621,
    "placementType": "Buy-Box",
    "multiplier": 0
  },
  "platformBidMultipliers": {
    "campaignId": 17062,
    "platformType": "Desktop",
    "multiplier": 0
  },
  "campaignPlacements": {
    "campaignId": 600002,
    "placements": {
      "placement": "Search Carousel",
      "status": "included"
    }
  }
}

Sample Response 5

[
  {
    "code": "success",
    "snapshotId": "5",
    "details": "https://advertising.walmart.com/file/5",
    " jobStatus ": "done"
  }
]

Example of the content of snapshot with id “5”. The file format is “json”:

Note: If a campaign has two Sponsored Brand profiles, the response will have 2 different Sponsored Brand profile IDs associated with the same campaign ID and ad group ID with the Sponsored Brand profile’s respective status

{
  "sbaProfiles": [
    {
      "searchAmpName": "text1",
      "headLineText": "text2",
      "sbaProfileId": 600000,
      "logoUrl": "logo URL",
      "clickUrl": "https://www.walmart.com",
      "reviewStatus": "pending",
      "reviewReason": null,
      "adGroupId": 600001,
      "campaignId": 200001,
      "status": "enabled"
    }
  ],
  "categories": [
    {
      "adGroupId": 100001,
      "campaignId": 100002,
      "id": 100003,
      "categoryId": "4908_439045_1010345",
      "state": "enabled",
      "bid": 5.23
    }
  ]
}

Sample Response 6

[
  {
     "code": "success",
     "snapshotId": "6",
     "details"   : "https://advertising.walmart.com/file/6",
     "jobStatus": "done"
  }
]

Example of the content of snapshot with id “6”. The file format is “json”:

{
          "campaigns":[
              {
                  "name": "Video Campaign",
                  "campaignType": "video",
                  "targetingType": "manual",
                  "status": "Proposal",
                  "budgetType": "both",
                  "startDate": "%currentDate%",
                  "endDate": "%currentDatePlus1Month%",
                  "totalBudget": 10000.0,
                  "dailyBudget": 2000.0,
                  "rollover": true,
                  "advertiserId": 600001,
                  "campaignId": 600007,
                  "channel": "Walmart.com"
              }
              ],
          "adGroups":[
              {
                  "adGroupId":600008,
                  "name":"Ad Group Video",
                  "status":"Enabled",
                  "campaignId":600007
              }
              ],

"keywords":[
              {
                  "campaignId":600006,
                  "adGroupId":600007,
                  "keywordId":600007,
                  "state":"enabled",
                  "keywordText":"sv keyword 2 normalized",
                  "keywordCategory":null,
                  "status":"pending",
                  "matchType":"exact",
                  "bid":5.85
              },
              {
                  "campaignId":600005,
                  "adGroupId":600006,
                  "keywordId":600008,
                  "state":"enabled",
                  "keywordText":"sv keyword 1 normalized",
                  "keywordCategory":null,
                  "status":"pending",
                  "matchType":"exact",
                  "bid":5.85
              }
              ],
          "adItem":[
              {
                  "campaignId":600001,
                  "adGroupId":600001,
                  "itemId":"562728956",
                  "adItemId":600003,
                  "bid":3.0,
                  "status":"enabled",
            "itemImageUrl":"https://i5.walmartimages.com/asr/905eb620-b036-48e9-b8df-8a00257efca0_1.cd6ce64707093979d61b67379b985e1d.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff",
                  "name":"TV",
                 "itemPageUrl":"https://www.walmart.com/ip/562728956",
                  "reviewReason": null,
                  "reviewStatus": "approved"
              },
              {
                  "campaignId":600002,
                  "adGroupId":600003,
                  "itemId":"45769024",
                  "adItemId":600004,
                  "bid":1.5,
                  "status":"enabled",
            "itemImageUrl":"https://i5.walmartimages.com/asr/95bf1b03-dd4a-41df-8474-730592348c96_1.3833b878a414a6995eaae81e792b635c.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff",
                  "name":"TV Stand",
                  "itemPageUrl":"https://www.walmart.com/ip/45769024",
                  "reviewReason": null,
                  "reviewStatus": "approved"
              }
              ],
          "adGroupMedias": [
              {
                  "campaignId": 600007,
                  "adGroupId": 600008,
                  "adGroupMediaId": 600003,
                  "mediaId": 600001,
                  "reviewStatus": "pending",
                  "reviewReason": null,
                  "status": "enabled"
              }
          ]
        }

Rate limits on API operations

There is a rate limit in place on the allowed number of API operations per hour.

Operations per hour are computed as the sum of number of changes requested across all API requests during the hour.

For example, 5 keyword bid changes, creation of an ad group, adding an item, and a snapshot report request in any given hour, would be counted as 8 operations.

You will receive an HTTP 429 status error code and an error message about rule enforced in case of breaking ops limit.

To learn more about current applicable limits specific to your integration, please reach out to the API Partner Enablement team.