What Platform API 1.0 unlocks for Apple Ads performance

The upgrade is a larger advertising surface, not just a new URL.

Classic Campaign Management API v5 remains useful for existing App Store campaign workflows. Platform API 1.0 adds an ad-account model, campaign groups, promoted objects beyond apps, broader creative support, new insights, and Apple Maps campaign capabilities. For an advertiser, the practical shift is from maintaining app campaigns to finding demand, choosing where to compete, and operating more placements through one API family.

• Use adAccountId as the operating scope for v1 workflows
• Organize and query campaign groups as integrations scale
• Use promoted objects for app and brand-oriented campaign models
• Migrate before Apple retires Campaign Management API v5 on January 26, 2027

Discover new demand with keyword, phrase, and category suggestions.

Platform API 1.0 exposes separate suggestion queries for keywords, phrases, and categories. Keyword suggestions can start from an app or seed terms; phrase and category discovery can broaden the planning frame before a campaign is built. These are candidate-discovery surfaces—not keyword recommendations and not a promise of profitable traffic.

• /suggestions/keywords/query for relevant search coverage
• /suggestions/phrases/query and /suggestions/categories/query for wider opportunity discovery
• Use category SEARCH queries to inspect specific category sets
• Filter candidates for product relevance, localization, and downstream ROAS before adding them

Measure keyword heat by market, genre, and time.

Search-term popularity insights expose demand by country or region and App Store genre. Completed weekly and monthly reports can return a term’s rank in its genre, genre-relative popularity, a cross-genre 1–100 score, and the familiar 1–5 score. Apple only returns eligible terms, so this is a market-demand signal rather than a complete keyword universe or the performance of a keyword already in your campaign.

• /insights/apps/search-term-popularity/query provides the demand signal
• Spot rising terms before they become obvious in campaign search-term reports
• Compare the same product concept across storefronts before localization
• Separate search demand from the taps, installs, and revenue a campaign actually produced

Know whether to bid harder—or stop chasing limited demand.

The impression-share insight can report FIRST_SLOT or ALL_SLOTS visibility by search term and market. Platform API 1.0 adds single-digit precision from 1% through 90%, with a 91%–100% range at the top. Combine share with popularity and observed ROAS: a popular term with low share may have auction headroom, while a low-popularity term may simply have little demand to capture.

• High popularity + low share: investigate bids, budget, and relevance
• High popularity + high share + weak ROAS: do not scale on visibility alone
• Low popularity + low share: validate demand before committing more spend
• Compare first-slot share with total impression share instead of treating them as the same metric

Use target CPA and budget recommendations as scaling guardrails.

The GA recommendation family covers target CPA and daily budget. It can surface campaigns where Apple estimates that a different acquisition target or more budget may produce incremental delivery, and it includes separate apply and dismiss operations. There is no GA /recommendations/keywords/query endpoint: keyword, phrase, and category discovery belongs to Suggestions.

• /recommendations/target-cpas/query informs the acquisition-cost constraint
• /recommendations/daily-budgets/query identifies possible underfunding
• Estimated installs, spend, and CPA make the tradeoff reviewable
• Compare every recommendation with margin, payback window, cohort maturity, and current ROAS before applying it

Run advertising workflows for Apple Maps.

Platform API 1.0 adds campaign-management capabilities for ads on Apple Maps. Its brand, location-group, location, eligibility, and rejection-reason surfaces let an integration discover eligible business inventory and manage promoted brand objects. Separate brand campaign, ad group, ad, keyword, and search-term reports make Maps activity measurable instead of leaving it outside the automation stack.

• Query business brands and eligible locations before planning a Maps campaign
• Create and maintain static or dynamic location groups
• Inspect supply-placement and country eligibility or rejection reasons
• Measure brand campaigns through dedicated reporting endpoints

Manage creatives and operations at larger scale.

The new API includes asset, creative, ad, product-page, budget-order, and bulk-operation models designed to evolve with new ad formats. Bulk requests use correlation IDs and per-item data so an integration can reconcile partial success safely. For an advertiser, that reduces manual object stitching and makes larger campaign launches easier to audit and retry.

• Build creative and ad workflows that are not limited to one legacy format
• Use promoted objects and product-page relationships explicitly
• Track each item in bulk keyword and negative-keyword operations
• Keep budget-order and campaign-group administration in the same integration boundary

Use richer reporting and change history to protect performance.

Platform API 1.0 broadens reporting across app and brand campaigns and adds total impression-share reporting. Change-history queries can show what changed, when it changed, and who or what made the change; detail calls expose the field-level values behind an event. When a KPI moves, this shortens the path from the symptom to a campaign edit that may explain it.

• Report by campaign, ad group, ad, keyword, and search term
• Use total impression share alongside first-slot visibility
• Correlate account changes with performance movement without claiming causation

Use Apple-maintained client libraries as the contract source.

Apple publishes open-source Node, Python, Java, and Swift client libraries generated from the Platform API contract. Following those models, routes, and enums reduces guesswork when Apple adds or changes fields. Lily’s TypeScript agent uses the official Node SDK for v1 calls; the Go CLI keeps its lightweight HTTP provider while using that SDK’s generated contract as the source for request models and regression tests.

Turn Apple’s opportunity signals into revenue decisions.

Apple can describe demand, visibility, delivery, installs, spend, and CPA, but it does not know your subscription renewals, refunds, gross margin, or customer lifetime value. The highest-value workflow joins Platform API 1.0 signals to RevenueCat or AppsFlyer outcomes, then scales only when the acquisition cost is supported by observed revenue and ROAS.

Query the supported opportunity surfaces with Lily CLI.

Lily CLI supports Platform API 1.0 campaign workflows, authenticated reporting, keyword, phrase, category, and target CPA suggestions, target CPA and daily-budget recommendations, search-term popularity, impression share, and change history alongside classic v5. Read-only opportunity queries do not apply or dismiss recommendations.

• Use --provider platform for every Platform API 1.0 opportunity query
• Use suggestions keywords, suggestions phrases, or suggestions categories for discovery
• Use recommendations target-cpa or recommendations daily-budget for Apple recommendations
• Opportunity commands return AI-friendly JSON without changing campaign state