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

# Apple Search Ads ROAS Workflow

> Check integration readiness, get optimization recommendations, and validate App Store ratings before scaling paid spend by country

Apple Search Ads shows what you spend and how users respond at install time. RevenueCat shows what those users earn afterward. Appeeky connects both sides so you can see which keywords and campaigns are actually profitable — and whether your App Store presence is strong enough to scale spend in each country.

This workflow is available through REST, the [web dashboard](https://appeeky.com), and [MCP tools](/docs/apple-search-ads-mcp).

***

## What This Covers

| Capability                   | Endpoint                                             | Best for                                                                                        |
| ---------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Integration readiness        | `GET /v1/connect/apple-ads/playbook/status`          | Confirm RevenueCat, Apple Search Ads, and attribution are wired up before trusting ROAS numbers |
| Optimization recommendations | `GET /v1/connect/apple-ads/playbook/recommendations` | Scale winners, cut wasteful spend, and review country-level rating risks in one call            |
| Review country gate          | `GET /v1/connect/apple-ads/review-country-gate`      | Compare active campaign countries against App Store ratings                                     |
| Profitability by country     | `GET /v1/connect/apple-ads/profitability?country=US` | ROAS filtered to campaigns targeting a specific country                                         |

For the core spend × revenue join and insight buckets, see [Apple Search Ads Profitability](/docs/apple-search-ads-profitability).

For per-customer attribution dimensions from RevenueCat, see [RevenueCat Attribution](/docs/revenuecat-attribution).

***

## Prerequisites

1. An Appeeky API key.
2. [Apple Search Ads connected](/docs/apple-search-ads-credentials) in Appeeky (or per-request ASA headers).
3. A RevenueCat secret API key (`X-RC-Key`), saved in Appeeky Settings or passed per request.
4. **Apple AdServices** enabled in RevenueCat under **Integrations**. This is what populates Apple Search Ads attribution in RevenueCat charts and customer attributes.

<Tip>
  Without Apple AdServices in RevenueCat, Appeeky can still return Apple Search Ads spend and installs, but revenue, profit, and ROAS will be incomplete. The readiness endpoint flags this before you act on recommendations.
</Tip>

***

## Integration Readiness

Check whether your stack is ready for ROAS analysis.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/connect/apple-ads/playbook/status
```

### Headers

| Header         | Required | Description                                                                                       |
| -------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `X-API-Key`    | Yes      | Your Appeeky API key                                                                              |
| `X-RC-Key`     | No       | RevenueCat secret key. If omitted, Appeeky uses credentials saved in your account when available. |
| `X-RC-Project` | No       | RevenueCat project ID when your key has multiple projects                                         |

### Example

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/connect/apple-ads/playbook/status" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "X-RC-Key: sk_YOUR_REVENUECAT_SECRET_KEY"
```

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "ready": false,
    "appleSearchAdsConnected": true,
    "revenueCatConnected": true,
    "appleAdsAttributionEnabled": false,
    "profitabilityAvailable": false,
    "steps": [
      {
        "id": "revenuecat",
        "title": "Connect RevenueCat",
        "status": "complete",
        "detail": "RevenueCat secret key is saved in Appeeky."
      },
      {
        "id": "apple_adservices",
        "title": "Enable Apple AdServices in RevenueCat",
        "status": "warning",
        "detail": "No Apple Search Ads attribution detected yet. Enable Apple AdServices in RevenueCat Integrations and wait for installs."
      },
      {
        "id": "apple_search_ads",
        "title": "Connect Apple Search Ads",
        "status": "complete",
        "detail": "Apple Search Ads API credentials are connected."
      },
      {
        "id": "profitability",
        "title": "ROAS analysis ready",
        "status": "warning",
        "detail": "Connect both integrations and enable Apple AdServices attribution to unlock ROAS."
      }
    ]
  }
}
```

### Step statuses

| Status       | Meaning                                                       |
| ------------ | ------------------------------------------------------------- |
| `complete`   | Requirement met                                               |
| `warning`    | Connected but data not flowing yet (e.g. attribution pending) |
| `incomplete` | Not configured                                                |

When `ready` is `true`, all steps are `complete` and profitability analysis is fully available.

***

## Optimization Recommendations

Returns a bundled analysis: integration gaps, ROAS-based scale and pause candidates, a RevenueCat attribution sample, and optional review-rating warnings by country.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/connect/apple-ads/playbook/recommendations
```

### Query parameters

| Parameter   | Default   | Description                                                              |
| ----------- | --------- | ------------------------------------------------------------------------ |
| `level`     | `keyword` | Rollup for profitability: `keyword`, `campaign`, or `adgroup`            |
| `days`      | `14`      | Trailing date window                                                     |
| `minSpend`  | `20`      | Minimum spend for insight buckets                                        |
| `minRating` | `4.5`     | App Store rating threshold for review country gate                       |
| `country`   | —         | Optional ISO country code (e.g. `US`) to scope profitability             |
| `appId`     | —         | Apple App Store numeric app ID. Required for review country gate section |

### Headers

Same as [Profitability](/docs/apple-search-ads-profitability): `X-API-Key`, `X-RC-Key`, optional `X-RC-Project`, and optional per-request ASA headers.

### Example

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl \
  "https://api.appeeky.com/v1/connect/apple-ads/playbook/recommendations?level=keyword&days=14&appId=123456789&country=US" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "X-RC-Key: sk_YOUR_REVENUECAT_SECRET_KEY"
