asc-revenuecat-catalog-sync

Original source / Raw SKILL.md

---
name: asc-revenuecat-catalog-sync
description: Reconcile App Store Connect subscriptions and in-app purchases with RevenueCat products, entitlements, offerings, and packages using asc and RevenueCat MCP. Use when setting up or syncing subscription catalogs across ASC and RevenueCat.
---

# asc RevenueCat catalog sync

Use this skill to keep App Store Connect (ASC) and RevenueCat aligned, including creating missing ASC items and mapping them to RevenueCat resources.

## When to use
- You want to bootstrap RevenueCat from an existing ASC catalog.
- You want to create missing ASC subscriptions/IAPs, then map them into RevenueCat.
- You need a drift audit before release.
- You want deterministic product mapping based on identifiers.

## Preconditions
- `asc` authentication is configured (`asc auth login` or `ASC_*` env vars).
- RevenueCat MCP server is configured and authenticated.
- In Cursor and VS Code, OAuth auth is available for RevenueCat MCP. API key auth is also supported.
- You know:
  - ASC app ID (`APP_ID`)
  - RevenueCat `project_id`
  - target RevenueCat app type (`app_store` or `mac_app_store`) and bundle ID for create flows
- Use a write-enabled RevenueCat API v2 key when applying changes.

## Safety defaults
- Start in **audit mode** (read-only).
- Require explicit confirmation before writes.
- Never delete resources in this workflow.
- Continue on per-item failures and report all failures at the end.

## Canonical identifiers
- Primary cross-system key: ASC `productId` == RevenueCat `store_identifier`.
- Keep `productId` stable once products are live.
- Do not use display names as unique identifiers.

## Scope boundary
- RevenueCat MCP configures RevenueCat resources; it does not create App Store Connect products directly.
- Use `asc` commands to create missing ASC subscription groups, subscriptions, and IAPs before RevenueCat mapping.

## Modes

### 1) Audit mode (default)
1. Read ASC source catalog.
2. Read RevenueCat target catalog.
3. Build a diff with actions:
   - missing in ASC
   - missing in RevenueCat
   - mapping conflicts (identifier/type/app mismatch)
4. Present a plan and wait for confirmation.

### 2) Apply mode (explicit)
Execute approved actions in this order:
1. Ensure ASC groups/subscriptions/IAP exist.
2. Ensure RevenueCat app/products exist.
3. Ensure entitlements and product attachments.
4. Ensure offerings/packages and package attachments.
5. Verify and print a final reconciliation summary.

## Step-by-step workflow

### Step A - Read current ASC catalog

```bash
asc subscriptions groups list --app "APP_ID" --paginate --output json
asc iap list --app "APP_ID" --paginate --output json
# for each subscription group:
asc subscriptions list --group-id "GROUP_ID" --paginate --output json
```

### Step B - Read current RevenueCat catalog (MCP)

Use these MCP tools (with `project_id` and pagination where applicable):
- `mcp_RC_get_project`
- `mcp_RC_list_apps`
- `mcp_RC_list_products`
- `mcp_RC_list_entitlements`
- `mcp_RC_list_offerings`
- `mcp_RC_list_packages`

### Step C - Build mapping plan

Map ASC product types to RevenueCat product types:
- ASC subscription -> RevenueCat `subscription`
- ASC IAP `CONSUMABLE` -> RevenueCat `consumable`
- ASC IAP `NON_CONSUMABLE` -> RevenueCat `non_consumable`
- ASC IAP `NON_RENEWING_SUBSCRIPTION` -> RevenueCat `non_renewing_subscription`

Suggested entitlement policy:
- subscriptions: one entitlement per subscription group (or explicit map provided by user)
- non-consumable IAP: one entitlement per product
- consumable IAP: no entitlement by default unless user asks

### Step D - Ensure missing ASC items (if requested)

Create missing ASC resources first, then re-read ASC to capture canonical IDs.

