Skip to main content
API docs by Redocly

DoorDash Ads API (1.0.27)

DoorDash Ads API for Sponsored Products for campaign management and reporting operations.

Please see DoorDash CPG Advertiser Guide & FAQ for more details about Ads functionalities.

Release Notes

v1.0.27 (May 4, 2026)

  • Minimum ROAS for Sponsored Products Automatic Bidding
    • Setting a minimum ROAS in automatic bidding helps manage performance goals at the campaign level.

Campaigns

Create campaign

Create a single campaign.

Authorizations:
Ads API Key Authentication
path Parameters
campaignType
required
string

Indicates campaign type. 'sp' for Sponsored Products or 'sb' for Sponsored Brand

Request Body schema: application/json

A campaign to create.

name
required
string (Name)

Resource name.

description
string (Description)

Resource description.

required
object (BudgetWrite) non-empty

At least one of daily or lifetime budget must be configured.

startDate
required
string (StartDate)

Start date for the resource to go live. The format of the date is yyyy-MM-dd HH:mm:ss.

endDate
string (EndDate)

End date for the resource to stop running. The format of the date is yyyy-MM-dd HH:mm:ss.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "budget": {
    },
  • "startDate": "2025-11-01 00:00:00",
  • "endDate": "2025-12-01 00:00:00"
}

Response samples

Content type
application/json
{
  • "campaignId": "string",
  • "name": "string",
  • "description": "string",
  • "status": "INCOMPLETE",
  • "statusDescription": "string",
  • "code": "string",
  • "codeDescription": "string",
  • "campaignType": "SPONSORED_PRODUCTS",
  • "budget": {
    },
  • "startDate": "2025-11-01 00:00:00",
  • "endDate": "2025-12-01 00:00:00",
  • "placementType": "AUTOMATIC",
  • "permission": {
    }
}

Update campaign

Update a single campaign.

Authorizations:
Ads API Key Authentication
path Parameters
campaignType
required
string

Indicates campaign type. 'sp' for Sponsored Products or 'sb' for Sponsored Brand

Request Body schema: application/json

A partial campaign object used to update an existing campaign.

campaignId
required
string (CampaignId)

Unique campaign identifier.

name
string (Name)

Resource name.

description
string (Description)

Resource description.

status
string (StatusWrite)
Enum: "ACTIVE" "PAUSED" "ENDED"

Current resource state.

object (BudgetWrite) non-empty

At least one of daily or lifetime budget must be configured.

startDate
string (StartDate)

Start date for the resource to go live. The format of the date is yyyy-MM-dd HH:mm:ss.

endDate
string (EndDate)

End date for the resource to stop running. The format of the date is yyyy-MM-dd HH:mm:ss.

Responses

Request samples

Content type
application/json
{
  • "campaignId": "string",
  • "name": "string",
  • "description": "string",
  • "status": "ACTIVE",
  • "budget": {
    },
  • "startDate": "2025-11-01 00:00:00",
  • "endDate": "2025-12-01 00:00:00"
}

Response samples

Content type
application/json
{
  • "campaignId": "string",
  • "name": "string",
  • "description": "string",
  • "status": "INCOMPLETE",
  • "statusDescription": "string",
  • "code": "string",
  • "codeDescription": "string",
  • "campaignType": "SPONSORED_PRODUCTS",
  • "budget": {
    },
  • "startDate": "2025-11-01 00:00:00",
  • "endDate": "2025-12-01 00:00:00",
  • "placementType": "AUTOMATIC",
  • "permission": {
    }
}

Get campaigns

Get a list of campaigns.

Authorizations:
Ads API Key Authentication
path Parameters
campaignType
required
string

Indicates campaign type. 'sp' for Sponsored Products or 'sb' for Sponsored Brand

query Parameters
startIndex
number
Default: 0

0-indexed record offset for the result set. Defaults to 0.

count
number

Number of records to include in the paged response.

Responses

Response samples

Content type
application/json
{
  • "campaigns": [
    ]
}

Get campaign by ID

Get a single campaign by the provided identifier.

