Preserving customer identity, subscription states, and campaigns when changing CRM tools

The starting point for the decision

The first decision in CRM migration is “who starts sending, and when?” Even while the same customer is registered in both tools, responsibility for the same business message must belong to only one.

This guide proposes correct customer identity, preserved messaging eligibility, and verified campaign-level sending responsibility plus stopping and return conditions as completion criteria. Do not activate campaigns just because imported row counts match. Separate transferable data from recipients actually ready for delivery, and transfer responsibility from a small test cohort onward.

The scope is a CRM and messaging environment operating push, email, text messages, and automated campaigns, rather than every sales-pipeline or support record. Specific feature differences are explained through a migration from Braze to OneSignal while retaining the existing app. This is neither a product recommendation nor an account of a real customer migration. Product documentation was checked as of September 26, 2026.

If the choice between staying, upgrading, and migrating is still open, first review the decision criteria in the OneSignal paid-plan transition guide. This article addresses the technical transition after migration has been chosen.

Divide migration objects into eight categories

OneSignal distinguishes a User representing a customer from a Subscription representing a channel contact point. Multiple devices and channel subscriptions can belong to one customer. Do not treat your own customer external_id, the OneSignal-assigned user ID, and an individual Subscription ID as interchangeable. OneSignal Users^[1] · Subscriptions^[2].

The following is a design example for dividing the work. “Preserve” means preserving the original value or meaning, not importing the original file unchanged.

Use an internal customer ID that survives tool changes as the identity reference. Do not merge people merely because an email address or phone number matches. Without evidence linking an anonymous user, leave that user anonymous or hold them out of sending. Avoid filling every empty ID with the same fallback value.

Shared devices particularly require testing the sequence where customer A logs out and B logs in. OneSignal login can change the user associated with a subscription. Verify ownership and attributes after account switching, rather than only confirming association at the first login. OneSignal Users^[1].

A single eligible-to-receive field is insufficient

OS/browser permission describes whether notifications are allowed on that device. Technical channel subscription describes whether a particular token or address can use the channel. Marketing consent and opt-out records concern the person’s choice to receive messages for particular purposes and channels. Do not combine these three axes in migration design.

Braze also distinguishes device push enablement from the user profile’s push subscription state. Subscribed is a default profile state, while Opted-In can be set through acceptance of OS notification permission. Neither value alone should be interpreted as evidence of purpose-specific marketing consent. Braze Push subscription states^[3].

Check email and SMS subscription groups separately too. Braze’s subscription-group lookup API returns groups with a history of state changes; absence of a group in the response must not be interpreted as permission to send. Unsubscribing from OneSignal push is also not equivalent to unsubscribing from all channels. Braze subscription-group lookup^[4] · OneSignal Subscriptions^[2].

A recommended design keeps an authoritative record of state, change timestamp, source, and version for each customer ID, channel, and purpose. Hold automated sending when the tools disagree or supporting evidence is missing. Verified subsequent consent can be recorded separately, but re-uploading a CSV or initializing an SDK is not renewed consent. This is a technical state-preservation design, not a determination of the legal sending requirements for individual messages.

For example, test a case where yesterday’s export says “allowed” but the customer opts out today. In this design example, today’s refusal must remain an effective sending block even if that file is imported again tomorrow or the app registers a new subscription. Prevent deleted customers from being resurrected by old files in the same way.

This does not mean retaining consent records forever. First define the minimum necessary information, access permissions, and retention/deletion policy, then prevent state reversals during migration within those boundaries.

Token portability depends on the channel

On mobile, check both the app and sending credentials

An Apple APNs token corresponds to a device-and-app combination. It cannot be reused as another app’s token. Check app identity, development/production environment, and APNs authentication. Firebase also returns SENDER_ID_MISMATCH when the authenticated sender does not match the token’s sender requirements. Copying a token string therefore does not establish continuity of delivery. Apple APNs registration^[5] · APNs connection requirements, Apple archive^[6] · FCM error codes^[7].

Import behavior also differs in OneSignal. Valid iOS subscriptions can receive push before SDK activation when the relevant conditions hold, but confirmed receipt and click tracking require an active SDK. Android requires the OneSignal SDK to be active on the device for the normal delivery path. Raw iOS APNs tokens must also be distinguished from FCM registration tokens. OneSignal migration guide^[8].

Avoid combining a messaging-tool replacement for the same app with changes to app identity or the Firebase project. Separate populations whose requirements change into their own transition, with token recollection and an app release where necessary.