```bash
# create subscription group
asc subscriptions groups create --app "APP_ID" --reference-name "Premium"

# create subscription
asc subscriptions create \
  --group-id "GROUP_ID" \
  --reference-name "Monthly" \
  --product-id "com.example.premium.monthly" \
  --subscription-period ONE_MONTH

# create iap
asc iap create \
  --app "APP_ID" \
  --type NON_CONSUMABLE \
  --ref-name "Lifetime" \
  --product-id "com.example.lifetime"
```

### Step E - Ensure RevenueCat app and products

Use MCP:
- create app if missing: `mcp_RC_create_app`
- create products: `mcp_RC_create_product`
  - `store_identifier` = ASC `productId`
  - `app_id` = RevenueCat app ID
  - `type` from mapping above

### Step F - Ensure entitlements and attachments

Use MCP:
- list/create entitlements: `mcp_RC_list_entitlements`, `mcp_RC_create_entitlement`
- attach products: `mcp_RC_attach_products_to_entitlement`
- verify attachments: `mcp_RC_get_products_from_entitlement`

### Step G - Ensure offerings and packages (optional)

Use MCP:
- list/create/update offerings:
  - `mcp_RC_list_offerings`
  - `mcp_RC_create_offering`
  - `mcp_RC_update_offering` (`is_current=true` only if requested)
- list/create packages:
  - `mcp_RC_list_packages`
  - `mcp_RC_create_package`
- attach products to packages:
  - `mcp_RC_attach_products_to_package` with `eligibility_criteria: "all"`

Recommended package keys:
- `ONE_WEEK` -> `$rc_weekly`
- `ONE_MONTH` -> `$rc_monthly`
- `TWO_MONTHS` -> `$rc_two_month`
- `THREE_MONTHS` -> `$rc_three_month`
- `SIX_MONTHS` -> `$rc_six_month`
- `ONE_YEAR` -> `$rc_annual`
- lifetime IAP -> `$rc_lifetime`
- custom -> `$rc_custom_<name>`

## Expected output format

Return a final summary with:
- ASC created counts (groups/subscriptions/IAP)
- RevenueCat created counts (apps/products/entitlements/offerings/packages)
- attachment counts (entitlement-products, package-products)
- skipped existing items
- failed items with actionable errors

Example:

```text
ASC: created groups=1 subscriptions=2 iap=1, skipped=14, failed=0
RC: created apps=0 products=3 entitlements=2 offerings=1 packages=2, skipped=27, failed=1
Attachments: entitlement_products=3 package_products=2
Failures:
- com.example.premium.annual: duplicate store_identifier exists on another RC app
```

## Agent behavior
- Always run audit first, even in apply mode.
- Ask for confirmation before create/update operations.
- Match by `store_identifier` first.
- Use full pagination (`--paginate` for ASC, `starting_after` for RevenueCat tools).
- Continue processing after per-item failures and report all failures together.
- Never auto-delete ASC or RevenueCat resources in this skill.

## Common pitfalls
- Wrong RevenueCat `project_id` or app ID.
- Creating RC products under the wrong platform app.
- Accidentally assigning consumables to entitlements.
- Skipping the post-create ASC re-read step.
- Missing offering/package verification after product creation.

## Additional resources
- Workflow examples: [examples.md](examples.md)
- Source references: [references.md](references.md)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### examples.md

