Skip to main content
API docs by Redocly

DoorDash Ads API (1.0.19)

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.19 (effective Apr 7, 2025)

  • Set up docs on Developer Portal
  • Campaigns
    • Net new budget capout recommendations endpoint
  • Ad Groups
    • Now supports behavioral targeting
    • [Beta] Now supports dayparting
  • Report
    • Now supports business reporting (Category Share, Product Sales)
    • [Beta] Now supports dayparted (hourly) reporting
    • Now supports catalog reporting
  • Keywords
    • Now supports retrieving recommended keywords with status within an ad group context
  • Resources
    • Net new resources search endpoint

[Beta]: Currently only rolled out to certain advertisers. GA launch for dayparting is estimated to be end of May 2025.

Campaigns

Create campaign

Create a single campaign.

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

A campaign to create.

name
required
string (Name)

Resource name.

description
string (Description)

Resource description.

campaignType
required
string (CampaignType)
Value: "SPONSORED_PRODUCTS"

The advertising product managed by this campaign.

required
object (BudgetWrite) non-empty

Only one of daily or lifetime budget may 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",
  • "campaignType": "SPONSORED_PRODUCTS",
  • "budget": {
    },
  • "startDate": "2025-05-01 00:00:00",
  • "endDate": "2025-05-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-05-01 00:00:00",
  • "endDate": "2025-05-01 00:00:00",
  • "placementType": "AUTOMATIC",
  • "permission": {
    }
}

Update campaign

Update a single campaign.

Authorizations:
Ads API Key Authentication
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.

campaignType
string (CampaignType)
Value: "SPONSORED_PRODUCTS"

The advertising product managed by this campaign.

description
string (Description)

Resource description.

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

Current resource state.

object (BudgetWrite) non-empty

Only one of daily or lifetime budget may 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",
  • "campaignType": "SPONSORED_PRODUCTS",
  • "description": "string",
  • "status": "ACTIVE",
  • "budget": {
    },
  • "startDate": "2025-05-01 00:00:00",
  • "endDate": "2025-05-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-05-01 00:00:00",
  • "endDate": "2025-05-01 00:00:00",
  • "placementType": "AUTOMATIC",
  • "permission": {
    }
}

Get campaigns

Get a list of campaigns.

Authorizations:
Ads API Key Authentication
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
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-05-01 00:00:00",
  • "endDate": "2025-05-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
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

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 (ManualTargetWrite)

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 (BehavioralTargetWrite)

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.

Responses

Request samples

Content type
application/json
{
  • "campaignId": "string",
  • "name": "string",
  • "startDate": "2025-05-01 00:00:00",
  • "endDate": "2025-05-01 00:00:00",
  • "automaticBid": {
    },
  • "manualTargets": [
    ],
  • "behavioralTargets": [
    ],
  • "dayparts": [
    ]
}

Response samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "name": "string",
  • "status": "INCOMPLETE",
  • "statusDescription": "string",
  • "startDate": "2025-05-01 00:00:00",
  • "endDate": "2025-05-01 00:00:00",
  • "automaticBid": {
    },
  • "code": "string",
  • "codeDescription": "string",
  • "manualTargets": [
    ],
  • "keywordsBidding": [
    ],
  • "behavioralTargets": [
    ],
  • "dayparts": [
    ]
}

Update ad group

Update a single ad group.

Authorizations:
Ads API Key Authentication
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

Bid for all ad group placement types. 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 (ManualTargetWrite)

Bid for specific ad group placement types. 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 (KeywordsBiddingWrite)

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

Array of objects (BehavioralTargetWrite)

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.

Responses

Request samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "name": "string",
  • "status": "ACTIVE",
  • "startDate": "2025-05-01 00:00:00",
  • "endDate": "2025-05-01 00:00:00",
  • "automaticBid": {
    },
  • "manualTargets": [
    ],
  • "keywordsBidding": [
    ],
  • "behavioralTargets": [
    ],
  • "dayparts": [
    ]
}

Response samples

Content type
application/json
{
  • "campaignId": "string",
  • "adGroupId": "string",
  • "name": "string",
  • "status": "INCOMPLETE",
  • "statusDescription": "string",
  • "startDate": "2025-05-01 00:00:00",
  • "endDate": "2025-05-01 00:00:00",
  • "automaticBid": {
    },
  • "code": "string",
  • "codeDescription": "string",
  • "manualTargets": [
    ],
  • "keywordsBidding": [
    ],
  • "behavioralTargets": [
    ],
  • "dayparts": [
    ]
}

Get ad groups

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

Authorizations:
Ads API Key Authentication
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
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-05-01 00:00:00",
  • "endDate": "2025-05-01 00:00:00",
  • "automaticBid": {
    },
  • "code": "string",
  • "codeDescription": "string",
  • "manualTargets": [
    ],
  • "keywordsBidding": [
    ],
  • "behavioralTargets": [
    ],
  • "dayparts": [
    ]
}

Product Ads

Create product ad

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

Authorizations:
Ads API Key Authentication
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.

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"
}

Get product ads

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

Authorizations:
Ads API Key Authentication
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
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"
}

Report

Create report

Create a single report.

Authorizations:
Ads API Key Authentication
path Parameters
recordType
required
object

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

Request Body schema: application/json

Report request parameters.

reportName
required
string

name of a report

fileType
string (FileType)
Value: "CSV"

Report file type.

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.

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"

CATEGORY only valid for Alcohol advertisers.

timeGranularity
string (TimeGranularity)
Enum: "HOUR" "DAY" "WEEK" "MONTH" "NONE"

Notes:

  • HOUR (for dayparted reports) is currently in Beta.
  • Access to other granularities depends on the advertiser's reporting tier:
    • Category Share
      • Diamond, Gold -> Week, Month
      • Silver, Bronze -> Month
      • Non-JBP -> Month
    • Product Sales
      • Diamond, Gold -> Day, Week, Month
      • Silver -> Week, Month
      • Bronze -> Month
      • Non-JBP -> Week
Array of objects (CatalogReportFilter)

Responses

Request samples

Content type
application/json
{
  • "reportName": "string",
  • "fileType": "CSV",
  • "startDate": "2025-05-01 00:00:00",
  • "endDate": "2025-05-01 00:00:00",
  • "segment": "PLACEMENT",
  • "groupBys": [
    ],
  • "timeGranularity": "HOUR",
  • "filters": [
    ]
}

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

Get all reports requested after this date.

endDate
string

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": [
    ]
}

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
[
  • {
    }
]

Keywords

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

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"
}