Authorizations:
Ads API Key Authentication
path Parameters
campaignType
required
string

Indicates campaign type. 'sp' for Sponsored Products or 'sb' for Sponsored Brand

campaignId
required
string

Unique identifier for a campaign

Responses

Response samples

Content type
application/json
{
  • "campaignId": "string",
  • "name": "string",
  • "description": "string",
  • "status": "INCOMPLETE",
  • "statusDescription": "string",
  • "code": "string",
  • "codeDescription": "string",
  • "campaignType": "SPONSORED_PRODUCTS",
  • "budget": {
    },
  • "startDate": "2025-11-01 00:00:00",
  • "endDate": "2025-12-01 00:00:00",
  • "placementType": "AUTOMATIC",
  • "permission": {
    }
}

Get budget capout recommendations

Get budget capout report and recommendations for the provided campaign ID.

Authorizations:
Ads API Key Authentication
path Parameters
campaignId
required
string

Unique identifier for a campaign

Responses

Response samples

Content type
application/json
{
  • "adEntityId": "string",
  • "type": "string",
  • "value": {
    }
}

Ad Groups

Create ad group

Create a single ad group.

Authorizations:
Ads API Key Authentication
path Parameters
campaignType
required
string

Indicates campaign type. 'sp' for Sponsored Products or 'sb' for Sponsored Brand

Request Body schema: application/json

An ad group to create.

campaignId
required
string (CampaignId)

Unique campaign identifier.

name
required
string (Name)

Resource name.

startDate
required
string (StartDate)

Start date for the resource to go live. The format of the date is yyyy-MM-dd HH:mm:ss.

endDate
required
string (EndDate)

End date for the resource to stop running. The format of the date is yyyy-MM-dd HH:mm:ss.

required
object (AutomaticBidRequest)

Bid for all ad group placement types. Either automaticBid OR manualTargets must be set.

Bid unitAmount range per advertiser country code is outlined in the following table. Ranges are presented as 'Minimum-Maximum'.

Country code (currency) Minimum-Maximum
US (USD) 80-10,000
CA (CAD) 80-10,000
AU (AUD) 80-10,000
required
Array of objects (ManualTargetsRequest)

Sponsored Products only. Bid for specific ad group placement types. Either automaticBid OR manualTargets must be set.

Supported ad group placement type combinations are represented in the following table.

Valid combinations
CATEGORIES, COLLECTION, SEARCH, and DOUBLEDASH
CATEGORIES, COLLECTION, and SEARCH
DOUBLEDASH only

Bid unitAmount range per advertiser country code per placement type is outlined in the following table. Ranges are presented as 'Minimum-Maximum'.

Placement type US (USD) CA (CAD) AU (AUD)
CATEGORIES 40-10,000 30-10,000 40-10,000
COLLECTION 30-10,000 40-10,000 50-10,000
SEARCH 60-10,000 40-10,000 50-10,000
DOUBLEDASH 80-10,000 80-10,000 80-10,000
targetBusinessIds
Array of strings (TargetBusinessIds)

Business IDs for merchant targeting (domestic, non-alcohol only).

Array of objects (BehavioralTargetsRequest)

Behavioral targeting configuration to customize the audience of this ad group campaign.

Array of objects (Daypart)

[Beta] Configure custom schedule for when people see this ad group campaign.

bidType
string (BidType)
Enum: "AUTOMATED" "MANUAL"

Sponsored Products US market only. Configure the AUTOMATED BidType to enable a new bidding strategy: Automatic Bidding. This strategy automatically sets and adjusts your bids in real-time to maximize clicks at the lowest cost.

When choosing Automatic Bidding with the AUTOMATED BidType, manualTargets must be set. Bid in manualTargets is not required.

All ad groups within the same campaign must use the same BidType. Specifying different BidTypes is not allowed.

bidMinRoas
double (BidMinRoas) [ 0.1 .. 6 ]

Specify the BidMinRoas value when configuring the Automatic Bidding strategy.

Choose a minimum ROAS that aligns with your campaign goals. If not specified, a default minimum guardrail of 2.0x will be applied.

