> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Apple Ads in Qonversion

> Answers to common Apple Ads problems in Qonversion by symptom: the Apple Ads report is missing, Reconnect required, campaign names shown as numbers, empty ROAS D7, spend shown as a dash, numbers that differ from the Apple Ads console, Budget usage unavailable, refused or unknown campaign changes, and generic MCP errors. Each answer says what the symptom means and what to do.

This page lists common problems with Apple Ads in Qonversion — in the Apple Ads report of the Qonversion dashboard, in the Apple Ads connection under **Settings → Connections → Apple Ads**, and through the Qonversion MCP server and REST API v4 — and for each one says what it means and what to do. Three rules explain most symptoms: an em dash **—** in a report cell means no value, never \$0 or 0; only the Owner and Administrator roles can connect, reconnect or disconnect Apple Ads, and only in the dashboard; and campaign changes need both the **Manage Apple Ads campaigns** capability and an Apple Ads role that can edit campaigns.

## Why can't I see the Apple Ads report or its data?

### Why don't I see the Apple Ads report?

**What it means.** The Apple Ads report is available only to accounts with the Apple Ads feature enabled. Accounts with Apple Ads enabled see a top-level **Apple Ads** item in the sidebar that opens the Apple Ads report (`/apple-ads-report`); it is not an item inside the **Analytics** menu. Accounts without it keep the older **Apple Search Ads** page under **Analytics** (`/apple-search-ads`), and an Apple Ads report link opened from such an account is redirected to that legacy page.

