How do I migrate configuration between Piano environments?

What Is a Setup Transfer?

A Setup Transfer is the process of copying Piano configuration and content assets, such as Composer experiences, templates, offers, terms, and related dependencies, from one Piano application (environment) to another. For example, from a Sandbox application to a Production application, or from Production to a Pre-Production/Stage environment.

When Would I Need a Setup Transfer?

Common scenarios include:

• Promoting tested work to Production: You have built and tested Composer experiences, templates, or term configurations in Sandbox or Stage and want to deploy them to your Production application.

• Refreshing a lower environment: You want to copy Production configuration into Sandbox or Stage so you can test against a current copy of your live setup.

• Copying a subset of assets: You need to transfer specific experiences or offers rather than the entire application configuration.

How Do I Request a Setup Transfer?

Setup Transfers (with the exception of template export/import — see the Section here) are performed by Piano Support. To request a transfer, open a support ticket and include the information described in the Section here.

What Can Be Transferred?

Assets That Can Be Transferred by Support

The following asset types are supported for Setup Transfer:

Assets That Cannot Be Transferred Automatically

The following items are not included in an automated Setup Transfer and require manual configuration in the destination environment:

• User provider / Identity Management configuration (account-level settings)

• Payment provider / gateway configuration (and currency support)

• Localization .po files (must be exported from the source and imported into the destination)

• Custom forms (form "steps" often require manual recreation)

• Site licensing terms/contracts and Grant Access terms

• Purchase flows and upgrade flows within experiences (these cannot be transferred and must be configured manually)

• Upgrade options and Shared subscription settings on terms

• Archived experiences and archived templates (these are excluded from the transfer)

• Newsletter sign-up mailing lists and push notification lists (the cards can be transferred, but the specific list references must be updated manually in the destination)

• Environment-specific references such as:\n

  • Hard-coded image or CSS paths

  • Hard-coded domain URLs

  • Environment-specific analytics tags or settings

Can I Migrate Templates Myself?

Yes. Templates (including template variants) are the one asset type you can migrate on your own using the built-in import functionality, without needing to involve Piano Support.

To import templates from another environment:

1. In the destination application, navigate to Manage → Templates and select Import templates.

2. Configure the import settings:\n

   • Profile: Select an existing saved profile, or choose Import with new profile if this is your first import. If you select a previously saved profile, the remaining fields will be populated automatically.

   • Environment and API URL: Select the environment you are importing from:\n

     • Sandbox — API URL is pre-populated.

     • Production — for the US dashboard; API URL is pre-populated.

     • Custom — for AP, AU, or EU dashboards; you must enter the API URL manually. Refer to the Piano documentation for the relevant URLs for each dashboard locale.

   • Application ID: The Application ID of the source environment.

   • API token: The API token of the source environment.

3. Select which template types you would like to import. You can choose more than one type.

4. Complete the import.

Important notes on import behavior:

• The import process does not overwrite existing template versions, template variants, or content fields if they already exist in the destination (matching is based on entity name).

• New template versions, template variants, and content fields are created only if they do not already exist in the destination.

• After importing, update any references in Composer experiences or custom code (e.g., RunJS) that point to template or variant IDs, as these IDs may differ between environments.

What Transfer Directions Are Supported?

Setup Transfer supports flexible transfer directions between any Piano applications, including:

• Sandbox → Production (promote tested configuration)

• Production → Sandbox/Stage (refresh a lower environment)

• Stage → Production (deploy staged changes)

• Cross-region transfers (e.g., Production US → Production EU)

It is also possible to transfer from one source application to multiple destination applications in a single request. For example, you can transfer from a Sandbox application to both Production EU and Production US at the same time. Include all target Application IDs in your support request.

How Do Overwrites and Matching Work?

Setup Transfer uses matching rules based on item display names to determine how items are handled in the destination. For each item, one of three actions is applied:

Key points to be aware of:

• If an item with the same display name already exists in the destination, it may be updated/overwritten unless you specify otherwise.

• Promotions may not copy if a promotion with the same name already exists in the destination.

• Item IDs will differ between source and destination. Transferred items receive new unique IDs in the destination application.

How Does Versioning Work During a Transfer?

• Only the currently active version of an experience, template, or variant is transferred, even if newer draft versions exist in the source. If you need a specific version migrated, make it active in the source environment before requesting the transfer.

• When a template is updated in the destination, a new version is created based on the source and becomes active. Previous versions of the template remain available in the destination.

