> ## Documentation Index
> Fetch the complete documentation index at: https://subscriptions-docs.getappfox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating with Matrixify

> Use Matrixify for bulk data preparation, then Appfox for subscription management

This guide shows you how to prepare customer data, order history, tags, and metafields in bulk with Matrixify, then set up subscription plans and recurring billing with Appfox Subscriptions. This two-tool workflow is useful whether you're migrating from another subscription app or setting up subscriptions on an existing Shopify store.

## What each tool handles

**Matrixify** handles bulk data operations:

* Customer imports and exports
* Order history imports
* Bulk tags for customer segmentation
* Product and customer metafields

**Appfox Subscriptions** handles subscription operations:

* Subscription plans and selling plan groups
* Customer portal (pause, skip, swap products)
* Recurring billing and dunning
* White-glove migration from Recharge, Appstle, Seal, and Subscription Plus

<Tip>
  Install [Appfox Subscriptions](https://apps.shopify.com/appfox-subscriptions) from the Shopify App Store before you start.
</Tip>

## Before you start

Make sure you have:

* [ ] Admin access to your Shopify store
* [ ] [Matrixify](https://matrixify.app/) installed from the Shopify App Store
* [ ] Export or inventory of current subscription customers (if migrating from another app)
* [ ] A tagging scheme planned for subscriber segments (examples: `subscriber`, `migrating-to-appfox`)

<Note>
  If you're migrating from Recharge, Appstle, Seal, or Subscription Plus, consider booking [Appfox white-glove migration](/settings/import) after completing bulk data preparation with Matrixify.
</Note>

## Step 1: Import customers in bulk

Matrixify lets you import or export customer data in bulk using Excel or CSV files.

### Why this matters

Subscription plans and the customer portal need accurate customer records with correct email addresses, tags, and shipping addresses.

### How to do it

<Steps>
  <Step title="Export existing customers">
    If you already have customers in Shopify, export them from Matrixify to get the correct column format. Otherwise, download the [Matrixify Customers template](https://matrixify.app/documentation/customers/).
  </Step>

  <Step title="Prepare your customer data">
    Format your customer data with these required columns:

    * **Email** (customer identifier)
    * **First Name** and **Last Name**
    * **Address** columns for shipping
    * **Tags** for segmentation
    * **Tags Command** (set to `MERGE` to add tags without overwriting existing ones)
  </Step>

  <Step title="Import the file">
    In Matrixify, go to **Home**, then **Import**. Upload your Excel or CSV file. Matrixify will detect the sheet as "Customers" based on the column headers.
  </Step>

  <Step title="Run a dry-run first">
    Before importing live data, test with a small batch or use Matrixify's preview to catch any formatting issues.
  </Step>
</Steps>

<Warning>
  Do **not** import or manage the `Active Subscriber` tag with Matrixify. Appfox automatically adds this tag when a subscription is created or resumed, and removes it when paused or cancelled. Use your own migration labels instead (e.g., `migrating-to-appfox`) with the `MERGE` command.
</Warning>

### Matrixify documentation

* [Customers documentation](https://matrixify.app/documentation/customers/)
* [Matrixify tutorials](https://matrixify.app/tutorials)

## Step 2: Import order history (optional)

If you need historical order context for support or reporting, import past orders with Matrixify.

### Why this matters

Order history provides context for customer support and helps with certain migration workflows. However, it's optional — you can skip this step if you don't need historical orders in Shopify.

### How to do it

<Steps>
  <Step title="Prepare your orders file">
    Use the Orders sheet format with columns like:

    * **Name** (order number)
    * **Customer: Email** (links the order to a customer)
    * **Line: Title**, **Line: Quantity**, **Line: Price** (line item details)
    * Products must already exist in your Shopify catalog if you're linking orders to store products
  </Step>

  <Step title="Import orders">
    Upload your Orders file to Matrixify. Set the **Command** column to `NEW` for new orders or `MERGE` to update existing ones.
  </Step>

  <Step title="Check for API limits">
    Note that Shopify API limits apply to what can be written on closed orders. Matrixify follows these limits, so some order fields may be read-only after orders are finalized.
  </Step>
</Steps>

<Note>
  Importing a large number of orders can take time. Use Matrixify's export feature to verify the import completed successfully.
</Note>

### Matrixify documentation

* [Orders documentation](https://matrixify.app/documentation/orders/)
* [Import Shopify Orders in bulk tutorial](https://matrixify.app/tutorials/import-shopify-orders-in-bulk-with-custom-line-items/)

## Step 3: Add tags and metafields for segmentation

Use bulk tags and metafields to power segmentation, Shopify Flow automations, and theme logic for active subscribers.

### Why this matters

Tags and metafields let you:

* Gate content or collections for subscribers only
* Build customer segments for email marketing (Klaviyo, Omnisend, etc.)
* Trigger Shopify Flow automations based on subscriber status
* Display custom content or pricing on your storefront

### How to do it

<Steps>
  <Step title="Plan your tagging scheme">
    Decide what tags you need for your workflows. Examples:

    * `subscriber` — General subscriber tag (your own; not the automatic "Active Subscriber" tag)
    * `migrating-to-appfox` — Temporary migration label
    * `vip-subscriber` — For high-value customers
  </Step>

  <Step title="Use Tags Command: MERGE">
    Always set the **Tags Command** column to `MERGE` when adding migration tags. This appends your tags to any existing ones without overwriting marketing tags or the automatic `Active Subscriber` tag managed by Appfox.
  </Step>

  <Step title="Add tags in bulk">
    Export customers or products from Matrixify, add your tags to the **Tags** column, set **Tags Command** to `MERGE`, and re-import the file.
  </Step>

  <Step title="Import metafields (optional)">
    If you need custom metafields (e.g., subscriber tier, renewal date, custom preferences), add them using the `Metafield: namespace.key [type]` column format. See the [Matrixify metafields guide](https://matrixify.app/tutorials/how-to-manage-shopify-metafields/) for details.
  </Step>
</Steps>

<Warning>
  Do **not** use `REPLACE` for the **Tags Command** unless you intentionally want to delete all existing tags. `REPLACE` will wipe out marketing tags, Shopify Flow tags, and other existing labels.
</Warning>

### Matrixify documentation

* [Bulk manage Product Tags tutorial](https://matrixify.app/tutorials/bulk-update-shopify-tags/)
* [How to manage Metafields](https://matrixify.app/tutorials/how-to-manage-shopify-metafields/)

## Step 4: Install and configure Appfox

Once your bulk data is ready, set up subscription plans and the customer portal in Appfox.

### Create subscription plans

<Steps>
  <Step title="Go to Plans">
    In Appfox Subscriptions, click **Plans**, then **Create Subscription Plan**.
  </Step>

  <Step title="Configure your plan">
    Choose products, set billing frequency (e.g., every 30 days), and configure discounts. You can create multiple plans for different products or billing intervals.
  </Step>

  <Step title="Enable the subscription widget">
    Go to **Storefront** → **Widget** and customize the widget appearance. Then add the **Subscription Widget** app block to your product page in the Shopify theme editor.
  </Step>
</Steps>

See the [Getting started guide](/getting-started) and [Plans documentation](/plans) for full setup instructions.

### Set up the customer portal

The customer portal lets subscribers pause, skip, swap products, and reschedule deliveries without contacting support.

Go to **Storefront** → **Customer Portal** to customize the self-service options. See the [Customer Portal documentation](/storefront/customer-portal) for details.

### Optional: White-glove migration

If you're migrating from Recharge, Appstle, Seal, or Subscription Plus, you can request white-glove migration assistance. This service moves live subscription contracts from your previous app to Appfox, preserving billing schedules and customer payment methods where possible.

Go to **Settings** → **Import & migration** or see the [Import & migration documentation](/settings/import) for details.

## Order of operations

Follow this sequence for best results:

1. **Matrixify: Customers** — Import or update customer records, addresses, and initial tags
2. **Matrixify: Orders (optional)** — Import historical orders if needed for context
3. **Matrixify: Tags & metafields** — Add segmentation tags and custom metafields for subscriber workflows
4. **Appfox: Selling plans** — Create subscription plans and enable the widget on product pages
5. **Appfox: Customer portal** — Configure self-service portal options
6. **Optional: White-glove migration** — Request Appfox migration assistance if moving from Recharge, Appstle, Seal, or Subscription Plus
7. **Validate** — Test that a customer can subscribe, manage their subscription in the portal, and that tags appear correctly in Shopify Admin

<Tip>
  After completing setup, place a test subscription order and verify that the `Active Subscriber` tag is applied automatically. Then pause or cancel the test subscription and confirm the tag is removed.
</Tip>

## Common pitfalls

Avoid these mistakes when migrating with Matrixify:

### Expecting Matrixify to create subscription contracts

**Issue:** Matrixify cannot create Appfox or Shopify subscription contracts directly. It handles bulk Shopify data (customers, orders, tags, metafields) but not subscription-specific objects like selling plans or subscription contracts.

**Solution:** Use Matrixify for data prep, then use Appfox to create and manage subscription plans and recurring billing.

### Using REPLACE for Tags Command

**Issue:** Setting **Tags Command** to `REPLACE` deletes all existing tags and replaces them with only the tags in your import file. This wipes out marketing tags, Shopify Flow tags, and the automatic `Active Subscriber` tag.

**Solution:** Always use `MERGE` to add new tags without overwriting existing ones. Use `REPLACE` only when you intentionally want to reset all tags for a customer or product.

### Importing orders without matching products or customers

**Issue:** If you import orders with line items that reference products or customers that don't exist in Shopify, the import will fail or create incomplete orders.

**Solution:** Import customers first, then import or create products in Shopify, then import orders that reference those customers and products.

### Skipping the dry-run

**Issue:** Importing large files without testing can lead to errors, duplicate data, or unexpected tag behavior.

**Solution:** Always test your import with a small batch first. Use Matrixify's preview and check the **Import Results** file after the import completes to verify success.

### Managing the Active Subscriber tag manually

**Issue:** Importing or editing the `Active Subscriber` tag with Matrixify can cause it to go out of sync with the actual subscription status.

**Solution:** Let Appfox manage the `Active Subscriber` tag automatically. Use your own custom tags (e.g., `migrating-to-appfox`, `vip-subscriber`) for migration labels and segmentation.

## When to contact support

### Matrixify support

For bulk import/export issues, template questions, or dry-run errors, contact Matrixify:

**Email:** [support@matrixify.app](mailto:support@matrixify.app)

### Appfox support

For subscription plans, customer portal setup, white-glove migration, or recurring billing issues, contact Appfox:

**Email:** [support@getappfox.com](mailto:support@getappfox.com)

## Related resources

### Matrixify

* [Matrixify tutorials](https://matrixify.app/tutorials)
* [Customers documentation](https://matrixify.app/documentation/customers/)
* [Orders documentation](https://matrixify.app/documentation/orders/)
* [Bulk manage Product Tags](https://matrixify.app/tutorials/bulk-update-shopify-tags/)
* [How to manage Metafields](https://matrixify.app/tutorials/how-to-manage-shopify-metafields/)

### Appfox Subscriptions

* [Getting started guide](/getting-started)
* [Subscription Plans](/plans)
* [Customer Portal](/storefront/customer-portal)
* [Import & migration](/settings/import)
* [Active Subscriber tag](/active-subscriber-tag)
* [Integrations](/integrations)