Ads Endpoints

Create, retrieve, update, and delete ads using these endpoints.

Overview

An Ad object connects a Creative to an ad group. The ad is the serving unit: It tells the system which ad creative to show when the ad group wins an auction. An ad group can contain multiple ads, but only one ad per ad group can be ENABLED at a time. Enabling a different ad requires pausing the one currently serving.

Creating an ad requires a name, a status, the adGroupId of the target ad group, and a creativeId referencing an existing Creative. Create the ad creative first, then reference its id here. The campaignId, adAccountId, and other system fields are read-only, and the system populates them automatically at creation.

Use the Ads Endpoints

Use these endpoints to create, retrieve, update, and delete ads:

Method	Path	Description
`POST`	`/v1/ads`	Post Ads creates a new ad.
`POST`	`/v1/ads/query`	Post Ads Query retrieves ads matching the specified filters.
`GET`	`/v1/ads/{id}`	Get Ads _id_ retrieves a single ad by its ID.
`PUT`	`/v1/ads/{id}`	Put Ads _id_ updates an existing ad.
`DELETE`	`/v1/ads/{id}`	Delete Ads _id_ soft-deletes an ad by its ID.

Track Ad Status and System Status

Ads have three status fields that together determine whether an ad is serving:

status: The advertiser-controlled field. Set it to ENABLED to let the ad serve, or PAUSED to stop delivery without deleting the ad. You can only update status and name after creation.
systemStatus: A system-computed field that reflects whether the ad is actually running. A value of RUNNING means the ad is active and eligible to serve, and a value of NOT_RUNNING means the system identified a condition that’s preventing delivery.
displayStatus: A system-computed field that represents a rolled-up label combining status and systemStatus into a single delivery state. See AdDisplayStatus for all values.

When systemStatus is NOT_RUNNING, the system populates the systemStatusReasons array with one or more values explaining why. Reasons marked App Store-specific apply only to App Store ads. Unless marked, a reason applies to both App Store and Apple Maps ads:

Reason	Description
`AD_APPROVAL_PENDING`	The ad is awaiting Apple review.
`AD_APPROVAL_REJECTED`	Apple reviewed and rejected the ad.
`AD_APPROVAL_CREATIVE_DOC_NOT_SUBMITTED`	The advertiser hasn’t submitted the required creative documentation for review.
`AD_APPROVAL_CREATIVE_DOC_PENDING`	Apple is reviewing the submitted creative documentation.
`AD_APPROVAL_CREATIVE_DOC_REJECTED`	Apple rejected the creative documentation during review.
`AD_APPROVAL_CREATIVE_DOC_EXPIRED`	The previously approved creative documentation has expired.
`PROCESSING`	General processing state. The ad isn’t yet ready to serve.
`PAUSED_BY_USER`	The advertiser set the ad’s `status` to `PAUSED`.
`PAUSED_BY_SYSTEM`	The system paused the ad due to a policy or account condition.
`DELETED_BY_USER`	The advertiser deleted the ad.
`CREATIVE_SET_INVALID`	The associated ad creative is invalid.
`CREATIVE_SET_UNSUPPORTED`	The current placement doesn’t support the associated ad creative type.
`CREATIVE_INVALID`	The associated ad creative is invalid and can’t serve.
`CREATIVE_PENDING`	The associated ad creative is pending validation or Apple review.
`CREATIVE_LOCALE_INCOMPATIBLE`	The ad creative locale doesn’t match the targeted market.
`PRODUCT_PAGE_DELETED`	App Store-specific. The developer deleted the linked product page in App Store Connect.
`PRODUCT_PAGE_HIDDEN`	App Store-specific. The developer hid the linked product page in App Store Connect.
`PRODUCT_PAGE_INCOMPATIBLE`	App Store-specific. The product page is incompatible with the current campaign configuration.
`PRODUCT_PAGE_INSUFFICIENT_ASSETS`	App Store-specific. The product page doesn’t have enough assets to render the ad.
`PRODUCT_PAGE_UNAVAILABLE`	App Store-specific. The product page is temporarily unavailable.

Interpret System Status Limiting Reasons

When an ad is running but delivering at reduced capacity, the system populates the systemStatusLimitingReasons array. Unlike systemStatusReasons, these reasons don’t stop delivery. Instead, they constrain reach. There’s one possible value, CREATIVE_POLICY_ISSUES, which means the ad creative associated with the ad has policy conditions that limit but don’t fully stop delivery.

Understand Apple Review Requirements

Apple must approve ads before they can serve. For App Store ads, the review covers the ad creative content and product page. For Apple Maps ads, the review covers the brand ad creative instead.

The CREATIVE_PENDING and CREATIVE_INVALID reasons reflect this review state. While an ad is under review, systemStatus is NOT_RUNNING and systemStatusReasons includes AD_APPROVAL_PENDING or CREATIVE_PENDING. Once Apple approves the ad, systemStatus changes to RUNNING unless the advertiser sets status to PAUSED or schedules a future start date.