• When an experience is updated in the destination (i.e., it already exists with the same name), the source experience is transferred as a new version of the destination experience, but the previously active version remains active. You will need to manually activate the new version after completing your validation.

What Happens to the Experience Status After a Transfer?

The behavior depends on whether the experience is being created or updated in the destination:

Best practice for Production: When creating new experiences in Production, request that the source experience is set to Offline before the transfer, so it does not go live in Production until you have completed validation. Alternatively, ask Support to confirm the expected status behavior for your specific transfer.

How Are Dependencies Handled?

Many Piano assets have dependencies on other assets. For example, an experience may depend on templates, offers, terms, and resources. The transfer process automatically identifies these dependencies and requires that each one is addressed (created, updated, or referenced) before the transfer can proceed.

Common dependency relationships include:

• Experiences depend on templates, offers, terms, resources, and potentially schedules, delivery zones, and external APIs.

• Offers depend on terms and resources.

• Terms depend on resources, and may also depend on schedules, periods, delivery zones, external APIs, and term-specific emails.

• Variants depend on their parent template.

• Custom field forms and sets depend on the individual custom fields they contain.

• Promotions depend on terms and resources.

• Periods depend on their parent schedule.

Asset-Specific Transfer Notes

The following sections detail important behaviors and prerequisites for specific asset types.

Experiences

• All experience types are supported, including AMP and Mobileexperiences. However, the relevant experience type must be enabled in the destination application, or the transfer will fail.

• Archived experiences cannot be transferred.

• Purchase flows and upgrade flows within experiences are not transferred and must be configured manually in the destination.

• Show newsletter sign-up and Show push signup cards can be transferred, but you will need to manually replace the mailing list or push list reference in the destination experience.

• Cross-app resource references are supported for applications that have Global Mode and cross-app access enabled, provided the referenced resources exist in the destination merchant's applications.

• Only the active version is transferred. When updating an existing experience, the transferred version arrives as a new inactive version that must be manually activated.

Templates

• All experience template types are supported (Adblocker, Offer, Newsletter, Site Licensing, etc.), including boilerplate templates.

• Archived templates cannot be transferred.

• Only the active version of a template is transferred.

• When updating an existing template in the destination, a new version is created and becomes active. The previous version remains available.

• Variants are not transferred automatically when transferring a template. Variants must be transferred separately (see the Section here).

• Templates can also be migrated self-service via export/import — see this Section.

Variants

• Only active variants are available for transfer.

• The parent template is a prerequisite — it must be created, updated, or referenced in the destination before the variant can be transferred.

Terms

• Supported term types: Payment, External, Custom, Registration, Access Granted, and Gift. Dynamic terms are described here.

• Not supported: Site licensing terms/contracts and Grant Access terms.

• The transferred term will receive a new unique Term ID in the destination.

• Upgrade options and Shared subscription settings are not transferred and must be configured manually.

• Prerequisites by term type:\n

  • Payment terms and Gift terms: The destination application must have at least one payment provider configured (including currency support) under Edit Business.

  • External terms: The relevant External service API type must be enabled in the destination application.

  • Terms with address collection: The Allow publisher to collect address setting must be enabled in the destination, and the relevant delivery zone must be transferred.

  • Payment terms with scheduled billing: The associated schedule and period must also be transferred.

• If a term has term-specific emails enabled, those emails will automatically be included as dependencies in the transfer.

Dynamic Terms

Dynamic terms can be transferred, but with the following limitations based on the periods they contain:

Offers

• The terms and resources linked to the offer must be transferred (or already exist in the destination) as prerequisites.

• The transferred offer will receive a new unique Offer ID in the destination.

Promotions

• Active, Expired, and Upcoming promotions can be transferred.

• All terms and resources linked to the promotion must be transferred as prerequisites.

• A promotion may not transfer if a promotion with the same name already exists in the destination.

Email Templates

• Only enabled email templates (including the Master email layout) can be transferred. Disabled email templates will not appear as available for transfer.

• When an email template is successfully transferred, the corresponding email notification is automatically enabled in the destination application.

• Important: Enabling email templates in Production can affect live email sending. Many teams choose to migrate email template changes carefully and validate them before allowing them to go live.

Term Emails

• Only term-specific emails that are enabled under a term in the source application can be transferred.

• Term emails are also automatically included as dependencies when transferring the parent term (if enabled).

Consent Fields

• Transferred consent fields retain the same status as in the source (active or inactive).

• The transferred consent field will receive a new unique ID in the destination.

Custom Fields

• Custom fields, custom field forms, and custom field sets can all be transferred.

