Skip to main content
Getting Started

Migrating to Moonbase

If you have an existing solution for selling your software, there are multiple ways to import your customer data into Moonbase to make sure you have a smooth transition

Written By Tobias Lønnerød Madsen

When existing businesses want to migrate to Moonbase, it’s often best to import existing customer data, so customers are able to log in and access their existing licenses, but also so you can take advantage of the unique pricing techniques Moonbase has to offer. Both targeted discounts and partial bundle purchases rely on Moonbase knowing what your customers already own, to unlock relevant upgrade-pricing.

When thinking about migrating data, there are primarily four things we want to import:

  1. Customers: The information on the customer accounts, so they can log in as before

  2. Licenses: The actual licenses owned by customers, which also dictate product ownership

  3. Trials (through the API only): Less important, but nice if you want to use the built-in customer segmentation, or prevent duplicate trials based on device signatures after the migration

  4. Orders: Your past purchases, so your sales history and analytics carry over. Imported orders send no emails, never reach a payout and can’t be refunded.

The different ways to import customer data

We generally see three approaches when business migrate to Moonbase:

  1. Use our import tool

  2. Use voucher codes

  3. Use our import APIs

If any of these seem challenging for your setup, we’d love to know! We offer some support for businesses migrating to Moonbase based on your size. Reach out to us at support@moonbase.sh.

Using our import tool

To make migrations as simple as possible, we offer built-in imports from CSV data sources in the Moonbase app. Account settings > Migration has all three imports (Customers, Licenses, Orders). Each is also on its own page: Import customers at the bottom of the customer groups list on Customers, Import licenses at the bottom of the product list on Licenses, and Import on Sales. On a smaller screen, the Customers and Licenses imports are the Import button above the list; on a phone, use Account settings > Migration.

The Customers page sidebar and customer groups list, with an arrow pointing to Import customers at the bottom of the list.

The first step of the import is to upload a CSV with the columns of data you want to import. Customers, licenses and orders each have their own columns; only a few are required. For customers, the first step also has Create customer accounts: turn it off to import a mailing list, where each row becomes a newsletter contact without an account and nobody is emailed. You’ll see the expected format during this first step, and a list of all columns we support. If your column names don’t match exactly, that’s fine, you can adjust it on the next step:

Step 1 of Import Customers: the Create customer accounts switch, the CSV upload area and the expected CSV format with its column reference.

You’ll get to preview the mapped data before starting the import, and you’ll also get the chance to handle any potential validation issues:

Step 3 of Import Customers: ten valid rows with email, name, external ID and address columns, and the Start Import button.

Once an import is started, it will run until it’s done importing all data. No emails will be sent to customers through this import, even if they may now have accounts to log in to. You can leave the page while it runs: progress shows in the sidebar (in the menu on a phone or tablet). Once done, the results list every row as Imported, Updated, Unchanged or Error, with Download results:

Import Results for a customer import: nine rows imported and one updated, with a Download results button.

A customer row whose email matches an existing customer fills in that customer rather than creating a duplicate, so you can re-import to fill gaps. Every license row creates a new license, so leave already imported licenses out of the next file.

Using voucher codes for migrations

While not ideal for a seamless transition, using Vouchers to migrate your customers to your new Moonbase account is the easiest solution, and fine if you have limited access to data in your existing systems.

How this works is by creating a number of vouchers, and adding codes to these that can be communicated to customers. Often, we use their existing license key codes or order IDs, and communicate that. Customers can then redeem their existing codes on your new website setup, and immediate get the licenses they should have, after creating an account themselves.

This flow requires customer action, but can be done without any technical work.

Using import APIs

For the smoothest transition, we offer endpoints to import all the customer data you need:

  1. Customers: https://moonbase.sh/docs/api/#import-customer

  2. Licenses: https://moonbase.sh/docs/api/#import-license

  3. Trials: https://moonbase.sh/docs/api/#import-trial

  4. Orders: https://moonbase.sh/docs/api/#import-order

  5. Subscriptions: POST /subscriptions/import

Typically, you start importing your customers one by one, first importing the customer profile itself, then all associated licenses and optionally trials. The customer import endpoint gives you the necessary customer ID to use for other endpoints.

While we don’t have any batch endpoints for imports today, the single-import endpoints scale very well, to the point where you can parallelize it on your end, importing customers side-by-side. Keep data import per customer sequential to avoid any concurrency issues while importing. There’s no limit on how many requests run at the same time, only on how many you send. Send your API key in the api-key header, and pace a large import to stay within the per-key rate limit in our API documentation. If a request is refused with 429 Too Many Requests, wait as long as its Retry-After header says, then carry on.

Customer passwords

While you can import passwords for customers if you have them, it’s extremely rare that you have clear-text passwords for your users. To get around this, you have two options:

  1. Communicate to customers that they need to reset their password
    This utilizes the built-in “Forgot password” flow of the Moonbase authentication system on your website. You can optionally add a login hint mentioning this in the Embedded Storefront.

  2. Add a Customer Migration Configuration
    This enables on-the-fly password migrations as customers log in for the first time.

On-the-fly customer & license data migration

This is an advanced feature, and not recommended unless you are well versed in hosting reliable APIs and integrating multiple systems.

Under Account settings > Migration, you can add a Customer migration configuration and a License migration configuration to connect your existing systems. The goal of this is to seamlessly migrate customer accounts, passwords and licenses to Moonbase as they log in, sign up or use their existing apps. A requirement for this is that you build an API that Moonbase can call during authentication flows to discover and authenticate your existing customer accounts and licenses.

The customer migration settings: switched on, with a discovery endpoint, a password validation endpoint and a masked API key.

Learn more about these flows in our articles on Customer migration and License migration.