Do not assume both SDKs should be installed together

OneSignal primarily recommends replacing the existing SDK in one app release. If both SDKs must coexist, prevent conflicts in token lifecycle management and notification handlers. Assign responsibility for device-side token management separately from responsibility for server-side campaign delivery. OneSignal migration guide^[8].

Even when old and new populations are divided by app version, verify that actual recipients respect that boundary. If several devices belong to a user-level journey, separately decide whether updating one device is enough to transfer responsibility for the whole customer.

On the web, distinguish retained permission from transferred subscriptions

OneSignal does not support direct import of existing web-push subscriptions. It describes re-registering a subscription when users revisit the same HTTPS origin where notification permission is already granted. Users who have not returned must not be counted as completed migrations. OneSignal migration guide^[8].

For web push, examine the origin, subscription endpoint and keys, and Service Worker deployment together. When replacing the old push worker, do not indiscriminately unregister workers that also provide PWA caching or offline functionality. If the origin changes, do not assume permission carries over; review permission and subscription enrollment in the new environment. W3C Push API Working Draft^[9].

Email and SMS also require separating recipient-address migration from sender-environment readiness. Mapping email addresses, phone numbers, and related states in a CSV does not complete sending-domain configuration or an SMS sender transition. If those requirements are unverified, leave that channel classified as not yet operational. OneSignal Import^[10] · Email setup^[11] · SMS setup^[12].

An export may represent only part of the current state

Braze’s user export API provides identifiers, subscription states, push tokens, and attributes, but user-profile custom_events and purchases are summaries covering the last 90 days. They are not the complete raw event log or the execution position of an active Canvas. First distinguish what can be archived from what must be reconstructed. Braze user export^[13].

On the target side, transform mobile subscriptions into the Create user API model, and use CSV import for the identifiers, addresses, attributes, and states its documentation supports. CSV changes to subscription state particularly require an email address, phone number, Subscription ID, or another supported subscription identifier. Do not assume external_id alone changes every channel’s state. Create user^[14] · Import^[10].

There are pitfalls when exporting again from OneSignal or inspecting migration results. A subscription CSV restricted to a segment includes subscribed subscriptions by default. Check include_unsubscribed=true when opt-outs must be included. That option has no effect without a specified segment. The export’s id is a Subscription ID, which also differs from a customer ID. Export subscriptions CSV^[15].

A recommended approach manages the full state at a reference time separately from subsequent changes. Carry opt-outs, deletions, account-association changes, and new subscriptions from the initial export through final cutover. An API that selects “recently active users” does not necessarily capture every state change. OneSignal’s last_active_since is an activity-time filter, not a promise to export complete change history. Export subscriptions CSV^[15].

If changes cannot be captured reliably, design a controlled change-freeze window and final reconciliation rather than forcing real-time coexistence. Do not, however, block the receipt of opt-outs. Record received changes in the authoritative record and maintain a path that applies them to sending blocks in both tools.

Transition runbook: define entry and stopping conditions together

The following is a transition runbook design example reflecting constraints across official documentation, not an automated feature of a particular product. Set actual cohort sizes and observation periods according to campaign waits, app-update distribution, and message expiry.

Reconcile sets, rather than concluding that “customer counts are similar.” For sends normalized under the same rules, check overlap between source and target ownership and identify sends belonging to neither. If sending to all devices is intentional, include each intended device delivery in the expected set from the start.

Numerical design example. Assume 1,000 candidate sends, each representing one push for the same campaign step per customer. Excluding 80 opt-outs and holding 100 SDK-unready plus 20 unidentified cases leaves 800 eligible sends.

All candidates 1,000 = opt-outs excluded 80 + held 120 + eligible 800

Source-owned 500 + target-owned 310 - overlap 10 = distinct sends 800

Covering all 800 eligible sends is not a pass if 10 overlap. Remove target ownership from those 10 and the split becomes source 500, target 300, overlap zero. These are auditable set-reconciliation numbers, not actual migration results. In a real decision, compare each send’s identifier rather than matching totals alone.

Do not migrate active campaigns by simply switching them back on

Segments and automated journeys do not continue merely because a customer list was copied. OneSignal segments support subscription-level and user-level evaluation; a user-level condition can target multiple subscriptions belonging to that user. Consequently, running user-level journeys in both tools can cross an intended boundary based on device app versions. OneSignal Segments^[16].

