Guides

Migrating ecommerce platforms is a big decision. Luckily, thanks to Swell's full-access Backend API, it is something that can be done incrementally and at your own pace. No matter the reason behind your migration, we are happy to assist you in your journey. Before going any further, ensure you have created a Swell store.

👉

What you'll need: a computer, a stable internet connection, and maybe some snacks.

The first step is determining what data you'll be moving across to your new store. In most cases, it will be all objects that can be retrieved in bulk. There are two main ways to obtain your store data: via API or CSV files.

Since many platforms do not offer CSV exports for every data type, we recommend obtaining your data via API when possible. If you have questions regarding your current platform's API usage, see their related documentation for guidance.

Now let's break down the object types you'll be migrating and the optimal order. Incremental migrations can make the process smoother, so don't feel like you need to make the move in one go. Products and customers are the primary items to migrate first since they are related to other things like orders or shipments. With this in mind, we recommend migrating your store's data sets in the order they are introduced within this section:

  1. Products
  2. Customers
  3. Orders
  4. Shipments
  5. Subscriptions

Posting to the Swell migration endpoint can expedite your uploads by allowing you to run multiple queries synchronously. Activate it by setting $migrate: true. When enabled, all entries will be created but will skip validation, events, and webhooks on each entry. Keep in mind that bypassing validation can also result in duplicate entries within your store. Using $migrate will also add an entry to the data object denoting it was migrated with migrate: true.

⚠️

This flag should not be used when migrating subscriptions, as these rely on subsequent events to be created properly.

01
Batch import example
Batch import example
swell.post('/:batch', {
  1: { ... },
  2: { ... },
  3: { url: '/products/{slug}', data: { $migrate: true, "slug": "my-product" }, method: 'PUT' }
});
👉

Depending on volume, we suggest limiting batch imports to no more than 1000 records at a time—as larger batches can take up to a couple of hours to complete and are more prone to interruptions.

Object identifiers in Swell—like a customer or order id—are hexadecimals based on MongoDB's ObjectId. If you're importing data to Swell from a platform or database which uses primary keys that are compatible with this format, you can pass them directly as the id field when creating the equivalent objects in Swell. This keeps your data cleaner and allows you to cross-reference data from your old system.

Alternatively, you can create a custom field containing the id from your previous system if you need to maintain a link to it.

One of Swell's most flexible features, custom fields provide the ability to define additional fields within models to capture data related to your particular needs. If a standard model is missing fields relevant to your usage, you can define custom fields to store that data on our models. These work similarly to Shopify's metafields or content fields in any modern CMS, but they can be defined on the root model alongside our standard fields. For more information on customizing data models, see our data model customization guide.

See the model

Products are the mainstay of any ecommerce store, and they are one of the more straightforward data types to migrate. There are a few concepts that we should address before jumping right in.

Product options can be modeled by defining a product's options or variants fields. Variants are a combination of one or more options, like size or color.

Swell has no technical limit to the number of options or variants per product; however, you should only enable variant generation for options where stock needs to be tracked on each variation— this provides optimum performance and ease of management. See our product modeling guide for additional information relating to product creation.

Swell categories operate similarly to Shopify's collections. We recommended assigning your product categories in bulk via the Swell dashboard once your products have been migrated. Create categories within the Categories sections which can then be assigned in bulk when viewing your Products.

For tracking product inventory, set stock_tracking: true. Then designate the stock_level during migration paired with $migrate: true to transfer stock levels for your products. Each product variant has its own stock count, allowing you to independently track inventory on all variants.

Within Swell, gift cards can either be physical or digital products. When transferring existing gift cards from your current platform, you can maintain their original code and code formats. This is accomplished by posting the code and adjusting the code_pattern if necessary. You can change your store's default code pattern within your Swell dashboard under Settings > Gift cards.

See the model

When moving customers to Swell, their account passwords can be transferred if encrypted with bcrpyt. For instances where customer passwords cannot be obtained or encrypted with bcrypt, your customers will be prompted to reset their account passwords when trying to log in to their accounts post-migration.

Raw credit card vaulting is a native feature within Swell—meaning customer billing tokens are stored on the account level for each user. This tokenization occurs during payment on the Swell-hosted checkout and can then be used for all subsequent purchases. Any credit card information entered into Swell's vault allows for changing payment gateways seamlessly. When migrating existing customers, you can pass these on to the customer records in the API if you have tokenized information from a payment gateway such as Stripe or Braintree.

