> ## 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.

# RevenueCat Attribution

> Read Apple Search Ads attribution from RevenueCat customer attributes and aggregate revenue by campaign, keyword, and country

When Apple AdServices is enabled in RevenueCat, attributed installs write reserved customer attributes such as media source, campaign, ad group, and keyword. Appeeky reads these attributes through the RevenueCat API so you can tie subscription revenue back to paid acquisition — without exporting files manually.

Use this alongside [Apple Search Ads Profitability](/docs/apple-search-ads-profitability), which joins spend from Apple with revenue from RevenueCat charts. Attribution endpoints complement that view with **customer-level** dimensions, including country.

***

## What This Answers

* Which keywords drove paying customers, not just chart-level revenue segments?
* How does attributed revenue break down by campaign and country?
* Is Apple Search Ads attribution actually flowing into RevenueCat?

<Note>
  Customer attributes are fetched per customer. The summary endpoint samples recent customers for responsiveness. For large-scale historical analysis, RevenueCat Scheduled Data Exports remain the right tool inside RevenueCat; Appeeky focuses on live optimization workflows.
</Note>

***

## Prerequisites

1. An Appeeky API key.
2. A RevenueCat **secret** API key (`sk_…`) via `X-RC-Key`.
3. **Apple AdServices** enabled in RevenueCat → Integrations.
4. Installs with attribution data — attributes appear after attributed users are recorded.

Optional: `X-RC-Project` when your API key accesses multiple RevenueCat projects.

***

## Attribution Summary

Aggregates a sample of customers who have attribution attributes, grouped by media source, campaign, keyword, and customer country. Includes total attributed revenue per group.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/connect/revenuecat/attribution-summary
```

The same endpoint is also available at:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/revenuecat/attribution-summary
```

Both paths behave identically. Connect-prefixed routes work with the Appeeky Connect client and dashboard proxy.

### Query parameters

| Parameter | Default | Description                     |
| --------- | ------- | ------------------------------- |
| `limit`   | `50`    | Max customers to sample (1–100) |

### Example

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/connect/revenuecat/attribution-summary?limit=50" \
  -H "X-API-Key: YOUR_APPEEKY_KEY" \
  -H "X-RC-Key: sk_YOUR_REVENUECAT_SECRET_KEY" \
  -H "X-RC-Project: proj_YOUR_PROJECT_ID"
```

### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "sampleSize": 50,
    "customersWithAttribution": 14,
    "appleSearchAdsAttributed": 9,
    "attributionEnabled": true,
    "rows": [
      {
        "mediaSource": "Apple Search Ads",
        "campaign": "US Competitors",
        "adGroup": "Exact match",
        "keyword": "rival app",
        "country": "US",
        "customerCount": 4,
        "totalRevenue": 63.96
      }
    ]
  }
}
```

### Fields

| Field                      | Description                                             |
| -------------------------- | ------------------------------------------------------- |
| `sampleSize`               | Customers scanned in this request                       |
| `customersWithAttribution` | Customers with at least one attribution attribute       |
| `appleSearchAdsAttributed` | Customers whose media source indicates Apple Search Ads |
| `attributionEnabled`       | Whether any attribution data was found in the sample    |
| `rows`                     | Aggregated groups sorted by `totalRevenue` descending   |

### Row dimensions

| Field         | RevenueCat attribute                         |
| ------------- | -------------------------------------------- |
| `mediaSource` | `$mediaSource`                               |
| `campaign`    | `$campaign`                                  |
| `adGroup`     | `$adGroup`                                   |
| `keyword`     | `$keyword`                                   |
| `country`     | Customer's last-seen country from RevenueCat |

Revenue per row is summed from each customer's subscription proceeds in USD.

***

## Customer Attributes

Read the full attribute list for a single RevenueCat customer, including parsed attribution fields.

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/connect/revenuecat/customers/:customerId/attributes
```

Also available at:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
GET /v1/revenuecat/customers/:customerId/attributes
```

### Example

```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/connect/revenuecat/customers/cust_abc123/attributes" \
  -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": {
    "customerId": "cust_abc123",
    "attributes": [
      {
        "name": "$mediaSource",
        "value": "Apple Search Ads",
        "updatedAt": 1719590400
      },
      {
        "name": "$campaign",
        "value": "US Competitors",
        "updatedAt": 1719590400
      },
      {
        "name": "$keyword",
        "value": "rival app",
        "updatedAt": 1719590400
      }
    ],
    "attribution": {
      "mediaSource": "Apple Search Ads",
      "campaign": "US Competitors",
      "adGroup": null,
      "ad": null,
      "keyword": "rival app",
      "creative": null
    }
  }
}
```

### Reserved attribution keys

| Key            | Parsed field  |
| -------------- | ------------- |
| `$mediaSource` | `mediaSource` |
| `$campaign`    | `campaign`    |
| `$adGroup`     | `adGroup`     |
| `$ad`          | `ad`          |
| `$keyword`     | `keyword`     |
| `$creative`    | `creative`    |

Other custom attributes on the customer are returned in `attributes` but not mapped into `attribution`.

***

## How This Fits With Profitability

| View                                                  | Source                                | Granularity                           | Best for                                                           |
| ----------------------------------------------------- | ------------------------------------- | ------------------------------------- | ------------------------------------------------------------------ |
| [Profitability](/docs/apple-search-ads-profitability) | Apple Ads reports + RevenueCat charts | Keyword / campaign / ad group         | Spend, ROAS, and rule-based insights in one table                  |
| Attribution summary                                   | RevenueCat customer API               | Keyword × campaign × country (sample) | Confirm attribution is live; see revenue by acquisition dimensions |
| [ROAS workflow](/docs/apple-search-ads-roas-workflow) | Bundles both + review gate            | End-to-end recommendations            | Weekly optimization review                                         |

Chart-based profitability matches revenue to segment names from RevenueCat. Customer attributes expose the same acquisition dimensions at the user level, which is useful when chart segments lag or you need country alongside keyword.

***

## MCP Tools

| Tool                     | Description                               |
| ------------------------ | ----------------------------------------- |
| `rc_attribution_summary` | Sample and aggregate attributed customers |
| `rc_customer_attributes` | Full attribute list for one customer      |

See [MCP](/docs/mcp) for parameter details.

***

## Errors

| Status | Code                | When                                         |
| ------ | ------------------- | -------------------------------------------- |
| 400    | `MISSING_RC_KEY`    | `X-RC-Key` not provided                      |
| 400    | `MULTIPLE_PROJECTS` | Multiple RC projects; specify `X-RC-Project` |
| 401    | `UNAUTHORIZED`      | Invalid RevenueCat API key                   |
| 404    | `NO_PROJECTS`       | No projects for this key                     |

***

## Related Docs

* [RevenueCat Overview](/docs/revenuecat-overview)
* [RevenueCat Charts](/docs/revenuecat-charts)
* [Apple Search Ads Profitability](/docs/apple-search-ads-profitability)
* [Apple Search Ads ROAS Workflow](/docs/apple-search-ads-roas-workflow)