Apple Ads API vs AdServices Attribution

The Apple Ads API and AdServices answer different questions.

The Campaign Management API reports aggregate delivery and cost: impressions, taps, spend, installs, campaigns, ad groups, and keywords. AdServices attributes an eligible app install to Apple Ads and returns the campaign identifiers associated with that install.

Use the API to understand what the account spent. Use AdServices to understand where an install came from. Use both when you want revenue or ROAS by campaign or keyword.

Apple Ads API vs AdServices at a glance

Apple renamed Apple Search Ads to Apple Ads in 2025. Older documentation and integrations may still say Apple Search Ads API, but they refer to the same advertising platform.

What the Apple Ads API does

Apple's Campaign Management API is the advertiser-side system. It can create and manage campaigns, but most analytics teams use it to automate reporting.

Common reporting levels include:

• Campaign.
• Ad group.
• Keyword.
• Ad or creative.
• Search term.

A report can return delivery metrics such as impressions and taps, outcome metrics such as Apple-reported installs, and cost data such as local spend. The reporting request defines the date range, granularity, selector, pagination, filters, and available grouping dimensions.

The API is designed for server-to-server use. Your backend authenticates with OAuth, passes the organization context, and requests report pages. Apple's current access tokens expire after one hour, so a scheduled job should mint or refresh them automatically.

Use the Campaign Management API for questions like:

• How much did each keyword spend yesterday?
• Which ad group gained impressions but few taps?
• What was the campaign's cost per Apple-reported install?
• How should Apple Ads data be loaded into Power BI or a warehouse?

The Apple Ads export guide covers CSV downloads, API extraction, Power BI, PostgreSQL, and Redshift in detail.

What AdServices does

AdServices is an iOS attribution framework. The installed app asks AAAttribution for an attribution token and sends that token to a secure server. The server exchanges it with Apple for the attribution result.

The result can indicate whether Apple Ads received attribution credit and can include identifiers for the organization, campaign, ad group, and keyword, plus country or region and conversion context. The exact fields depend on Apple's eligibility and privacy rules. Search Match conversions may not have a keyword ID because no named keyword was selected by the advertiser.

The attribution token expires after 24 hours. Request it during the early app experience and send it promptly. Do not wait for the user to finish onboarding, start a trial, or return days later.

Use AdServices for questions like:

• Was this installation attributed to Apple Ads?
• Which campaign and ad group were associated with the install?
• Which keyword received credit when a keyword ID is available?
• Was the conversion a new download or a redownload?

AdServices does not return campaign spend, impressions, taps, or full entity names. It also does not know whether the installed user later started a trial, paid, renewed, or received a refund.

Why the two systems cannot replace each other

The Apple Ads API may report installs in aggregate, but those totals are not a list of individual app installations that you can attach to customer records.

AdServices can attach campaign IDs to one installation, but it cannot tell you how much the keyword spent across the reporting period.

This creates two complementary data sets:

Join the sets only after choosing a shared reporting grain. For example, group attributed installs and subscription revenue by acquisition date, campaign ID, ad group ID, keyword ID, and country, then compare those cohort totals with spend at the same level.

Do not copy a keyword's full daily spend onto every attributed install and then sum it. That multiplies the cost by the number of installs. Spend belongs in the aggregate fact table and is joined after both sides are grouped.

A complete Apple Ads revenue flow

Consider a user who taps an Apple ad, installs the app, starts a seven-day trial, converts, and renews one month later.

The systems participate in this order:

1. Apple Ads records delivery, taps, and spend for the campaign and keyword.
2. The app requests an AdServices attribution token after the first launch.
3. A server exchanges the token and stores the returned Apple entity IDs beside an internal install ID.
4. The app or subscription provider records the trial and later purchase events under the same internal identity.
5. The reporting job pulls Apple Ads spend at campaign or keyword level.
6. A cohort report groups revenue by acquisition source and divides it by the matching spend.

That last join is where campaign ROAS becomes possible:

Keyword cohort ROAS = revenue from installs attributed to the keyword divided by spend for the matching keyword cohort

The observation window matters. A keyword with a seven-day trial does not have final paid-conversion data after two days. Keep active, mature, and revenue-mature cohorts separate.

Recommended data model

You do not need one giant Apple table. Three narrower tables are easier to reason about.

Install attribution table

Store one record per internal installation:

• Internal install ID.
• Acquisition timestamp.
• Attributed source.
• Apple organization ID.
• Campaign ID.
• Ad group ID.
• Keyword ID or an explicit Search Match bucket.
• Country or region.
• Redownload or conversion context when available.

