Campaigns Endpoints

Overview

To promote iOS apps in the App Store or brands and locations on Apple Maps, use campaigns.

Use These Campaign Endpoints

The following endpoints create, retrieve, update, and delete campaigns, and return per-country limited-status details for legacy app campaigns:

Both App Store ads and Apple Maps ads share the same campaign, ad group, and reporting infrastructure. They differ in promotedObjectType, creative requirements, and bid strategy options.

Every campaign is scoped to a single ad account and identifies its promoted object through two immutable fields set at creation: promotedObjectType and promotedObjectId. For App Store campaigns, promotedObjectId is the app’s adamId. For Apple Maps campaigns, it’s the brand’s unique identifier. Retrieve the brand identifier from Query Brands or from GET /v1/advertiser-resources?resourceType=BUSINESS_BRAND. See Create a Campaign for the required fields and payload examples for each campaign type.

The following table compares how App Store and Apple Maps campaigns differ:

An ad account’s productFeatures gate which campaign type it can create. An account authorized with APPSTORE_APP_MANUAL can only create App Store campaigns, and an account authorized with BUSINESS_BRAND_MANUAL can only create Apple Maps campaigns. See ProductFeatures for details.

Promote Apps

App Store campaigns (promotedObjectType: APPSTORE_APP) promote iOS apps across App Store placements. See CampaignTargeting for the full list of accepted App Store country or region and placement targeting values.

The app must be available for purchase, download, or preorder in the App Store and Apple Ads must be available in the targeted countries. To check eligibility before creating a campaign, use Check App Eligibility. After you confirm eligibility, see Create a Campaign to create the campaign.

Promote Brands and Locations

Apple Maps campaigns (promotedObjectType: BUSINESS_BRAND) promote brands on Apple Maps. The brand must have eligibility.status: ELIGIBLE before a campaign can serve. The ad account must also have a BUSINESS_BRAND delegation linking it to the brand before campaigns can go live. See ProductFeatures for delegation requirements. The billingEvent can be TAPS (for MANUAL_CPT or MAX_ENGAGEMENTS) or IMPRESSIONS (for MANUAL_CPM).

See Ads on Apple Maps Endpoints for the full setup workflow, then see Create a Campaign to create the campaign.

Choose a Bid Strategy

The bidStrategy object is always present on a campaign and controls how the campaign competes in auctions. It’s required at creation: you must send both bidStrategyType and bidStrategyGoal, and the goal must match the type. See BidStrategy for the type and goal pairings.

Use the following table to match your goal to a bidStrategyType and bidStrategyGoal pair:

A Maximize Conversions bid strategy (MAX_CONVERSIONS) maximizes the number of tap-through conversions at or near your target CPA. It uses a cost-per-tap pricing model and requires an automated ad group.

To switch a campaign’s bid strategy after creation, send an updated bidStrategy object with a matching bidStrategyType/bidStrategyGoal pair via Update a Campaign. See BidStrategyUpdate for the field-level mechanics. For reports with a Maximize Conversions bid strategy, see Campaigns Report and Ad Groups Report.

Manage Budget Orders

A budget order enforces a spending cap for a group of campaigns within an ad account. Campaigns assigned to the same budget order share a common spend limit via the sharedBudgets field. Budget orders are available to Apple Ads customers on monthly invoicing. A campaign with shared budget assignments also requires a dailyBudget. Both controls function independently: dailyBudget caps daily spending. Each shared budget caps spending over its flight period.

See Budget Orders Endpoints for details on creating and managing budget orders.

Monitor Campaign and System Status

Campaigns have three status fields and a bid strategy that together reflect their delivery state.

The status field captures the advertiser’s intent for the campaign to serve. Set it to ENABLED to allow the campaign to serve or PAUSED to stop delivery without deleting the campaign.

The systemStatus field is system-computed. A value of RUNNING means the campaign is active and eligible to serve, and NOT_RUNNING means a condition is preventing delivery.

The displayStatus field is system-computed and represents a rolled-up label that combines status and systemStatus into a single delivery state. It’s the same value that campaign reporting returns.

The bidStrategy object is always present on a campaign and is required at creation. See the Choose a Bid Strategy section above for details.

The following table lists what each displayStatus value means:

When systemStatus is NOT_RUNNING, the system populates the systemStatusReasons array with one or more CampaignSystemStatusReason values explaining why. Reasons include scheduling, app or brand eligibility, budget exhaustion, payment issues, and ad group state, among others.

When a campaign is running but delivering at reduced capacity, the system populates the systemStatusLimitingReasons array with one or more CampaignSystemLimitedStatusReason values. These don’t stop delivery. They indicate conditions that constrain reach or impression volume.

To filter campaigns by status, see Query Campaigns.

Continue Building Campaign Delivery

Once a campaign exists, continue building out its delivery: create Ad Groups Endpoints to configure targeting and bid strategy, add Managing Keywords and Negative Keywords for App Store search campaigns, and create Ads Endpoints to serve within each ad group.

Topics

• Create a Campaign
• Query Campaigns
• Get a Campaign
• Update a Campaign
• Delete a Campaign
• Get Legacy App Limited Status Reason Details

See Also

Campaigns

• Campaigns Data Objects
• Campaigns Data Types