```markdown
# Examples: asc RevenueCat catalog sync

Use these examples as execution templates for realistic catalog synchronization workflows.

## Example 1: Drift audit only (read-only)

Goal: compare ASC and RevenueCat, produce a no-write reconciliation report.

### User request
`Audit my ASC subscriptions and IAP catalog against RevenueCat and show what is missing on either side.`

### Expected behavior
1. Read ASC:
   - `asc subscriptions groups list --app "APP_ID" --paginate --output json`
   - `asc iap list --app "APP_ID" --paginate --output json`
   - `asc subscriptions list --group-id "GROUP_ID" --paginate --output json` (for each group)
2. Read RevenueCat via MCP:
   - list apps/products/entitlements/offerings/packages for `project_id`
3. Build and present a diff:
   - missing in ASC
   - missing in RevenueCat
   - type mismatch
   - app/platform mismatch
4. Stop for confirmation (no writes).

## Example 2: Create missing ASC subscriptions, then map to RevenueCat

Goal: bootstrap both systems when store products are partially missing.

### User request
`Ensure monthly and annual subscriptions exist in ASC for app APP_ID, then sync them to RevenueCat project PROJECT_ID under my iOS app.`

### Expected behavior
1. Audit existing resources first.
2. If missing in ASC:
   - create group:
     - `asc subscriptions groups create --app "APP_ID" --reference-name "Premium"`
   - create subscriptions:
     - `asc subscriptions create --group-id "GROUP_ID" --reference-name "Monthly" --product-id "com.example.premium.monthly" --subscription-period ONE_MONTH`
     - `asc subscriptions create --group-id "GROUP_ID" --reference-name "Annual" --product-id "com.example.premium.annual" --subscription-period ONE_YEAR`
3. Re-read ASC to capture authoritative IDs.
4. In RevenueCat:
   - create app if missing (`type: app_store`, same bundle identifier)
   - create products with matching `store_identifier`
   - create entitlement (for example `premium`) and attach products
   - optionally create `default` offering with `$rc_monthly` and `$rc_annual`
5. Verify with final summary and failures list.

## Example 3: Sync one-time IAP and keep consumables entitlement-free

Goal: model recommended entitlement behavior by product type.

### User request
`Sync my non-consumable lifetime IAP and consumable coin pack to RevenueCat.`

### Expected behavior
1. Confirm product type mapping:
   - `NON_CONSUMABLE` -> `non_consumable`
   - `CONSUMABLE` -> `consumable`
2. Create missing ASC IAPs if requested:
   - `asc iap create --app "APP_ID" --type NON_CONSUMABLE --ref-name "Lifetime" --product-id "com.example.lifetime"`
   - `asc iap create --app "APP_ID" --type CONSUMABLE --ref-name "Coins 100" --product-id "com.example.coins.100"`
3. In RevenueCat:
   - create both products
   - attach **non-consumable** product to an entitlement (for example `lifetime_access`)
   - skip entitlement attachment for consumable by default (unless user explicitly asks)
4. Return created/skipped/failed counts.

## Example 4: Controlled apply in CI-style automation

Goal: make apply mode safe and repeatable in team workflows.

### User request
`Run a full sync and apply missing resources.`

### Expected behavior
1. Run audit and print plan.
2. Request explicit approval.
3. Apply in deterministic order:
   - ASC group/subscription/IAP
   - RC app/product
   - RC entitlement + attachments
   - RC offering/package + attachments
4. Continue after item failures and aggregate errors.
5. Print machine-readable summary plus human-readable recap.

## Suggested natural-language prompts for MCP

- `List all apps in RevenueCat project PROJECT_ID and show which one matches bundle id com.example.app`
- `Create RevenueCat product com.example.premium.monthly as subscription in app APP_ID`
- `Create entitlement premium and attach product PRODUCT_ID`
- `Create offering default with packages $rc_monthly and $rc_annual`
- `Show complete offering configuration including packages and attached products`

```

### references.md

```markdown
# References

These sources were used to validate command/tool assumptions and workflow boundaries.

## RevenueCat MCP docs

- MCP overview:
  - https://www.revenuecat.com/docs/tools/mcp
- Setup and authentication (OAuth/API key, cloud endpoint):
  - https://www.revenuecat.com/docs/tools/mcp/setup
- Tools reference (tool names, parameters, enums, package naming):
  - https://www.revenuecat.com/docs/tools/mcp/tools-reference
- Usage examples (natural language interaction patterns):
  - https://www.revenuecat.com/docs/tools/mcp/usage-examples
- Best practices and troubleshooting:
  - https://www.revenuecat.com/docs/tools/mcp/best-practices-and-troubleshooting

## RevenueCat product model docs

- Configuring products (products, entitlements, offerings model):
  - https://www.revenuecat.com/docs/projects/configuring-products
- iOS product setup in App Store Connect (store-side creation details):
  - https://www.revenuecat.com/docs/getting-started/entitlements/ios-products

## RevenueCat MCP launch context

- Launch post and current beta limitations:
  - https://www.revenuecat.com/blog/company/introducing-revenuecat-mcp/

```