Advertising Your App on the App Store

Overview

You can promote your app on the App Store in four placements, as detailed in the table below: search results, the Search tab, the Today tab, and Product Pages. Every App Store campaign uses promotedObjectType: APPSTORE_APP.

Before you begin:

• Every API call requires a valid Bearer token. Complete the OAuth setup in Implementing OAuth for the Apple Ads Platform API before proceeding.

• Your ad account must have productFeatures: ["APPSTORE_APP_MANUAL"] and a CONTENT_PROVIDER delegation with the CPID as resourceId to create App Store campaigns. Both must be in place before campaigns can go live. For full delegation requirements, see ProductFeatures.

• For ad-account-scoped operations, also include the X-AP-Context header. For the full header reference and a request example, see Calling the Apple Ads Platform API.

• When automating campaign, creative, or keyword operations at scale, watch the rate-limit headers described in Applying Rate Limits and back off before hitting a 429.

• See Calling the Apple Ads Platform API for details on the request structure and common query patterns.

Confirm Your Organization and Ad Account

Start by confirming which organization and ad account you’re working under. Get User ACL returns the ad accounts and roles available to your token, as shown here:

GET https://api.ads.apple.com/v1/acls

For each ad account, Get Ad Account by ID, shown below, returns full ad account details including currency, time zone, and payment model, all of which you need when creating campaigns and interpreting reports.

GET https://api.ads.apple.com/v1/ad-accounts/{adAccountId}

Confirm the productFeatures and CONTENT_PROVIDER delegation mentioned above are present on this ad account. To update an ad account’s delegations, use Update Ad Accounts. The delegations field uses full-replacement semantics: a partial array removes unlisted entries, so always send the complete desired state.

Choose Your App

To search the App Store catalog for your app and retrieve its Adam ID, use Search for Apps. The Adam ID is the promotedObjectId you set on every App Store campaign.

GET https://api.ads.apple.com/v1/search/apps

To retrieve full metadata (display name, category, supported device classes, and availableStorefronts), use Get App Details by Adam ID, like this:

GET https://api.ads.apple.com/v1/apps/{adamId}

Check availableStorefronts to confirm which App Store countries or regions you can target before setting campaign targets. See Search Apps Endpoints for more information.

Verify Your App Is Eligible to Advertise

To confirm your app’s advertising eligibility status before you build a campaign, use Check App Eligibility. Pass your app’s Adam ID to check which placements and App Store countries or regions are available, as shown here:

POST /v1/eligibilities/apps/query

{
  "filters": [
    {
      "field": "adamId",
      "operator": "EQUALS",
      "value": 123456789
    }
  ]
}

For eligibility states and per-placement details, see App Eligibility Endpoints.

Choose Placements and App Store Countries or Regions

Before creating the campaign, select where you want your ads to run on the App Store (Today tab, Search tab, search results, or product pages) and choose one or more App Store countries or regions for the campaign to run.

There are three campaign-level targeting dimensions, described in the table below:

App Store campaigns support the four placements described below:

Set countryOrRegion.include using the availableStorefronts list you retrieved earlier when choosing your app, as shown below. Only include App Store countries or regions where your app is available for download or purchase.

"targeting":
{
  "supplySource": {
    "include": [
      "APPSTORE"
    ]
  },
  "supplyPlacement": {
    "include": [
      "APPSTORE_SEARCH_RESULTS"
    ]
  },
  "countryOrRegion": {
    "include": [
      "US"
    ]
  }
}

Create a Campaign

This example creates an APPSTORE_SEARCH_RESULTS placement campaign:

POST /v1/campaigns

{
  "name": "AwayFinder - Brand Keywords - US",
  "adAccountId": 123456789,
  "billingEvent": "TAPS",
  "promotedObjectType": "APPSTORE_APP",
  "promotedObjectId": "123456789",
  "dailyBudget": {
    "value": { "amount": "100.00", "currency": "USD" }
  },
  "targeting": {
    "countryOrRegion": { "include": ["US"] },
    "supplyPlacement": { "include": ["APPSTORE_SEARCH_RESULTS"] }
  },
  "bidStrategy": {
    "bidStrategyType": "MANUAL_CPT",
    "bidStrategyGoal": "TAP"
  },
  "status": "ENABLED"
}

Create an Ad Group

Ad groups sit under a campaign and control targeting, scheduling, and bidding. Create one with Create an Ad Group, supplying the campaignId from the previous step. App Store ad groups support audience targeting (device class, age, gender, app category, and app downloader), geo targeting (country, admin area, and locality), daypart, and keyword targeting. For a full description, see Ad Groups Endpoints.

POST /v1/adgroups