Array of objects (InterestTarget)
Array of objects (KeywordsBiddingRequest)

Sponsored Products only. Keyword search bidding configuration to customize the audience of this ad group campaign.

Responses

Request samples

Content type
application/json
{
  • "campaignId": "string",
  • "name": "string",
  • "startDate": "2025-11-01 00:00:00",
  • "endDate": "2025-12-01 00:00:00",
  • "automaticBid": {
    },
  • "manualTargets": [
    ],
  • "targetBusinessIds": [
    ],
  • "behavioralTargets": [
    ],
  • "dayparts": [
    ],
  • "bidType": "AUTOMATED",
  • "bidMinRoas": 2,
  • "interestTargets": [
    ],
  • "keywordsBidding": [
    ]
}

Response samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "name": "string",
  • "status": "INCOMPLETE",
  • "statusDescription": "string",
  • "startDate": "2025-11-01 00:00:00",
  • "endDate": "2025-12-01 00:00:00",
  • "automaticBid": {
    },
  • "code": "string",
  • "codeDescription": "string",
  • "manualTargets": [
    ],
  • "keywordsBidding": [
    ],
  • "targetBusinessIds": [
    ],
  • "behavioralTargets": [
    ],
  • "dayparts": [
    ],
  • "bidType": "AUTOMATED",
  • "bidMinRoas": 2,
  • "interestTargets": [
    ]
}

Update ad group

Update a single ad group.

Authorizations:
Ads API Key Authentication
path Parameters
campaignType
required
string

Indicates campaign type. 'sp' for Sponsored Products or 'sb' for Sponsored Brand

Request Body schema: application/json

A partial ad group object used to update an existing ad group.

campaignId
required
string (CampaignId)

Unique campaign identifier.

adGroupId
required
string (AdGroupId)

Unique ad group identifier.

name
string (Name)

Resource name.

status
string (StatusWrite)
Enum: "ACTIVE" "PAUSED" "ENDED"

Current resource state.

startDate
string (StartDate)

Start date for the resource to go live. The format of the date is yyyy-MM-dd HH:mm:ss.

endDate
string (EndDate)

End date for the resource to stop running. The format of the date is yyyy-MM-dd HH:mm:ss.

object (AutomaticBidRequest)

Bid for all ad group placement types. Either automaticBid OR manualTargets must be set.

Bid unitAmount range per advertiser country code is outlined in the following table. Ranges are presented as 'Minimum-Maximum'.

Country code (currency) Minimum-Maximum
US (USD) 80-10,000
CA (CAD) 80-10,000
AU (AUD) 80-10,000
Array of objects (ManualTargetsRequest)

Sponsored Products only. Bid for specific ad group placement types. Either automaticBid OR manualTargets must be set.

Supported ad group placement type combinations are represented in the following table.

Valid combinations
CATEGORIES, COLLECTION, SEARCH, and DOUBLEDASH
CATEGORIES, COLLECTION, and SEARCH
DOUBLEDASH only

Bid unitAmount range per advertiser country code per placement type is outlined in the following table. Ranges are presented as 'Minimum-Maximum'.

Placement type US (USD) CA (CAD) AU (AUD)
CATEGORIES 40-10,000 30-10,000 40-10,000
COLLECTION 30-10,000 40-10,000 50-10,000
SEARCH 60-10,000 40-10,000 50-10,000
DOUBLEDASH 80-10,000 80-10,000 80-10,000
Array of objects (KeywordsBiddingRequest)

Sponsored Products only. Keyword search bidding configuration to customize the audience of this ad group campaign.

targetBusinessIds
Array of strings (TargetBusinessIds)

Business IDs for merchant targeting (domestic, non-alcohol only).

Array of objects (BehavioralTargetsRequest)

Behavioral targeting configuration to customize the audience of this ad group campaign.

Array of objects (Daypart)

[Beta] Custom schedule for when people see this ad group campaign.

bidType
string (BidType)
Enum: "AUTOMATED" "MANUAL"