• Prerequisite: The Identity Management configuration in the destination application must be completed before custom fields can be transferred.

• When transferring a custom field form or set, all individual custom fields included in it are automatically identified as dependencies and must also be addressed in the transfer.

Delivery Zones

• Prerequisite: The Allow publisher to collect address setting must be enabled in the destination application before delivery zones can be transferred.

External API

• External API configurations from Manage → External APIs can be transferred.

• Prerequisite: The relevant external service term/API type must be enabled in the destination application under Edit Business before the transfer.

System Templates

• System templates (System, My Account, and Identity Management) can only be updated, not created. Every application already has system templates from the time of its creation.

Schedules and Periods

• Transferring a period requires the parent schedule to be transferred first.

• Only periods with a future end date can be transferred. Periods that have already ended are excluded.

What Should I Prepare Before Requesting a Transfer?

Information to Provide to Support

Include the following in your support ticket:

1. Source Application ID (AID) and Destination Application ID(s) (AID) — you can specify multiple destination applications if needed.

2. A list of items to transfer, including:\n

   • Experience IDs (EID)

   • Template IDs (and variant IDs if relevant)

   • Any dependent assets to include (offers, terms, resources, schedules, etc.)

3. Desired initial state in the destination (typically: experiences set to Offline)

4. Overwrite approval — confirmation of whether it is acceptable to overwrite items with matching names in the destination, or whether existing items should be referenced as-is

5. Preferred migration date/time window

Pre-Migration Checklist

Before the transfer is performed, complete the following checks:

• Freeze edits to the source experiences and templates you are migrating (to avoid copying a moving target).

• Confirm the source experience is not broken. Composer may display warnings (e.g., a "!" indicator) for invalid or missing dependencies.

• Ensure the correct version is active in the source for each experience and template you want to transfer.

• Confirm the destination prerequisites are in place:\n

  • Payment provider configuration exists and supports the currencies used by terms.

  • Required delivery zones exist or Allow publisher to collect address is enabled if terms use address collection.

  • Required external API features are enabled if external terms depend on them.

  • Identity Management configuration is completed if custom fields are being transferred.

  • Relevant experience types (AMP, Mobile) are enabled if transferring those experience types.

• Identify and plan for assets that require manual recreation in the destination (site licensing terms, Grant Access terms, purchase/upgrade flows, upgrade options, shared subscription settings, custom forms).

• Review RunJS and custom code for hard-coded environment references:\n

  • templateId, variantId, term IDs, schedule IDs

  • Sandbox/stage URLs, asset paths, analytics configuration

What Should I Verify After a Transfer?

After the transfer is complete, perform the following validation steps:

1. Open and preview each migrated experience in the destination application.

2. Confirm the experience status is correct (typically Offline for Production until you are ready to launch).

3. If experiences were updated (not newly created), confirm the new version is present and activate it when ready.

4. Validate dependencies:\n

   • Offer cards resolve correctly.

   • Terms and schedules appear and have correct currency and payment provider support.

   • Template variants are present and referenced correctly.

   • Newsletter sign-up and push signup cards reference the correct lists in the destination.

5. Update environment-specific references:\n

   • Replace any hard-coded templateId or variantId values in RunJS.

   • Update any sandbox/stage domains, resource URLs, or paths.

   • Update term and schedule references if IDs differ between environments.

6. Run end-to-end QA:\n

   • Use test cards or $0 plans where appropriate.

   • Verify checkout, entitlement/access granting, and email notifications.

How Long Does the Process Take?

The timeline depends on the complexity of the transfer:

• Allow at least 2 business days for Piano Support to schedule and perform the transfer.

• Complex transfers involving many assets or dependencies may require additional coordination time.

• The actual transfer execution takes seconds to a few minutes depending on the number of items.

• Additional changes after the initial transfer typically require a new transfer window.

Best Practices

• Always migrate to Production as Offline first. Complete QA, then activate.

• Keep a migration tracking spreadsheet listing what was transferred, including new IDs in the destination where applicable.

• Avoid hard-coding environment-specific IDs in RunJS. Prefer dynamic lookup patterns where possible.

• Ensure destination provider configuration (payment provider, user provider) is ready before transferring monetization assets.

• For templates only, consider using the self-service export/import feature to save time and avoid a support request.

• When transferring to multiple destination applications, include all target AIDs in a single request so they can be processed together.

• Provide a detailed list of items to transfer in your support request, this significantly speeds up the process and reduces the chance of missing dependencies.

Last updated: June 25, 2026