{
  "campaignId": 542317095,
  "name": "AwayFinder - Brand Keywords - US",
  "pricingModel": "CPT",
  "bidStrategy": {
    "bidStrategyType": "MANUAL_CPT",
    "bidStrategyGoal": "TAP",
    "bid": { "amount": "1.00", "currency": "USD" }
  },
  "status": "ENABLED",
  "startTime": "2026-01-01T00:00:00.000",
  "endTime": "2026-03-31T23:59:59.999"
}

Add Keywords

To add keywords to an ad group for Search results placement, use Create a Keyword or Bulk Create Keywords. matchType is BROAD or EXACT, as shown in the example below. An optional per-keyword bid overrides the ad group default. For the full match type reference, see KeywordMatchType.

POST /v1/keywords/bulk-create

{
  "items": [
    {
      "correlationId": 1,
      "data": {
        "adGroupId": 542370539,
        "text": "travel app",
        "matchType": "BROAD",
        "bid": {
          "amount": "1.25",
          "currency": "USD"
        },
        "status": "ENABLED"
      }
    },
    {
      "correlationId": 2,
      "data": {
        "adGroupId": 542370539,
        "text": "flight tracker",
        "matchType": "EXACT",
        "bid": {
          "amount": "1.50",
          "currency": "USD"
        },
        "status": "ENABLED"
      }
    }
  ]
}

If you’re not sure which keywords to add, use Query Keyword Suggestions to discover terms related to your app’s category and Query Phrase Suggestions to explore broader phrase ideas.

Exclude Irrelevant Traffic with Negative Keywords

Negative keywords prevent your ads from showing for unrelated searches. Apply them at two levels:

• Campaign-level negatives apply across all ad groups. Set campaignId, omit adGroupId.

• Ad group-level negatives apply to a single ad group. Set adGroupId, omit campaignId.

You can add negative keywords with Create a Negative Keyword, as shown below. For large exclusion lists, you can use bulk creation via Bulk Create Negative Keywords. See Managing Keywords and Negative Keywords for scoping rules and match type behavior.

POST /v1/negative-keywords

{
  "adGroupId": 542370539,
  "text": "free",
  "matchType": "BROAD",
  "status": "ENABLED"
}

Create a Creative and an Ad

First, create the creative with Create an Ad Creative using creativeType: DEFAULT_PRODUCT_PAGE, as the example below demonstrates. You also need destination.parameters.adamId, which should match the promotedObjectId you set when creating the campaign.

POST /v1/creatives

{
  "name": "AwayFinder - Default Product Page",
  "creativeType": "DEFAULT_PRODUCT_PAGE",
  "creativeSpec": {},
  "destination": {
    "destinationType": "APP_STORE_PRODUCT_PAGE",
    "parameters": {
      "adamId": "123456789"
    }
  }
}

The response’s result.id is the creativeId you reference below. Create the ad with Create an Ad, and link it to the ad group and creative.

POST /v1/ads

{
  "adGroupId": 542370539,
  "creativeId": 666777888,
  "name": "Default Search Ad",
  "status": "ENABLED"
}

To use a custom product page instead of the default, first retrieve available pages with Query Product Pages, then set creativeType: CUSTOM_PRODUCT_PAGE and pass the chosen productPageId alongside adamId in the creative’s destination.parameters. For more information on fetching page IDs and locale details, see Product Pages Endpoints. For the full creative workflow, see Creatives Endpoints.

Pull Campaign Performance Reports

After your campaign is live, you can retrieve performance data with Campaigns Report. All report calls follow the same POST /query structure with a required timeRange as shown below:

POST /v1/reports/apps/campaigns/query

{
  "timeRange": {
    "start": "2026-01-01",
    "end": "2026-01-31",
    "timeZone": "UTC",
    "granularity": "DAILY"
  },
  "filters": [
    { "field": "campaignId", "operator": "EQUALS", "value": 542317095 }
  ]
}

Search term reports show the actual queries that triggered your ads, so you can use them to discover new keyword opportunities and build out your Managing Keywords and Negative Keywords list. To understand which keywords and creatives are driving results, drill deeper with Ad Groups Report, Keywords Report, and Search Terms Report.

Optimize Your Campaigns

With a campaign running and data flowing, you’re ready to optimize in the following ways:

• To act on automated suggestions, use Query Daily Budget Recommendations.

• To understand how often your ads win auctions versus competitors, use Impression Share Query.

• To identify trending search terms in your category, use Search Term Popularity Query.

• Scale keyword changes with Bulk Update Keywords. To remove a keyword, use the single-item Delete a Keyword endpoint. When looping over many campaigns or ad groups, watch the rate-limit headers described in Applying Rate Limits and back off before hitting a 429.

See Also

Essentials

• Implementing OAuth for the Apple Ads Platform API
• Calling the Apple Ads Platform API
• Using Client Libraries
• Applying Rate Limits
• Advertising Your Business on Apple Maps