Migrate to Swell

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.

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:

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.

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

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.

await swell.post('/products', {
  name: 'Giant Trampoline',
  price: 399,
  old_system_id: '1459175177', // Custom field
  imported_at: '2021-10-10T14:48:00' // Custom field
});

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.

//Must use $migrate: true when setting stock

await swell.post('/products', {
  $migrate: true,
  name: 'Giant Trampoline',
  stock_tracking: true,
  stock_level: 10
});

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.

await swell.post('/giftcards', {
  amount: 100,
  code: 'C9X9L7D9Q3MAXC3P',
  code_pattern: 'XXXX XXXX XXXX XXXX'
});

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.

POST /accounts/{id}/cards {
  "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.

POST /accounts/{id}/cards {
  "token": "pm_1J0SQEG77uxvnJDE56oKJMdS",
  "stripe_token": "pm_1J0SQEG77uxvnJDE56oKJMdS",
  "stripe_customer": "cus_JdjuUTWMalp6JD"
}

// Token prefix reference:
// `pm_` payment method token. Tells Stripe which payment method to charge.

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.

await swell.post('/orders', {
  $migrate: true, //Skips validation, and allows overrides 
  date_created: "2021-07-16T14:36:00.253Z", //Format as ISO 8601
  number: 10023,
  items: [{...}],
  billing: {...},
  shipping: {...},
  payment_marked: true, //If paid
  paid: true, //If paid
  payment_amount: 10,
  payment_balance: 0, //Negative numbers mean a balance is owed
  status: 'complete', //Order has been fulfilled
  delivery_marked: true,
  account_id: "5a9ea7ba3f95740a914267f2",
});

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.

await swell.post('shipments', {
  order_id: "5a9ea7ba3f95740a914267f1",
  items: [
    {
      order_item_id: '5a9ea7ba3f95740a914267f2', //found in order items[i].id
      product_id: '5cad15bc9b14d1990724663a', //Product id as found in Swell
      quantity: 2, //Quantity fulfilled in shipment
    }
  ],
    tracking_code: 'T192000000XYZ',
  });

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.

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.

swell.post('/:batch', {
  "url": "/subscriptions",
  "data": {
    ... subscription data ...
  },
  "method": "POST"
})

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.