The migration plan should maintain a record fixing one sending owner for each customer, campaign, channel, and step. Include the business event ID identifying the originating purchase or sign-up, campaign version, and step. Manage customer-level frequency limits separately from device-level delivery.

Design ownership transfer in this order: block new source sends → reconcile in-progress and unknown requests → apply the latest messaging states → update the ownership version → enable target sends. Changing a tool name in a table is insufficient. Custom sending servers should check current ownership and processing records immediately before sending; tool-native paths must enforce the boundary through actual schedules, journeys, and permissions. Do not enable the target while a gap allows both tools to process the same send.

There are two ways to handle active journeys. Draining the existing journey means closing new source entries, leaving remaining recipients and steps with the source, and excluding them from the target. Reconstructing remaining steps in the target means clearing source schedules and waits, then creating only unprocessed work using the last completed step, next scheduled time, frequency limit, and expiry. Verify feasibility using the actual export, stop, and lookup capabilities.

Separate the path that archives historical events for analysis from the path that starts new campaigns. Do not ingest past purchases as new purchase events or restart historical welcome campaigns for everyone in the new environment.

Copying OneSignal re-entry and exit settings is not sufficient either. A Custom Event-based Journey can allow multiple instances for the same user, and the first step can run even when entry and exit conditions are both satisfied. For customers who must not receive messages, verify exclusions before entry rather than relying only on exit conditions. Journey settings^[17].

A deduplication key in a server’s sending record is ineffective if an operator sends directly from the source dashboard or a default Journey bypasses it. APIs, automated journeys, scheduled sends, and manual sends must all fit within the same responsibility boundary. If that cannot be ensured, use an explicit sending pause rather than leaving both tools enabled.

OneSignal’s notification-creation API provides an idempotency_key for retries, with notification request keys retained for 30 days. This controls request reprocessing within the same tool. It is not a shared deduplication mechanism that also blocks a message independently sent by Braze. Idempotent API requests^[18].

Stopping a source campaign also does not establish that notifications already accepted and queued by a delivery service have disappeared. FCM can store messages while a device is offline and deliver them before expiry. If an earlier request’s outcome is unknown, decide whether to inspect, wait for expiry, or hold it rather than immediately resending through the new tool. FCM message lifespan^[19].

Apply Go/No-go criteria before comparing counts

The recommended stopping criteria are clear: if an incorrect customer merge, permission to send to an opted-out recipient, or dual ownership of the same send is found, first block new sends for that scope in both tools and stop expansion. Do not advance with unexplained omissions or uncertainty about whether the latest opt-outs have been applied. “Zero cases” here is a review acceptance condition, not a guarantee of lossless migration.

Next verify actual delivery paths and campaign outcomes. OneSignal Delivered means handoff to APNs/FCM, while Confirmed indicates device receipt under supported conditions. Confirmed receipt depends on paid-plan, platform, and SDK requirements and is unsupported in some cases, including Safari web push; a missing value therefore does not immediately mean non-delivery. Neither metric is equivalent to a completed purchase or message view. Confirmed receipt^[20].

Agree on failure rates, delays, and observation periods for each app and campaign before testing. Do not rely on one average mixing device types, app versions, channels, and consent states. A previously successful test cohort does not validate a newly added population.

Return options differ by stage.

Even when returning, preserve opt-outs and completed campaign steps recorded in the new environment. Returning to stale source state and reclassifying people as “not yet sent” can itself cause duplicates. Review code, configuration, and database return conditions alongside the rollback-ready deployment guide.

Completion includes an explanation of the remaining population

If you operate one app, stable customer IDs, and few campaigns, with developers and CRM operators able to review together, a separate migration product need not be the first step. First assess whether exports, explicit mappings, sending blocks, and small-scale review can provide the required procedure.

If multiple apps or accounts are mixed, shared-device identity issues exist, or long-wait journeys and several channels must move together, data owners, app developers, CRM operators, and access administrators need to collaborate. Do not assign only file conversion while leaving campaign responsibility vacant.

Account explicitly for remaining old-version users, web users who have not returned, and customers with unverified consent. Decide whether the source continues to own them, they remain on hold, or they are excluded from migration, and name an owner. “We can explain who may receive what, who is responsible, and how the remaining population will be handled” is a more useful completion criterion than “everything was imported.”

If you need outside support to review migration scope and campaigns to retain when moving an existing messaging environment to OneSignal, see IXC’s CRM migration and transition support.