Store the parsed result rather than relying on the short-lived token as your permanent record.

Apple Ads reporting table

Store aggregate rows under a declared grain:

• Report date and time zone.
• Organization, campaign, ad group, and keyword IDs.
• Entity names captured at extraction time.
• Impressions, taps, installs, spend, and currency.
• Pull timestamp and source interval.

Product and subscription event table

Store trial, purchase, renewal, refund, and important product events against the internal install or customer identity. Preserve both event time and acquisition time so a later renewal remains credited to the original cohort.

RevenueCat and Superwall can provide the subscription lifecycle. The RevenueCat connection guide and Superwall connection guide show how that identity is carried through their webhooks.

Implementation order

1. Capture AdServices attribution first

Install attribution cannot be reconstructed reliably for users who arrived before the token flow existed. Ship the app-side collection, server exchange, and durable install identity before spending time on a polished dashboard.

Request the token early, retry transient delivery failures, and keep unmatched installs organic or unattributed. Do not force every install into a paid campaign just to make totals align.

2. Connect the Campaign Management API

Create server-side credentials, implement OAuth, select the organization, and pull a small daily report. Verify it against the Apple Ads dashboard with the same date range, time zone, currency, and filters.

Then add pagination, rolling refreshes, raw-payload storage, and keyword reports. Apple's reporting endpoints have date-span limits, so backfills should be split into restartable intervals.

3. Join downstream events

Choose one identity that can move from the app to your subscription source and back to the reporting layer. The subscription event should retain product, trial state, revenue, currency, and transaction context.

If the event cannot find the original installation, keep it as valid unattributed revenue instead of discarding it or guessing a campaign.

4. Define the report before optimizing

Write down:

• Whether revenue means customer price, proceeds, or another amount.
• Whether refunds and renewals are included.
• Which report time zone is authoritative.
• How currencies are normalized.
• How Search Match is labeled.
• Which cohort age is required before comparing ROAS.

These definitions usually explain more dashboard disagreement than the API call itself.

Privacy and consent notes

AdServices is built for Apple's advertising attribution flow. Calling attributionToken() does not display the App Tracking Transparency prompt and does not require access to IDFA.

That does not mean every user or conversion returns identical detail. Apple's response remains subject to platform eligibility, consent state, and privacy rules. Build reports that tolerate missing identifiers instead of turning them into false precision.

The Campaign Management API uses advertiser credentials and aggregate account reporting. Keep those credentials on a backend and restrict them to the access the reporting job needs.

Common implementation mistakes

Calling the Campaign Management API from the app

The app binary is not a safe place for advertiser private keys. API authentication and report extraction belong on a backend.

Waiting too long to send the attribution token

The AdServices token has a 24-hour lifetime. Collecting it only after a trial starts can miss users who delay or abandon onboarding.

Expecting spend from AdServices

AdServices returns attribution context, not account cost. Pull spend from the Campaign Management API.

Expecting a keyword on every attributed install

Search Match can produce a valid Apple Ads attribution without a named keyword ID. Give it a separate bucket.

Matching on names instead of IDs

Campaign and ad group names can change. Join on IDs, then use names for display.

Comparing data under different clocks

An AdServices acquisition timestamp, an Apple report date, and a subscription event timestamp may use different time zones. Normalize them before building daily cohorts.

Treating fresh free-trial cohorts as failed

A cohort still inside its trial window has not had a chance to produce paid revenue. The free-trial ROAS guide shows how to label maturity.

Which one do you need?

Use only the Apple Ads API if you need account reporting, pacing, or a warehouse export and aggregate Apple metrics are enough.

Use only AdServices if you need to identify Apple Ads-attributed installs but do not need cost or delivery metrics.

Use both when you need cost per attributed trial, cost per paid subscriber, keyword revenue, or ROAS. Add a subscription-event source when revenue occurs after the install.

If you prefer a maintained join instead of operating both pipelines, Postback's Apple Ads setup connects AdServices attribution, Apple reporting, and downstream events.

Sources

• Apple Campaign Management API - Current advertiser and reporting API
• Calling the Apple Ads API - Current authorization, organization context, and retry behavior
• Campaign-level reports - Aggregate campaign report endpoint
• Keyword-level reports - Aggregate keyword report endpoint and metrics
• Apple AdServices - Current install attribution framework
• AdServices attribution token - Token collection and 24-hour lifetime