Sponsored Products US market only. Configure the AUTOMATED BidType to enable a new bidding strategy: Automatic Bidding. This strategy automatically sets and adjusts your bids in real-time to maximize clicks at the lowest cost.

When choosing Automatic Bidding with the AUTOMATED BidType, manualTargets must be set. Bid in manualTargets is not required.

All ad groups within the same campaign must use the same BidType. Specifying different BidTypes is not allowed.

bidMinRoas
double (BidMinRoas) [ 0.1 .. 6 ]

Specify the BidMinRoas value when configuring the Automatic Bidding strategy.

Choose a minimum ROAS that aligns with your campaign goals. If not specified, a default minimum guardrail of 2.0x will be applied.

Array of objects (InterestTarget)

Responses

Request samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "name": "string",
  • "status": "ACTIVE",
  • "startDate": "2025-11-01 00:00:00",
  • "endDate": "2025-12-01 00:00:00",
  • "automaticBid": {
    },
  • "manualTargets": [
    ],
  • "keywordsBidding": [
    ],
  • "targetBusinessIds": [
    ],
  • "behavioralTargets": [
    ],
  • "dayparts": [
    ],
  • "bidType": "AUTOMATED",
  • "bidMinRoas": 2,
  • "interestTargets": [
    ]
}

Response samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "name": "string",
  • "status": "INCOMPLETE",
  • "statusDescription": "string",
  • "startDate": "2025-11-01 00:00:00",
  • "endDate": "2025-12-01 00:00:00",
  • "automaticBid": {
    },
  • "code": "string",
  • "codeDescription": "string",
  • "manualTargets": [
    ],
  • "keywordsBidding": [
    ],
  • "targetBusinessIds": [
    ],
  • "behavioralTargets": [
    ],
  • "dayparts": [
    ],
  • "bidType": "AUTOMATED",
  • "bidMinRoas": 2,
  • "interestTargets": [
    ]
}

Get ad groups

Get a list of ad groups, optionally filtered by campaign IDs and/or ad group IDs.

Authorizations:
Ads API Key Authentication
path Parameters
campaignType
required
string

Indicates campaign type. 'sp' for Sponsored Products or 'sb' for Sponsored Brand

query Parameters
startIndex
number
Default: 0

0-indexed record offset for the result set. Defaults to 0.

count
number

Number of records to include in the paged response.

campaignIdFilter
string

A comma-delimited list of campaign identifiers. At least one of campaignIdFilter and adGroupIdFilter is required.

adGroupIdFilter
string

A comma-delimited list of ad group identifiers. At least one of campaignIdFilter and adGroupIdFilter is required.

Responses

Response samples

Content type
application/json
{
  • "adGroups": [
    ]
}

Get ad group by ID

Get a single ad group by the provided identifier.

Authorizations:
Ads API Key Authentication
path Parameters
campaignType
required
string

Indicates campaign type. 'sp' for Sponsored Products or 'sb' for Sponsored Brand

adGroupId
required
string

The identifier of an existing ad group.

Responses

Response samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "name": "string",
  • "status": "INCOMPLETE",
  • "statusDescription": "string",
  • "startDate": "2025-11-01 00:00:00",
  • "endDate": "2025-12-01 00:00:00",
  • "automaticBid": {
    },
  • "code": "string",
  • "codeDescription": "string",
  • "manualTargets": [
    ],
  • "keywordsBidding": [
    ],
  • "targetBusinessIds": [
    ],
  • "behavioralTargets": [
    ],
  • "dayparts": [
    ],
  • "bidType": "AUTOMATED",
  • "bidMinRoas": 2,
  • "interestTargets": [
    ]
}

Product Ads

Create product ad

Create a single product ad the provided campaign and ad group IDs.

Authorizations:
Ads API Key Authentication
path Parameters
campaignType
required
string

Indicates campaign type. 'sp' for Sponsored Products or 'sb' for Sponsored Brand

Request Body schema: application/json

A product ad to create.

campaignId
required
string (CampaignId)

Unique campaign identifier.

adGroupId
required
string (AdGroupId)