**What to do.** If you see only **Analytics → Apple Search Ads** and no top-level **Apple Ads** item, contact support to get access to the Apple Ads report. See [Where do I find the Apple Ads report?](/docs/apple-ads-report#where-do-i-find-the-apple-ads-report)

### Why does the report say "Apple Ads data is not available for your role"?

**What it means.** In the dashboard, users with the Developer role cannot see report data. The Owner, Administrator, Manager, Analyst, Viewer and Observer roles can view the report.

**What to do.** Ask the Owner or Administrator of the account for a role change.

### Why does the report say "Couldn't load the Apple Ads report"?

**What it means.** The report failed to load.

**What to do.** Press **Try again**.

### Why does the API return 404 or MCP return "Resource not found"?

**What it means.** For accounts without Apple Ads access, the Apple Ads REST read endpoints and the connection endpoint return 404 `not_found`, indistinguishable from a nonexistent endpoint, and the MCP read tools fail with a "Resource not found" error. The change endpoint `POST /v4/analytics/apple-ads/entity/update` also answers HTTP 404 for such accounts, after its authorization check.

**What to do.** Apple Ads is available to accounts with Apple Ads enabled — contact support. See [Apple Ads in REST API v4](/reference/v4/apple-ads).

### Why does the setup checklist say "No users matched"?

**What it means.** The report's setup checklist has a step **Attribution is matching** that completes once at least one attributed user appears in the report. **No users matched** means Apple spend exists but no users matched it yet.

**What to do.** Check the SDK setup in your iOS app:

| Check | Rule |
| - | - |
| The call is made | Attribution collection is not automatic: the SDK sends the AdServices token only after the app calls `collectAppleSearchAdsAttribution()`, on every app launch where collection is wanted. |
| After initialization | Call it after Qonversion is initialized; before initialization the SDK logs "Attempt to get Qonversion instance before initialization". |
| AdServices is linked | Add `AdServices.framework` to the app target; otherwise the SDK logs "AdServices framework not found. Make sure that you import AdServices" and sends no token. |
| iOS version | The AdServices token is requested only on iOS 14.3 and later. |
| Platform | The native Android SDK has no Apple Ads attribution. |

Attribution is resolved asynchronously after the SDK has sent the token, so it appears on the user some time after the app's first launch rather than in the SDK call's response. If Apple has no attribution record for a token, the user stays unattributed unless a later token sent by the SDK resolves. Users carrying Apple's sample attribution payload (campaign ID and ad group ID both 1234567890) are excluded from the Apple Ads report. See [How do I collect Apple Ads attribution with the Qonversion SDK?](/docs/apple-ads-attribution)

## Why does my Apple Ads connection need attention?

### My connection says Reconnect required

**What it means.** The status **Reconnect required** has two forms on the **Connection status** card under **Settings → Connections → Apple Ads**:

| Apple authorization row | What it means |
| - | - |
| **Expired or revoked** | The Apple authorization expired, was revoked or disconnected, or Apple access for it can no longer be refreshed. Reporting access shows **Paused** and Campaign management **Unavailable**. |
| **Rejected by Apple** | Apple rejected the stored credential, or the connection was saved more than 48 hours ago and has never returned any Apple Ads account access or spend for the project. Reporting access shows **Unavailable** ("Spend may be missing until Apple access is restored."). |

After you disconnect an Apple authorization yourself, the status also shows **Reconnect required** (Apple authorization **Expired or revoked**) rather than **Not connected**. This is expected.

**What to do.** An Owner or Administrator selects **Reconnect with Apple** and signs in with Apple again; no key upload is needed. Members who are not Owner or Administrator see "Ask an account owner or administrator to reconnect it." on the report and no reconnect button. If the account's plan does not include Apple Ads settings, the report banner offers **Contact support** instead of a reconnect button. See [What does each connection status mean?](/docs/apple-search-ads#what-does-each-connection-status-mean)

### Why does the status say Verifying, Needs verification or Check out of date?

| Status | What it means | What to do |
| - | - | - |
| **Verifying** | Right after Apple authorization: the authorization is saved, but Qonversion is still reading the granted accounts and roles. | Wait; it becomes **Connected** only after Apple confirms access. |
| **Needs verification** | An Apple-authorization connection that is not being verified and that Apple has not rejected has no recent Apple confirmation (out-of-date check or no organizations returned). A connection saved more than 48 hours ago whose project has never received any Apple Ads account access or spend shows **Reconnect required** with **Rejected by Apple** instead. | An Owner or Administrator selects **Check again**. |
| Reporting access **Check out of date**, Campaign management **Refresh required** | Apple's permission check is too old. "A fresh Apple permission check is required before Qonversion can make changes." | An Owner or Administrator selects **Check again**. |
| **Connection unavailable** | The last attempt to refresh access for a legacy API-key connection failed. For an Apple-authorization connection the same failure is shown as **Reconnect required**. | Select **Check again** if it is offered, or **Migrate to Apple authorization**. |

### Why can't I select Connect with Apple?

| What you see | What it means | What to do |
| - | - | - |
| Buttons are disabled and the page says "Only an Owner or Admin can connect Apple Ads." | Only the Owner and Administrator roles can connect, reconnect, disconnect or run **Check again**. The **Manage Apple Ads campaigns** capability does not include changing the Apple Ads connection. | Ask an Owner or Administrator. |
| The button reads **Apple authorization unavailable** and the page shows "Apple Ads is available only on the Growth plan." | The account's plan does not include Apple Ads settings. An existing Apple authorization can still be disconnected. | Use **Upgrade plan**. |
| The button reads **Apple authorization unavailable** with "Apple authorization is not available for this project right now. Your existing Apple Ads connection is unchanged." | Apple authorization is switched off for the project. | Nothing changes for your existing connection. |
| You do not see **Settings → Apple Ads** in the Settings menu | The entry is shown to roles that can view project settings (Developer, Manager, Administrator, Owner); Viewer, Analyst and Observer do not see it. | Ask an Owner or Administrator. |

### What do the Connect with Apple error messages mean?

| Message | What it means | What to do |
| - | - | - |
| "The Apple authorization link expired. Start the connection again." | The Apple authorization link is single-use and expires; it was used after it expired. | Start **Connect with Apple** again. |
| "Apple Ads was not connected because access was not granted." | You canceled or did not grant access on Apple's page. Nothing is connected. | Start again and grant access. |
| "You do not have permission to connect Apple Ads for this project." | Your role is not Owner or Administrator. | Ask an Owner or Administrator. |
| "Apple Ads authorization is temporarily unavailable. Wait a moment and try again." | Apple authorization could not be completed at that moment. | Wait a moment and try again. |
| "Apple Ads authorization was not completed. You can safely try again." | The fallback message for an unrecognized failure reason. | Try again. |

### Why did Check again fail?

| Message | What to do |
| - | - |
| "Too many Apple Ads checks. Try again in a minute." | Wait a minute; the check was rate limited. |
| "Apple Ads is not available on your plan." | The plan does not include Apple Ads settings. |
| "This Apple Ads connection can't be checked automatically right now. Contact support if it persists." | Contact support if it persists. |
| "Could not check Apple Ads. Try again later." | Try again later. |

### Can an AI agent or a script connect or reconnect Apple Ads?

No. The API and MCP cannot start or complete the Apple sign-in. To connect or reconnect, a person must use the dashboard link returned in `dashboard_url` (**Settings → Apple Ads**). See [Can I connect Apple Ads from the API or MCP?](/docs/apple-search-ads#can-i-connect-apple-ads-from-the-api-or-mcp)

## Why do the report numbers look wrong?

### Why don't Qonversion numbers match the Apple Ads console?

**What it means.** Qonversion's report differs from the Apple Ads console by design:

| Reason | Details |
| - | - |
| Different population | Spend, impressions, taps and installs come from Apple, but subscriber metrics (trials, payers, revenue, ROAS) cover only installs that Qonversion attributes to Apple Ads with a known campaign, grouped by install date. |
| Revenue is cumulative | Subscriber revenue is cumulative to date, so it keeps growing after the selected period ends. |
| UTC days | Qonversion's report uses UTC days for every date: periods, cohort install dates, window boundaries and the "Updated" timestamps. |
| Currency | Apple spend in a local currency is converted to USD at each spend date's rate and then into the display currency at one period rate, so it can differ slightly from the local-currency spend shown in Apple Ads even when the display currency equals the account currency. |

**What to do.** Compare Apple metrics (Spend, Impressions, Taps, Installs) with the console for the same UTC days, and read subscriber metrics as Qonversion's attributed cohort. See [Why don't Qonversion's Apple Ads numbers match the Apple Ads console?](/docs/apple-ads-data-freshness#why-dont-qonversions-apple-ads-numbers-match-the-apple-ads-console)

### Why are campaign names shown as numbers?

**What it means.** When attribution is first recorded, the campaign name, ad set (ad group) name, ad name (when Apple sent a real ad ID) and keyword text are set to Apple's numeric IDs. Readable campaign, ad group and keyword names replace the numeric IDs only when the app's project has a connected Apple Ads account that can access the campaign's organization; otherwise names stay as numeric IDs. Analytics data recorded before a name was resolved can keep showing the numeric ID. The Ad dimension for Apple Ads is never renamed: it shows Apple's numeric ad ID, or "No ad" when Apple sent no ad ID (missing, or 0 or less — Apple uses `-1`) (older records: an identifier starting with "Q-"). A keyword shown as "Unknown" means Apple's response had no keyword ID; it is never resolved to a keyword name.

**What to do.** Connect Apple Ads under **Settings → Connections → Apple Ads** with an Apple account that can access the campaign's organization. See [Why do I see numeric IDs instead of campaign names?](/docs/apple-ads-attribution#why-do-i-see-numeric-ids-instead-of-campaign-names)

### Why is ROAS D7 empty?

| Cause | What you see | What to do |
| - | - | - |
| The column is not added | On the report list, the ROAS/CAC columns of the default windows D3, D7 and D30 start hidden. | Add **ROAS D7** from **Columns** (group **Cohort windows**). |
| No spend | ROAS Dn and CAC Dn are empty when spend is missing or 0. | Nothing to fix: there is no spend to divide by. |
| Mature reading, window not closed yet | While a selected window has no closed install day, its columns show **final values** with the UTC date its first final values are expected, and cells show a hatched provisional value or **—** when there is none. | Wait for that date, or switch **Cohort windows** to **Growing**. |
| Mature reading, no spend history | "Closed-window ROAS and CAC aren't available yet." — no daily spend history has been recorded for this project yet. | Wait; Owners and Administrators can press **Import spend history…**. |
| Mature reading, period before spend history | "This period is older than our spend history." | Owners and Administrators can press **Import spend history…**. |
| Missing exchange rate | Spend-based cells, including window ROAS/CAC, show **—** because spend is withheld. | See [Why is spend shown as —?](#why-is-spend-shown-as) |

In a CAC Dn cell, **No payers** is a separate state: the window has spend and attributed installs, but nobody has paid, so CAC cannot be calculated. With a non-Country filter active, ROAS Dn and CAC Dn are marked **Spend not filtered**; see [Why did ROAS Dn drop after I applied a filter?](#why-did-roas-dn-drop-after-i-applied-a-filter). See also [Growing and Mature cohort windows](/docs/apple-ads-report#growing-and-mature-cohort-windows).

### Why is spend shown as —?

**What it means.** An em dash **—** in a cell means no value — never \$0 or 0.

| Cause | Details |
| - | - |
| Missing exchange rate | If no exchange rate exists for an Apple Ads currency on or before a spend date, the spend of every row that includes such a day — and the Total — is withheld together with everything derived from it (CPA, CPT, CPM, ROAS, CPS, Cost per trial, window ROAS/CAC). Installs, taps, impressions and cohort metrics stay available. The report page shows no dedicated notice: the cells show **—** with the tooltip **No data attributed (≠ \$0)**. |
| App campaign data incomplete | While Apple's campaign data for the app is incomplete, the Total and Unallocated rows show no spend-based values; rows of confirmed campaigns keep their values. The page shows "Some spend and return metrics are unavailable." |

**What to do.** For a missing exchange rate, export the report: the CSV export lists the affected dates and currencies in a `# Spend FX unavailable:` line. For incomplete app campaign data, press **Request again**. See [Read spend in the report currency](/docs/apple-ads-report#read-spend-in-the-report-currency).

### Why do CPS or Cost per trial show — on a row with spend?

A dash in CPS or Cost per trial on a row that has spend means nobody in the cohort has started a trial or subscription (or no trials) yet; the cost is undefined, not \$0.

### Why does the Unallocated row have spend but no users or revenue?

The **Unallocated** row aggregates Apple spend and delivery for entities of the current level that have no Apple Ads–attributed installs in the period under the current filters. It carries only Apple metrics; Qonversion metrics, ROAS, CPS and Cost per trial are empty (**—**, not \$0).

### Why doesn't the Total row equal the sum of the rows?

The **Total** row is computed over the whole report for the selected period and attribute filters: it is not the sum of the rows on the current page, counts each user once, and its Apple metrics include the Unallocated spend. It is shown on the **Campaigns** level only, and it is hidden while a row filter (State & delivery, search, Spend ≥ or a metric filter) is active. See [What do the Total and Unallocated rows mean?](/docs/apple-ads-report#what-do-the-total-and-unallocated-rows-mean)

### Why did ROAS Dn drop after I applied a filter?

Media source, Ad, device and customer filters narrow only the Qonversion cohort; Apple spend is not filtered by them, because Apple does not split spend by those dimensions. The filter narrows revenue and payers but not the spend they are divided by, so ROAS Dn reads too low and CAC Dn too high, and the columns are marked **Spend not filtered**. Read these two on the unfiltered report.

### Why do revenue and ROAS keep changing for a past period?

**Revenue** is the cohort's revenue cumulative to date: only the install date is limited by the selected period, so the number keeps changing after the period ends — it grows as the cohort keeps paying and can go down when refunds arrive. Cohort windows default to the **Growing** reading, whose values keep growing. Even a closed window can change: a refund that comes in after a window closed still lowers that window's revenue and ROAS. For values over closed install dates only, switch **Cohort windows** to **Mature**.

### What does "Spend is undercounted" mean?

"Spend is undercounted — Apple didn't return data for N of M campaigns." means Apple didn't answer for part of the account in this request. ROAS looks better and cost metrics look cheaper than they really are, while revenue and cohort counts are unaffected. Press **Request again**, which re-runs the request.

### Why does the Status column show — for some rows?

"N rows don't show whether they're running." means Apple didn't return those rows' state. They show a dash in the Status column, and filtering by Status or Delivery hides them even if they're active. Press **Request again**.

### What do the other messages above the report table mean?

| Message | What to do |
| - | - |
| "N days of spend history are missing from this period." | There is no button: waiting or retrying won't fill those days. Closed-window ROAS and CAC over those dates stay provisional and read higher than reality. |
| "Closed-window ROAS and CAC are unavailable right now." | Press **Try again**; everything else on the page is unaffected. |
| "The CSV didn't download." | Press **Retry**; nothing on screen changed. |

All messages are listed in [What do the data messages above the Apple Ads report table mean?](/docs/apple-ads-data-freshness#what-do-the-data-messages-above-the-apple-ads-report-table-mean)

### Why don't I see the "Updated …" label or Update now?

The **Updated …** indicator and its **Update now** button are shown only on some projects. If your report doesn't show them, nothing is wrong with your connection: the Apple Ads numbers on that report are requested from Apple for the report you open, so there is nothing to refresh.

Where the button is shown, anyone who can view the Apple Ads section can press **Update now**; it does not need an owner or administrator role. If an update doesn't land, a **Couldn't update the data** notification appears and the button changes to **Retry**. **Update now** is dashboard-only: the REST API and the MCP server can't trigger it.

## Why does Budget usage show no reading?

### Why does Budget usage say Temporarily unavailable?

**What it means.** Budget usage shows **Temporarily unavailable** for a campaign when a data source failed, when an exchange rate needed to convert its spend or budget to USD is missing, or, on app-scoped projects, for campaigns not confirmed as belonging to the app.

**What to do.** Click the reading to open **Why there is no reading**, which lists every applicable reason and marks the main one **Primary**. See [Why does a campaign show a dash instead of a budget usage percent?](/docs/apple-ads-budget-usage#why-does-a-campaign-show-a-dash-instead-of-a-budget-usage-percent)

### Why does Budget usage show a dash?

When a reading can't be computed, the cell shows a dash, never 0%. Common reasons:

| Reason | What to do |
| - | - |
| **Not available with filters** | A Country filter turns budget usage off for every campaign. Remove the Country filter. |
| **Not enough history** | The campaign started after the first day of the 7-day window. It clears once the campaign has 7 full days of history. |
| Ad group or keyword row | Budget usage is available only for campaigns ("Budget usage is available at the campaign level"). |
| Totals row | "not additive across the report" |

If you don't see the column at all: it is not shown by default; add it from **Columns** on the **Campaigns** level.

### Budget usage is above 100%. Did Apple overspend my budget?

Not necessarily. Spend is compared with the campaign's current daily budget, not with the budget that applied when the money was spent. A reading above 100% does not by itself mean a limit was broken, because Apple's daily budget is an average target over a month. See [What does the Budget usage column show for Apple Ads campaigns?](/docs/apple-ads-budget-usage)

## Why can't I import spend history?

### Why can't I fill in spend for recent days?

Rows from the last 90 days (UTC) are always skipped as "still being recorded from the API". Imported days must also be earlier than the date your recorded spend history starts, so an import can't fill gaps inside recorded history; it can only extend history backwards. Recorded data always wins: an import never overwrites or updates an existing row.

### Why was my spend import file rejected?

| Problem | Rule |
| - | - |
| Ad Group, Keyword, Search Term, Match Type, Ad or Creative Set columns | The import accepts campaign-level reports only. |
| "No header row found…" | The file needs a header row within its first 25 rows with a Day (or Date) column, a Spend column and a Campaign column. |
| "Required column missing: Campaign…" | Add the campaign name or its Campaign ID. |
| File too large | Upload .xlsx or .csv up to 8 MB and up to 150,000 rows; split the report into shorter date ranges. |
| Rows skipped as unreadable for currency | Imported spend is never currency-converted; a row whose currency differs from the Apple Ads organization's currency is skipped. |

### Why don't I see Spend history… or Import spend history…?

Only the owner and administrator roles can import spend history; other roles don't see the import entry points. See [How do I import older Apple Ads spend history?](/docs/apple-ads-data-freshness#how-do-i-import-older-apple-ads-spend-history)

## Why can't I change a campaign, bid or budget?

### Why can't I change a bid?

| Cause | What you see | What to do |
| - | - | - |
| Not a keyword | Bids can be changed only for keywords. Campaigns have no bid, and the ad group default bid cannot be changed from Qonversion. | Change keyword bids on the **Keywords** level. |
| No capability | Members without **Manage Apple Ads campaigns** see Status, Bid and Daily budget read-only: no switches, edit buttons, row checkboxes or bulk bar. | An owner or administrator grants the capability under **Members** → edit member → **Capabilities**. |
| No current value | The control is disabled: "Apple’s current bid for this row is not in this report yet, and a bid cannot be changed without a verified current value." | A change is only possible when the report shows Apple's current value for that row. |
| Read-only Apple Ads role | "Reporting is connected. Campaign management isn't enabled" | Change the role in Apple Ads to one that can edit campaigns, such as Admin or Campaign Manager, then reconnect with Apple. |
| Connection problem | Changes cannot be made while the connection is missing, rejected by Apple, expired or revoked, or still being verified; a control opens a dialog that says "No changes were made." | Fix the connection with the action in the report banner. |
| Permissions not confirmed | **Apple Ads permissions need to be refreshed**: Qonversion has not been able to confirm the connection's Apple permissions for more than 48 hours. | Use **Refresh connection**. |
| Demo account | "Not available in the demo account. This project is a read-only demo, so the change was never sent to Apple — nothing changed." | Use your own project. |
| Campaign management temporarily unavailable | "Campaign management is temporarily unavailable." Every change is refused with HTTP 503. | Nothing is changed in Apple Ads. |

### Why can't I save the new amount?

| Message or state | Rule |
| - | - |
| "A bid must be greater than zero. To stop spending, pause instead." | Zero is not allowed. |
| "Use a dot for decimals — Apple takes 1.20, not 1,20." | Use a dot as the decimal separator and at most two decimal places. |
| **Save changes** stays disabled, or "That is already the current bid." | Saving the same amount as the current one is not possible. |
| "We will not send more than … — one change cannot raise this to more than 3× the current value." | One change cannot raise a bid or daily budget to more than 3× the current value. Raise in steps. |
| A currency error | Bids and daily budgets are entered in the Apple Ads account (org) currency, not converted to USD. |

### Why did my change fail?

| What the row shows | What it means | What to do |
| - | - | - |
| **! Pause failed** (or **Resume failed**, **Set bid failed**, **Set daily budget failed**) | Apple or Qonversion refused the change. Clicking it shows the reason and Apple's error code when Apple gave one; usually "Nothing changed on Apple’s side." | Use **Try again** when it is offered, or **Dismiss**. |
| HTTP 409 `value_changed` ("The status changed since you loaded the report…") | The entity was changed through Qonversion shortly before, and the value you saw is no longer the one Apple confirmed. No retry is offered. | Reload the report and decide against the current value. |
| HTTP 409 `in_progress` | The same change is already being applied. | Wait for it to finish. |
| HTTP 429 | A per-project rate limit was reached. | See [Why did I hit a daily limit?](#why-did-i-hit-a-daily-limit-even-though-i-lowered-bids) |

See [What do I see after I make a change?](/docs/apple-ads-manage-campaigns#what-do-i-see-after-i-make-a-change)

### What does "? Outcome unknown" mean?

**What it means.** No answer came back from Apple: the change may or may not have been applied.

**What to do.** Do not press retry repeatedly. Reload the report and check the current value before retrying. The **Check and retry** button asks about the same attempt instead of sending a second change, so it cannot double-apply. Changes whose outcome is unknown count toward the rate limits.

### Why did I hit a daily limit even though I lowered bids?

If Qonversion has never successfully changed that keyword or campaign before, the first bid or daily-budget change on it is counted toward the daily increase limit even when it lowers the value. The per-project limits are:

| Limit | Value |
| - | - |
| Changes per rolling minute | 10 |
| Changes per rolling hour | 60 |
| Resumes (enables) per rolling 24 hours | 20 |
| Bid increases per rolling 24 hours | 20 |
| Daily-budget increases per rolling 24 hours | 10 |

Pausing is never subject to the daily limits — only to the 10-per-minute and 60-per-hour limits. Limits are shared by every member and by changes made through the MCP server. A refusal's `Retry-After` header equals the full window length (60, 3600 or 86400 seconds) — an upper bound, not the exact moment the limit frees up. See [What limits apply to campaign changes?](/docs/apple-ads-manage-campaigns#what-limits-apply-to-campaign-changes)

### The connection says Connected, but every change is refused

**What it means.** The connection state describes the authorization only, not permission to change campaigns: a connected integration can still be reporting-only. A read-only Apple Ads role still powers full reporting; only campaign management is unavailable, shown as **Read-only** in the **Campaign management** row. Through the API or MCP, `campaign_management.state` is `read_only` and `next_action` is `grant_campaign_role_in_apple_ads`.

**What to do.** Give the Apple Ads user a role that can edit campaigns (Admin, Account Admin, API Account Manager, API Campaign Manager, Campaign Group Manager or Campaign Manager) in Apple Ads, then reconnect with Apple. If `campaign_management.state` is `unknown`, that is not a refusal; try later.

### Why did my change overwrite an edit made in the Apple Ads console?

Changes made directly in the Apple Ads console are not detected before a change is sent: Qonversion checks the value you saw only against changes it confirmed itself shortly before, so a change from Qonversion overwrites a newer console edit.

### Why does a campaign show "not delivering" right after I resumed it?

Right after resuming, Apple often still reports the entity as not running, so **not delivering** can appear briefly after a successful resume.

## Why did an MCP or REST API call fail?

### MCP returned a generic error after a change

**What it means.** Through MCP, any server-side (5xx) failure — including a change whose outcome is unknown — surfaces as the generic error "The Qonversion API returned an error. Please try again." It must not be taken as proof that a change failed. A 502 or 504 from the change endpoint means the change may or may not have reached Apple, and it is never retried automatically.

**What to do.**

1. Do not resend the change with a new `idempotency_key`. Retry only with the same `idempotency_key`, which cannot apply the change twice.
2. Check the entity's current value before making any new change.
3. Call `get_apple_ads_connection_status`. If it shows `campaign_management.state` `unknown` with `reason_code` `permission_data_stale`, changes are refused with HTTP 503 and nothing is sent; a person reopens Apple Ads settings in the dashboard to refresh, then you retry.

See [What should I do after the generic error on a change?](/docs/mcp-apple-ads#what-should-i-do-after-the-generic-error-on-a-change)

### Why does the REST change endpoint return 403 control\_forbidden?

Campaign changes cannot be made over the plain REST API with a project Secret Key: `POST /v4/analytics/apple-ads/entity/update` without Qonversion MCP authorization (an acting dashboard user plus the `apple_ads:write` scope) returns 403 `control_forbidden`. Make campaign changes through the Qonversion MCP server or in the dashboard.

### Why does an MCP change tool return an insufficient-scope error?

The three campaign-change tools require the OAuth scope `apple_ads:write`; without it the tool returns an insufficient-scope error. An OAuth token only carries `apple_ads:write` when the signed-in dashboard user holds the **Manage Apple Ads campaigns** permission. Owners and administrators have it through their role; any other member needs an owner or administrator to grant it.

### Why did set\_apple\_ads\_bid return 409 value\_changed?

The `before_bid` (or `before_status`, `before_daily_budget`) value disagrees with a value Qonversion recently saw Apple confirm for that entity, and the response states the current confirmed value. Decide again from that value instead of resending the same request.

### Why does the report or series return 400 unsupported\_parameter?

On the Apple Ads report and series endpoints an unknown or unsupported query parameter is refused with 400 `invalid_request` and `error.details[].reason` `unsupported_parameter`, instead of being silently ignored. For example, the public series is daily only and does not accept a `unit` parameter. See [What errors and rate limits do the Apple Ads endpoints return?](/reference/v4/apple-ads#what-errors-and-rate-limits-do-the-apple-ads-endpoints-return)

## What is not supported?

* Connecting, reconnecting or disconnecting Apple Ads through the REST API or MCP.
* Filling spend history for the last 90 days (UTC), or for gaps inside recorded history, with an import.
* Detecting edits made directly in the Apple Ads console before a change from Qonversion is sent.
* Changing ad-group bids, or changing campaigns over the plain REST API with a project Secret Key.
* Budget usage on ad group or keyword rows, or with a Country filter.
* Triggering **Update now** from the REST API or the MCP server.

## Related pages

* [Apple Ads in Qonversion: what it does and how to set it up](/docs/apple-ads) — what the integration does, who can use it, and the three setup steps.
* [How do I connect Apple Ads to Qonversion?](/docs/apple-search-ads) — every connection status, Check again, reconnecting and the legacy API key.
* [How do I read the Apple Ads report in Qonversion?](/docs/apple-ads-report) — cohort windows, revenue basis, Total and Unallocated, filters and currency.
* [How do I pause campaigns and change bids and budgets for Apple Ads in Qonversion?](/docs/apple-ads-manage-campaigns) — permissions, amounts, rate limits and change outcomes.
* [How do I use Apple Ads through the Qonversion MCP server?](/docs/mcp-apple-ads) — MCP tools, scopes, confirmation and error handling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.