Skip to main content

​
Overview

Connecting Apple Search Ads lets the dashboard:
  • Create, update, pause, resume, and delete App Store search campaigns plus their ad groups and targeting keywords.
  • Run ads that point at any Custom Product Page (CPP) managed in App Store Connect — set the cpp_id on a creative and the dashboard resolves the matching ASC product page automatically.
  • Pull spend, impressions, taps, conversions, and CPI metrics via the reports API.
  • Run native creative experiments by rotating multiple ad groups (each pinned to a different CPP) under one campaign.
The integration uses Apple Search Ads Campaign Management API v5 with a long-lived PEM private key signing short-lived JWT bearer tokens.

​
Why this setup is different

Apple Search Ads does not support OAuth. Instead, you generate an API certificate from the Apple Search Ads UI; the certificate gives you a PEM private key plus four identifiers. The integration signs every API request with a JWT minted from that key. This means the connect flow asks for 5 inputs rather than the usual single OAuth click:
InputWhat it isWhere to find it
Team IDThe Apple Developer team identifier. Used as the JWT iss claim.Apple Developer portal → Membership Details, or the ASA UI top-right account switcher.
Key IDThe id of the API certificate you generated.ASA UI → Settings → API → next to the certificate row.
Client IDThe ASA client identifier issued alongside the certificate.ASA UI → Settings → API → expand the certificate row.
Org IDThe numeric ASA organisation id. Sent as the X-AP-Context: orgId={id} header on every API call.ASA UI → URL bar (/o/{org_id}/...) or Settings → Account.
PEM private keyThe downloaded .pem file’s contents.ASA UI → when you generate the certificate, the PEM downloads once — store it in your secret manager.
Without all five, the dashboard cannot mint a JWT and the connect call fails.

​
Prerequisites

Before connecting, make sure you have:
  1. An Apple Search Ads account in good standing.
  2. A user with the API role in your ASA org (only API-role users can mint certificates).
  3. A generated API certificate with the PEM file safely stored. Apple shows the PEM exactly once — re-download is not possible. If the file is lost, generate a new certificate.

​
Generate an API certificate