Tokens and raw credit card information can be transferred into Swell and continue to be used for processing transactions.

👉

If you wish to switch to another payment gateway, you will need the customer’s raw credit card information. This is either obtained by contacting the payment gateway directly or by having customers re-enter their credit card information after the migration.

Adding Stripe tokens to customer accounts:

In this example, we are using the Stripe-specific fields for the payment tokens; however, the generic token fields should work with other payment gateway tokens such as Braintree.

Add stripe token to customer account
POST /accounts/{id}/cards {
  "id": "60424e018c28b57c6c5b302b",
  "token": "card_1J0SQEG77uxvnJDE56oKJMdS",
  "stripe_token": "card_1J0SQEG77uxvnJDE56oKJMdS",
  "stripe_customer": "cus_JdjuUTWMalp6JD"
}

// Token prefix reference:
// `cus_` stripe customer. Stripe determines which card to charge
// `card_` stripe token. Tells Stripe the specific card to charge

01
Create a card token with Swell.js:
const response = await swell.card.createToken({
  number: '4242 4242 4242 4242',
  exp_month: 1,
  exp_year: 2099,
  cvc: 321,
  account_id: '5c15505200c7d14d851e510f',
  billing: {
    address1: '1 Main Dr.',
    zip: 90210
    // Other standard billing fields optional
  }
})

For more information on creating tokens with Swell.js, see our Storefront API reference.

02
Create or update the account's billing information with the backend API:
swell.post(‘/accounts’, { 
   ... account details ..., 
   billing: { card: resultFromCreateToken } 
})

swell.put(`/accounts/${accountId}`, {
	... account details ...
	billing: { card: resultFromCreateToken }
}
Linking imported payment info to customer’s billing method:
swell.post('/:batch', {
  {
  "url": "/accounts/{id}",
  "data": {
    "id": "<account id>",
    "billing": {
      "account_card_id": "<card_id>
    }
  },
  "method": "PUT"
})

See the model

When migrating historical order data, you can set the original date as it was created in another system with the date_created field, which needs to be formatted as ISO 8601. You will need to use migrate flag for this as well. To maintain order number continuity within Swell, you can change the starting order number by navigating to Settings > General within the dashboard. All new orders received in Swell will start at the designated number—allowing order numbers to continue from where they had previously left off without interruption or changes in format.

Products and customers can be added to your orders by referencing the product's Swell id for each within the order. The notes field can also be used on orders to store any additional information that may want to be conserved without the need for creating custom fields.

See the model

A consideration for transferring historical shipment data is that all shipments created within Swell will have their date_created set to the date on which they are uploaded unless specified with their original date. Once products and accounts have been migrated, you can reference their Swell ids for a comprehensive entry. Additionally, you can preserve other historical data within custom fields.

See the model

While Swell supports subscriptions without the need for third-party solutions, they can be tricky to handle in migration. There are many moving parts when looking at migrating your subscriptions. The first would be retrieving your subscriptions data from your current subscription app. You will need to reference your Swell product and account ids when creating your subscriptions in Swell.

⚠️

At this point, you should have migrated over your products, customers, and customer payment information. If not, see the topics above.

To maintain active subscription continuity, you will need to adjust the subscription date_trial_end fields to end on the date for which the subscription should renew. Specifying the trial end date prevents the subscription from starting immediately upon import. For example, a subscription is being migrated, and the customer's subscription renews on the first of the month—four days away, the date_trial_end should be set for four days to align the start date with the subscription's renewal date.

As mentioned previously, we recommend not using the $migrate flag when migrating your subscriptions with—as the script prevents the necessary events from creating a subscription successfully from taking place. To prevent notifications from going out to customers when their subscriptions are moved into Swell, we recommend turning off subscription notifications from within the Swell dashboard. This can be accessed by navigating to your store's Settings > Notifications.

While migration can be a daunting task, you have the option of tackling it in increments—and Swell's flexible data models allow for mapping your data and preserving key data points you may wish to conserve during migration. Though this guide was a general approach meant to serve users across platforms, we also suggest exploring our platform-specific guides for more in-depth migration assistance based on your current platform.

For additional resources relevant to migration from your current platform, choose from the resources below to get your migration underway.

Migrate from Shopify
Learn More