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’s primarily three 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: 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

The different ways to import customer data

We generally see two approaches when business migrate to Moonbase:

1. Use voucher codes

2. 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 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

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. You may run up to 25 requests simultaneously.

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 data migration

As part of your Moonbase account settings, you may add a customer migration configuration to integrate with your existing systems. The goal of this is to seamlessly migrate customer accounts and passwords to Moonbase as they log in or sign up. 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.

Both endpoints configured here will have the API key configured sent in an api-key header in all requests, which should be validated on your API.

Discovery endpoint

To prevent duplicate accounts, you need to provide a GET endpoint, that will take a email query parameter, and responds with either a HTTP 204/404 if no account with that email exists, or if the account exists, responds with a HTTP 200 and a JSON body like:

Example
Expected response body
Copy
{
  "name": "Full customer name",
  "externalId": "Optional ID from your system",
  "address": {
    "countryCode": "NO",
    "streetAddress1": "Slottsplassen 1",
    "streetAddress2": null,
    "locality": null,
    "region": "Oslo",
    "postCode": "0010"
  }
}

The only necessary body parameter is the name , the rest can be omitted if you don’t have it. This endpoint is mainly used to validate that an email is not already associated with an account.

Password validation endpoint

When customers try to sign in the for the time, they will try to use their password. If that password is not yet stored on their Moonbase customer profile, we will try to validate it on your API, and if correct we add it to the account for later sign-ins. For this, you need to provide a POST endpoint, that handles a JSON body with the following payload:

Example
Request body
Copy
{
  "email": "tobias@moonbase.sh",
  "password": "ExamplePassword"
}

Your endpoint should respond with either a HTTP 200 if the password is correct, or a HTTP 401 if it is not correct. Based on this response, Moonbase will handle the rest of the flow, either signing the customer in, or rejecting their attempt.