Unique ad group identifier.

idType
required
string (ProductIdType)
Enum: "GTIN_14" "UPC" "DD_SIC"

Product ID type

productId
required
string (ProductId)

Unique product identifier based on product ID type.

isPriority
boolean (IsPriority)

Indicates pinned product for Sponsored Brand campaigns.

Responses

Request samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "idType": "GTIN_14",
  • "productId": "string",
  • "isPriority": false
}

Response samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "idType": "GTIN_14",
  • "productId": "string",
  • "ddSic": "string",
  • "isPriority": false,
  • "upcs": [
    ],
  • "gtin14s": [
    ]
}

Get product ads

Get a list of product ads, optionally filtered by campaign IDs and/or adGroup IDs.

Authorizations:
Ads API Key Authentication
path Parameters
campaignType
required
string

Indicates campaign type. 'sp' for Sponsored Products or 'sb' for Sponsored Brand

query Parameters
startIndex
number
Default: 0

0-indexed record offset for the result set. Defaults to 0.

count
number

Number of records to include in the paged response.

campaignIdFilter
string

A comma-delimited list of campaign identifiers. At least one of campaignIdFilter and adGroupIdFilter is required.

adGroupIdFilter
string

A comma-delimited list of ad group identifiers. At least one of campaignIdFilter and adGroupIdFilter is required.

Responses

Response samples

Content type
application/json
{
  • "productAds": [
    ]
}

Delete product ad

Delete a single product ad by the provided identifier.

Authorizations:
Ads API Key Authentication
path Parameters
campaignType
required
string

Indicates campaign type. 'sp' for Sponsored Products or 'sb' for Sponsored Brand

Request Body schema: application/json

The identifier of an existing product ad.

campaignId
required
string (CampaignId)

Unique campaign identifier.

adGroupId
required
string (AdGroupId)

Unique ad group identifier.

idType
required
string (ProductIdType)
Enum: "GTIN_14" "UPC" "DD_SIC"

Product ID type

productId
required
string (ProductId)

Unique product identifier based on product ID type.

Responses

Request samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "idType": "GTIN_14",
  • "productId": "string"
}

Response samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "idType": "GTIN_14",
  • "productId": "string",
  • "ddSic": "string",
  • "code": "string",
  • "codeDescription": "string",
  • "upcs": [
    ],
  • "gtin14s": [
    ]
}

Assets

Create a new asset

Create a new asset and get upload URL

Authorizations:
Ads API Key Authentication
Request Body schema: application/json
required
name
required
string

Name of the asset

type
required
string (AssetType)
Enum: "IMAGE" "VIDEO"

Type of the asset

width
required
integer <int64>

Width of the asset in pixels

height
required
integer <int64>

Height of the asset in pixels

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "type": "IMAGE",
  • "width": 0,
  • "height": 0
}

Response samples

Content type
application/json
{
  • "asset": {
    },
  • "uploadUrl": "string",
  • "uploadUrlExpiresAt": "2019-08-24T14:15:22Z"
}

Get asset by ID

Get a single asset by its identifier

Authorizations:
Ads API Key Authentication
path Parameters
assetId
required
string

Asset identifier

Responses

Response samples

Content type
application/json
{
  • "asset": {
    }
}

Register an asset

Register an asset after upload is complete

Authorizations:
Ads API Key Authentication
path Parameters
assetId
required
string

Asset identifier

Responses

Response samples

Content type
application/json
{
  • "asset": {
    }
}

Creatives (SB)

For Sponsored Brand campaigns only.

Create creatives

Create creatives for a campaign and ad group

Authorizations:
Ads API Key Authentication
Request Body schema: application/json
required
campaignId
required
string

Campaign identifier

adGroupId
required
string

Ad group identifier

required
Array of BrandHeaderImageCreative (object) or BrandLandingPageCreative (object)

Responses

Request samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "creatives": [
    ]
}

Response samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "creatives": [
    ]
}

Get creatives

Get creatives with pagination support

Authorizations:
Ads API Key Authentication
query Parameters
campaignIdFilter
required
string