```

### Response shape

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "playbook": { "...": "same as /playbook/status" },
    "profitability": { "...": "same as /profitability" },
    "attribution": {
      "sampleSize": 50,
      "customersWithAttribution": 12,
      "appleSearchAdsAttributed": 8,
      "attributionEnabled": true,
      "rows": [
        {
          "mediaSource": "Apple Search Ads",
          "campaign": "US Brand",
          "adGroup": null,
          "keyword": "competitor name",
          "country": "US",
          "customerCount": 3,
          "totalRevenue": 47.97
        }
      ]
    },
    "reviewGate": {
      "appId": "123456789",
      "minRating": 4.5,
      "rows": [],
      "warnings": []
    },
    "recommendations": [
      {
        "type": "scale",
        "priority": "high",
        "title": "Scale: competitor name",
        "detail": "ROAS 2.10x with $82 spend and 19 installs.",
        "keyword": "competitor name",
        "roas": 2.1,
        "spend": 82
      }
    ]
  }
}
```

### Recommendation types

| Type          | Meaning                                                                           |
| ------------- | --------------------------------------------------------------------------------- |
| `setup`       | Missing integration or attribution step                                           |
| `scale`       | Strong ROAS with enough spend — candidate to increase budget or bids              |
| `kill`        | Meaningful spend with weak ROAS or zero installs — candidate to pause or bid down |
| `attribution` | Top rows from RevenueCat customer attribution sample                              |
| `review_gate` | Country with active campaigns but App Store rating below threshold                |

***

## Review Country Gate

Low App Store ratings in a country can hurt conversion on paid traffic. This endpoint compares **active** Apple Search Ads campaign targeting against the app's **App Store rating in each country**.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/connect/apple-ads/review-country-gate?appId=123456789
```

### Query parameters

| Parameter   | Required | Default | Description                                    |
| ----------- | -------- | ------- | ---------------------------------------------- |
| `appId`     | Yes      | —       | Apple App Store numeric app ID                 |
| `minRating` | No       | `4.5`   | Flag countries at or below this average rating |

### Example

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl \
  "https://api.appeeky.com/v1/connect/apple-ads/review-country-gate?appId=123456789&minRating=4.5" \
  -H "X-API-Key: YOUR_APPEEKY_KEY"
```

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "appId": "123456789",
    "minRating": 4.5,
    "rows": [
      {
        "country": "TH",
        "countryCode": "TH",
        "rating": 3.8,
        "reviewCount": 42,
        "campaignCount": 1,
        "campaignNames": ["SEA Tier 3"],
        "status": "critical",
        "recommendation": "Rating 3.8 is below 4.5. Pause or remove this country from campaigns to avoid burning budget on low-trust listings."
      }
    ],
    "warnings": []
  }
}
```

### Row status

| Status     | Meaning                                                          |
| ---------- | ---------------------------------------------------------------- |
| `ok`       | Rating meets threshold                                           |
| `warning`  | Rating could not be fetched — verify manually                    |
| `critical` | Rating below threshold while campaigns still target this country |

Ratings are sourced from the public App Store catalog per country. They reflect the listing users see when your ad appears in that storefront.

***

## Country-Scoped Profitability

Filter ROAS analysis to campaigns that target a single country. Useful when you run separate campaigns per region.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/connect/apple-ads/profitability?level=keyword&days=14&country=US
```

Appeeky filters using each campaign's `countriesOrRegions` metadata from Apple Search Ads. Revenue attribution remains at the keyword, ad group, or campaign level from RevenueCat charts — country filtering applies to spend and campaign scope, not a second revenue dimension.

See [Apple Search Ads Profitability](/docs/apple-search-ads-profitability) for full parameters, response fields, and insight types.

***

## Typical Workflow

1. **Check readiness** — `GET /playbook/status` until `ready` is `true`.
2. **Review recommendations** — `GET /playbook/recommendations?appId=…` for scale, pause, and country warnings.
3. **Drill into keywords** — `GET /profitability?level=keyword&country=US` for a focused table.
4. **Validate attribution** — [RevenueCat Attribution](/docs/revenuecat-attribution) for customer-level keyword × campaign × country rows.
5. **Act** — pause campaigns, adjust bids, or add negatives via [Campaigns](/docs/apple-search-ads-campaigns) and [Keywords](/docs/apple-search-ads-keywords), or ask your assistant via [MCP](/docs/apple-search-ads-mcp).

***

## MCP Tools

| Tool                            | Description                                                         |
| ------------------------------- | ------------------------------------------------------------------- |
| `asa_playbook_status`           | Integration readiness checklist                                     |
| `asa_admaxxing_recommendations` | Full optimization bundle (setup + ROAS + attribution + review gate) |
| `asa_review_country_gate`       | Country rating vs active campaign targeting                         |
| `asa_profitability`             | ROAS join; supports `country` filter                                |

See [Apple Search Ads MCP Tools](/docs/apple-search-ads-mcp) for parameters and example prompts.

***

## Related Docs

* [Apple Search Ads Profitability](/docs/apple-search-ads-profitability)
* [RevenueCat Attribution](/docs/revenuecat-attribution)
* [Apple Search Ads Overview](/docs/apple-search-ads)
* [RevenueCat Overview](/docs/revenuecat-overview)