Inside the Apple Search Ads console:
  1. Go to Settings → API.
  2. Click Create API Certificate.
  3. Pick the appropriate role for the certificate (typically Standard: campaign read + write).
  4. Confirm — Apple will now show the Key ID, Client ID, and offer the PEM file as a single download.
  5. Download the .pem file and copy it somewhere safe (the dashboard reads it once on connect, then encrypts it at rest).
  6. Note the Key ID and Client ID shown alongside the certificate.
  7. Find the Org ID in the URL of the ASA console (e.g. https://app.searchads.apple.com/cm/app/o/123456/campaigns — the org id is 123456).
  8. Find your Team ID in the Apple Developer portal.

​
Connect

  1. Open the Paid UA → Integrations page in the dashboard.
  2. Click Connect on the Apple Search Ads tile. (The tile opens an inline form rather than redirecting — Apple Search Ads is the only integration that doesn’t use OAuth.)
  3. Paste the five values from the previous step into the form. The PEM field accepts the full file contents including the -----BEGIN EC PRIVATE KEY----- and -----END EC PRIVATE KEY----- lines.
  4. (Optional) Add a comma-separated list of storefronts (2-letter App Store country codes, e.g. US, GB, DE, JP). You can skip this and pick storefronts per campaign later.
  5. Click Connect. The dashboard mints a JWT, exchanges it for a bearer token, and probes the /me endpoint to confirm the credentials work.
After a successful connect, the PEM is stored encrypted at rest. The short-lived bearer is automatically re-minted from the PEM whenever it expires.

​
What happens behind the scenes

OperationAPI endpoint
Create / update / delete campaignPOST/PUT/DELETE /campaigns[/id]
Create / update ad groupPOST/PUT /campaigns/{id}/adgroups[/id]
Bulk-upsert targeting keywordsPOST /campaigns/{id}/adgroups/{id}/targetingkeywords/bulk
Create / update ad (CPP reference)POST/PUT /campaigns/{id}/adgroups/{id}/ads[/id]
List campaigns + pull insightsPOST /reports/campaigns (range + selector body)
Per-ad-group split-test resultsPOST /reports/campaigns/{id}/adgroups
List accessible orgs (test connection)GET /me, GET /acls
Every API call carries:
  • Authorization: Bearer <access_token> — the short-lived bearer minted from the PEM.
  • X-AP-Context: orgId={your_org_id} — required by Apple Search Ads on every endpoint.
Write requests carry an Idempotency-Key HTTP header. Apple Search Ads doesn’t natively dedupe on this header, so the dashboard also runs a 24-hour Redis-backed dedupe cache to make replays safe even after a transient network failure.

​
Custom Product Page integration

The most powerful Apple Search Ads feature is the ability to route different ad groups to different Custom Product Pages. The dashboard ties this directly to the ASO module:
  1. Build and publish your CPPs from the ASO module. Each CPP gets a stable internal id and (after publish) an App Store Connect product-page id.
  2. When creating an ad in the Paid UA module, set creative.cpp_id to the internal CPP id. The dashboard will:
    • Look up the CPP row.
    • Forward the ASC-side product-page id as productPageId on the Apple Search Ads ad creation call.
    • Fall back to your app’s default App Store product page if the CPP hasn’t been published yet.
  3. Set up a creative experiment that varies cpp_id across variants — the dashboard creates one ad group per variant under a single campaign, each pinned to its own CPP. Apple’s optimisation engine handles traffic rotation; the dashboard collects per-variant metrics for winner declaration.

​
Rate limiting

Requests are throttled per (client_id, org_id) using a sliding window built on Redis. The default budget is 60 requests per minute per org. Apple Search Ads doesn’t publish hard rate limits, so this is a conservative ceiling. If the platform returns HTTP 429, the request is automatically retried with exponential backoff.

​
Reporting

Metrics are pulled hourly (or on demand) via the reports API. The default report covers spend (in the org’s currency), impressions, taps, installs, and CPI. Spend is converted to USD on ingestion using same-day FX rates; the native currency, FX rate, and local-currency spend are stored alongside the USD value.

​
Token rotation

Apple Search Ads has no refresh-token grant. The dashboard re-mints a fresh JWT from the long-lived PEM whenever the short-lived bearer expires (the bearer typically lasts 1 hour). The PEM itself is valid for 180 days from the moment Apple issues it; rotate the certificate from the ASA UI before that window closes and reconnect from the dashboard.

​
Disconnect

Click Disconnect on the integration tile. The PEM and bearer token are removed from the dashboard. To fully revoke access, also revoke the API certificate from the ASA UI.

​
Troubleshooting

  • “Apple Search Ads connect requires team_id, key_id, client_id, org_id, private_key_pem” — one or more inputs are missing. Re-check the connect form; all five are mandatory.
  • “Apple Search Ads token exchange failed: 400” — the PEM does not match the Key ID / Client ID / Team ID combination. Re-download the certificate from the ASA UI; the PEM and ids must come from the same certificate generation.
  • “Apple Search Ads /me returned 401” — the bearer expired or the PEM was rotated. Reconnect; the dashboard re-mints a JWT from the stored PEM on every refresh, so this should be self-healing unless the certificate itself was revoked.
  • “AppNotAvailableInStorefront: XX” — the campaign requested a storefront where your app is not yet available. Either remove that storefront or expand the app’s territory list in App Store Connect.
  • No CPPs available when creating an ad — the ASO module hasn’t published any CPPs yet, or the published CPPs have no ASC product-page id. Publish a CPP from the ASO module first, then return to the ad-creation flow.
  • “PEM file lost” — Apple does not allow re-downloads. Generate a new API certificate from the ASA UI, then reconnect with the new credentials.