A comma-delimited list of campaign identifiers

limit
integer
Default: 20

Number of results to return per page

searchAfter
string

Null when results included all matching resources. Base64 encoded string of the request payload when there are additional resources not included within the current result set.

Responses

Response samples

Content type
application/json
{
  • "searchAfter": "string",
  • "results": [
    ]
}

Merchants (Retailers)

To retrieve business IDs available for merchant targeting.

Get merchants

Get merchant business IDs for targeting

Authorizations:
Ads API Key Authentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Keywords (SP)

For Sponsored Products campaigns only.

Get recommended keywords

Get a list of recommended keywords for the provided products and placement type.

Authorizations:
Ads API Key Authentication
Request Body schema: application/json

List of placement types and list of product IDs.

required
Array of objects (Placement)

Placement type must be 'SEARCH' for recommended keywords.

required
Array of objects

List of product IDs

Responses

Request samples

Content type
application/json
{
  • "placements": [
    ],
  • "products": [
    ]
}

Response samples

Content type
application/json
{
  • "recommendedKeywords": {
    }
}

Get recommended keywords with status in ad group

Get a list of recommended keywords and their status within the given ad group (e.g. new) for the provided products and placement type.

Authorizations:
Ads API Key Authentication
path Parameters
adGroupId
required
string

Unique identifier for an ad group

Request Body schema: application/json

List of placement types and list of product IDs.

required
Array of objects (Placement)

Placement type must be 'SEARCH' for recommended keywords.

required
Array of objects

List of product IDs

Responses

Request samples

Content type
application/json
{
  • "placements": [
    ],
  • "products": [
    ]
}

Response samples

Content type
application/json
{
  • "recommendedKeywords": {
    }
}

Resources

To retrieve brands and categories available for behavioral targeting.

Search resources

