---
id: "revenuecat-support/common-tickets/merging-projects"
title: "Merging RevenueCat Projects"
description: "This guide shows you how to consolidate related RevenueCat projects while preserving subscriber access. RevenueCat can't merge two existing projects automatically, so consolidation is a phased migration: you'll choose a target project, recreate app configurations, migrate purchases, update released apps, and manage the transition."
permalink: "/docs/revenuecat-support/common-tickets/merging-projects"
slug: "merging-projects"
version: "current"
original_source: "docs/revenuecat-support/common-tickets/merging-projects.mdx"
---

> **AI agents:** This is the Markdown version of a RevenueCat documentation page. For the complete documentation index, see [llms.txt](https://www.revenuecat.com/docs/llms.txt).

This guide shows you how to consolidate related RevenueCat projects while preserving subscriber access. RevenueCat can't merge two existing projects automatically, so consolidation is a phased migration: you'll choose a target project, recreate app configurations, migrate purchases, update released apps, and manage the transition.

This is commonly needed when the iOS and Android versions of the same app were accidentally configured as separate projects, or when related apps need to share entitlements and web purchases.

## Why consolidate projects?

A RevenueCat [project](https://www.revenuecat.com/docs/projects/overview) is the top-level container for apps, customers, products, entitlements, Offerings, and integrations. Keeping related apps in the same project allows them to:

- Share [entitlements](https://www.revenuecat.com/docs/getting-started/entitlements) across platforms
- Recognize a customer's access when the same App User ID is used
- Use [Redemption Links](https://www.revenuecat.com/docs/web/redemption-links) across platforms when the web app configuration and every mobile app that redeems its links belong to the same project
- Manage products, Offerings, Paywalls, and integrations together

## 1. Choose the project to keep

Start by comparing the projects and selecting a target. In most cases, keep the project with:

- More production transactions and active subscribers
- More historical reporting that would be difficult to recreate
- The most complete product, entitlement, and integration setup
- The largest number of currently active app versions

Also consider the work required to recreate newer configurations. For example, a recently created sandbox web configuration with no production purchases is usually easier to recreate than an established mobile project with years of transaction history.

The other project becomes the source project. Its app and purchases will move gradually into the target project.

## 2. Add the missing app to the target project

Create a new app configuration in the target project for the platform being migrated. Use the existing App Store bundle ID or Google Play package name.

Before updating the released app, configure and validate the required store credentials and [server notifications](https://www.revenuecat.com/docs/platform-resources/server-notifications) in the new app configuration.

Do not delete or disable the source project. Existing app versions will continue using its public SDK key until customers install an update.

## 3. Recreate products, entitlements, and Offerings

Import or recreate the migrated app's products in the target project. Then:

1. Attach the products to the entitlement that should unlock access.
2. Recreate the app's [Offering](https://www.revenuecat.com/docs/offerings/overview) and packages.
3. Recreate any Paywalls or remote configuration the app needs.
4. Confirm that the target project's [restore behavior](https://www.revenuecat.com/docs/projects/restore-behavior) matches the intended customer-access rules.

Products control what customers purchase and how much they pay. Entitlements control the access those products unlock. Products from different platforms can unlock the same entitlement when the apps belong to one project.

## 4. Decide how to migrate existing purchases

There are two main migration options. They can be used separately or together.

### Optional server-side import

A [server-side import](https://www.revenuecat.com/docs/migrating-to-revenuecat/migrating-existing-subscriptions/receipt-imports) sends existing Apple receipts or Google Play purchase tokens to the new app configuration through RevenueCat's [`POST /receipts` API](https://www.revenuecat.com/docs/api-v1#tag/transactions/operation/receipts).

This usually provides the best coverage because it does not depend on customers opening the updated app. It is especially useful for active subscribers who need access immediately after the migration.

The import should associate each receipt or purchase token with the same custom App User ID used by that customer in the app. Before submitting production receipts or purchase tokens that RevenueCat already tracks in another project, [contact RevenueCat Support](https://app.revenuecat.com/settings/support) to review the migration plan.

Server-side imports have some limitations:

- They require access to the original receipts or purchase tokens. If you don't have them, RevenueCat Support can provide an export of the receipt and purchase token data available in the source project.
- Store APIs may not return complete history for older purchases.
- Imported purchases may not reproduce every historical chart or reporting detail from the source project.
- Google Play purchases expired for more than 60 days generally cannot be imported through their purchase tokens.

### Client-side migration from the SDK

After the app begins using the target project's public SDK key, call `syncPurchases()` once for existing customers. This sends the purchases available from the device's store account to the new project without showing an OS-level sign-in prompt.

This option is simpler, but it only migrates customers who open the updated app. It may also not recover expired purchase history or reproduce historical reporting.

Starting with RevenueCat Android SDK 9 and Google Play Billing Library 8, `syncPurchases()` can recover active subscriptions and non-consumed one-time purchases, but not all historical purchases.

Do not call `syncPurchases()` on every app launch. Trigger it once per Customer after configuring or logging in to RevenueCat with the same custom App User ID used in the source project. Record a successful sync so the migration does not run again for that Customer.

### Recommended coverage

After RevenueCat Support reviews the migration plan, you may use a server-side import with `syncPurchases()` as a fallback. This can cover customers included in the import while catching active purchases that were missed or created during the transition.

[Google Historical Import](https://www.revenuecat.com/docs/migrating-to-revenuecat/migrating-existing-subscriptions/google-historical-import) can help fill gaps in older Google Play reporting, but it does not replace the main purchase migration.

## 5. Release the app with the target project's SDK key

Update the migrated app to use the public SDK key from its new app configuration in the target project.

The release should:

- Identify customers with the same custom [App User IDs](https://www.revenuecat.com/docs/customers/user-ids) used before the migration
- Call `syncPurchases()` once when applicable
- Read access from the entitlement configured in the target project
- Continue providing a user-initiated [Restore Purchases](https://www.revenuecat.com/docs/getting-started/restoring-purchases) option

Test the migration in sandbox before releasing it broadly.

## 6. Recreate integrations and store notifications

Review project-level and app-level configuration that may need to be recreated or updated, including:

- Apple App Store Server Notifications
- Google Play real-time developer notifications
- Webhooks
- Attribution and third-party integrations
- Scheduled Data Exports
- Web Billing, Paddle, or Stripe configurations
- Redemption Links and custom URL schemes

Plan an explicit Apple and Google server-notification cutover. Don't assume the source and target configurations can both receive the same store notifications during the transition.

Project-level integrations may begin receiving events from all apps in the consolidated project. If an integration needs app-specific behavior, filter events using app, store, product, or other identifiers available in its payloads.

## 7. Keep the source project during the transition

Older app versions continue communicating with the source project because they still contain its SDK key. Keep its credentials, products, Offerings, and integrations working while those versions remain active.

During the transition:

- Monitor adoption of the new app version.
- Compare active subscribers in both projects.
- Verify that migrated customers receive the expected entitlement.
- Keep the source project available for historical reporting.
- Avoid changing or deleting configurations still used by older releases.

There is rarely a reason to delete the source project immediately. Keeping it available provides a rollback path and preserves historical visibility.

## Identity and restore-behavior considerations

Use consistent custom App User IDs across the apps whenever possible. RevenueCat customers are scoped to a project, so the same identifier in two separate projects represents two separate customer records until the purchase is imported or synchronized into the target project.

If customers use anonymous IDs, reinstall the app, or change identifiers during migration, the target project's restore behavior determines whether purchases transfer, alias, or return an ownership error.

Review restore behavior before migrating production customers, and test the important identity scenarios in sandbox.

## What does not migrate automatically?

Consolidating projects does not automatically move:

- Customer records
- Receipts or purchase tokens
- Historical charts
- Products, entitlements, Offerings, or Paywalls
- Webhooks and other integrations
- Store credentials and notification configuration
- Audit logs

The goal is to preserve customer access and move future activity into one project. The source project may still be needed to inspect historical activity that cannot be reconstructed in the target.

## Final checklist

Before switching production traffic, confirm that:

- The target project contains all required app configurations.
- Store credentials and server notifications are valid.
- Products are attached to the correct entitlements.
- Offerings and Paywalls return the expected products.
- Custom App User IDs remain consistent.
- The server-side import or `syncPurchases()` plan has been tested.
- Web purchases and Redemption Links work on every supported platform.
- Older app versions can continue using the source project.
- Project-level integrations can handle events from the consolidated apps.

With a phased migration, active subscribers can retain access while new purchases, renewals, and web redemptions gradually move into the consolidated project.