Get a list of resources (categories or advertiser's brands) based on classification type and resource type.

Authorizations:
Ads API Key Authentication
Request Body schema: application/json
classificationType
required
string (ClassificationType)
Enum: "BRAND" "CATEGORY"
resourceTypes
Array of strings
Items Enum: "L1_BRAND" "L1_CATEGORY" "L2_CATEGORY"

When classificationType = BRAND, resourceTypes must be at least one of [L1_BRAND].

When classificationType = CATEGORY, resourceTypes must be at least one of [L1_CATEGORY, L2_CATEGORY].

When not provided, will return only L1s for the provided classification.

When provided, will returns associated resources of the provided classification type.

searchAfter
string

Null when results included all matching resources. Base64 encoded string of the request payload when there are additional resources not included within the current result set.

limit
number
Default: 10

Responses

Request samples

Content type
application/json
{
  • "classificationType": "BRAND",
  • "resourceTypes": [ ],
  • "searchAfter": "string",
  • "limit": 10
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "searchAfter": "string"
}

Catalog

Validate products

Validate eligibility of a list of catalog products. Products in result will be returned in the same order as provided in the request.

Authorizations:
Ads API Key Authentication
Request Body schema: application/json

List of product IDs

Array ([ 1 .. 100 ] items)
idType
string (ProductIdType)
Enum: "GTIN_14" "UPC" "DD_SIC"

Product ID type

productId
string (ProductId)

Unique product identifier based on product ID type.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Report

Create report

Create a single report. See request samples for example report requests. Note that there is a 3 year rolling window for reports (startDate cannot be more than three years ago).

Authorizations:
Ads API Key Authentication
path Parameters
recordType
required
object
Examples:
  • CAMPAIGN - Campaign Report (SB, SP)
  • ADGROUP - Campaign Performance Report (SB, SP), Placement Report (SP)
  • PRODUCT - Product Report (SB, SP)
  • KEYWORD - Keyword Report (SP)
  • CATEGORY_SHARE - Category Share Report
  • PRODUCT_SALES - Product Sales Report
  • CATALOG - Catalog Report
  • INTEREST_INSIGHTS - Interest Insight Report

one of: CAMPAIGN, ADGROUP, PRODUCT, KEYWORD, CATEGORY_SHARE, PRODUCT_SALES, CATALOG, INTEREST_INSIGHTS

Request Body schema: application/json

Report request parameters.

reportName
required
string

Name of the report

fileType
string (FileType)
Value: "CSV"

Report file type.

startDate
required
string (Date)

A date string in format of yyyy-MM-dd HH:mm:ss

endDate
required
string (Date)

A date string in format of yyyy-MM-dd HH:mm:ss

segment
string (Segment)
Enum: "PLACEMENT" "NONE"

A secondary dimension used to further segment certain types of reports.

groupBys
Array of strings (GroupBy)
Items Enum: "BRAND" "VERTICAL" "CATEGORY" "ITEM" "RETAILER" "DISH"
  • "CATEGORY" only available for Nielsen Category Share reports for Alcohol and non-US advertisers, and Circana Category Share reports for US advertisers.
  • "RETAILER" only available to Product Sales reports for Diamond and Gold tier advertisers.
  • "RETAILER" and "VERTICAL" cannot be both requested in the same report.
  • "DISH" only available for Interest Insights reports.
timeGranularity
string (TimeGranularity)
Enum: "HOUR" "DAY" "WEEK" "MONTH" "NONE"
  • HOUR (for dayparted reports) is currently in Beta.
  • Category Share supports Week or Month grain
  • Product Sales supports Day, Week, or Month grain
Array of objects (CatalogReportFilter)
campaignTypes
Array of strings (ReportCampaignTypes)
Items Enum: "SPONSORED_PRODUCTS" "SPONSORED_BRAND"
  • Type of campaigns to include in the report.
  • Only relevant for Marketing reports (when recordType is one of {CAMPAIGN, ADGROUP, PRODUCT, KEYWORD}).
categoryProvider
string (CategoryProvider)
Enum: "NIELSEN" "CIRCANA"

Data provider for product category definitions. Only applicable for Category Share reports. Note that Circana is only available to US advertisers.

Responses

Request samples

Content type
application/json
Example
{
  • "reportName": "Sponsored Brand Campaign Report",
  • "startDate": "2025-11-01 00:00:00",
  • "endDate": "2025-11-01 00:00:00",
  • "campaignTypes": [
    ]
}

Response samples

Content type
application/json
{
  • "reportId": "string"
}

Download report

Download a single report by the provided identifier.

Authorizations:
Ads API Key Authentication
path Parameters
reportId
required
string

The identifier for a report.

Responses

Response samples

Content type
application/json
{}

Get reports

Get a list of reports, optionally filtered by status or report type.

Authorizations:
Ads API Key Authentication
query Parameters
startDate
required
string
Example: startDate=2025-11-01 00:00:00

Get all reports requested after this date.

endDate
string
Example: endDate=2025-11-01 00:00:00

Get all reports requested before this date.

startIndex
number
Default: 0

0-indexed record offset for the result set. Defaults to 0.

count
number

Number of records to include in the paged response.

status
string (ReportStatus)
Enum: "SCHEDULED" "PROCESSING" "COMPLETED" "ERROR"
Example: status=COMPLETED

Filter report by status.

Responses

Response samples

Content type
application/json
{
  • "totalCount": 0,
  • "reports": [
    ]
}

Menu

Get dish labels

Get available dish labels available for interest targeting

Authorizations:
Ads API Key Authentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Targeting

Get audience size estimation

Gets an audience size estimation for a campaign to be created or updated based on the targeting

Authorizations:
Ads API Key Authentication
Request Body schema: application/json
required
required
Array of objects (TargetingFilters)
Array
field
required
string
Enum: "L1_BRANDS_EXISTING" "L1_BRANDS_NEW" "L1_CATEGORY_EXISTING" "L1_CATEGORY_LAPSED" "L1_CATEGORY_NEW" "BOUGHT_FROM_RETAILER" "L2_DISH_INTEREST" "PLACEMENT" "CAMPAIGN_TYPE"

Targeting field to be specified

values
required
Array of strings non-empty

Responses

Request samples

Content type
application/json
{
  • "filters": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]