Skip to content
Log in

Migrate subscriptions from another platform

On this page

Use this process to move active subscribers from another platform into StoreConnect, so each subscription renews on the right date, for the right amount, on a card StoreConnect can charge. There is no subscription importer: you load the records into Salesforce with Data Loader or a similar tool, and the choices below decide whether those records renew correctly.

Choose how migrated customers pay

Decide this first, because it sets Charge Payments and the payment fields on every subscription you import. You can use a different option for different groups of subscribers.

Option Use it when What you import
Keep the customer’s saved card Your StoreConnect payment provider connects to the same gateway account that holds the customers’ saved cards today The gateway’s token for each customer. See Add saved cards to imported subscriptions.
Ask customers to add a card You are changing gateway, or the old platform cannot export tokens No token. See Ask customers to add a card.
Collect payment outside StoreConnect You invoice the customer or take payment through another system No token, with Charge Payments unchecked. StoreConnect creates each renewal order and advances the dates without charging.

A saved card cannot move between gateway accounts through StoreConnect. A token only charges through the gateway account that issued it.

Before you start

  • You have a subscription product in StoreConnect for each plan you are migrating, with the same term and price. See Add a subscription product.
  • Each subscriber exists in Salesforce as a Contact with an Account.
  • Each subscriber who will manage their subscription on your store has a storefront login.
  • Your store has an active payment provider that supports recurring payments and is available on the web channel, unless every subscriber pays outside StoreConnect.
  • You can export each subscriber’s next charge date, price, and term from the old platform.

Plan the cutover from the old platform

Each subscriber’s first StoreConnect charge should be the next charge the old platform would have taken. Before that date arrives, stop the old platform billing the subscriber.

If you are keeping saved cards, cancel the subscriptions on the old platform but leave the customers and their saved cards in the gateway. Deleting a customer at the gateway deletes the card the token points to.

:::warning Do not import the subscriber’s original join date as Next Renewal Date. After each successful charge StoreConnect moves that date forward by one term from the previous value, not from today, so a date years in the past stays due and the customer is charged every day until it catches up. Start Date can be the original join date. :::

Import every subscription with Skip Processing checked. Nothing is charged while you check the import, and you turn billing on once everything is correct.

Import the subscriptions

Import in this order, because each record looks up the one before it: the original orders, then the subscriptions, then the order products that link them.

Create the original orders

Every subscription needs an original order. Each renewal takes the store, price book, shipping method, and billing and shipping addresses from it, and the customer’s account page finds subscriptions through it.

  1. Prepare an import file for the Order object, with one row per subscriber.
  2. Set Account and Bill To Contact to the subscriber. Use the same contact you set on the subscription.
  3. Set Store (s_c__Store_Id__c) to the store the subscriber buys from.
  4. Set Price Book to the price book that holds the subscription products.
  5. Enter the billing and shipping addresses, with the country as the two-letter code (US, NZ). Renewal tax only matches the two-letter code, so a blank country or a full country name renews untaxed. See Subscription renewal orders.
  6. Uncheck Send Confirmation Emails (s_c__Send_Confirmation__c). It is checked by default, and an imported order that matches one of your transactional emails sends the customer that email.
  7. Fill the fields Salesforce requires on every order, such as Order Start Date, and leave Status at Draft. Salesforce does not allow products to be added to an activated order.
  8. In a multicurrency org, set Order Currency to the currency the subscriber pays in.
  9. Import the file.

Create the subscriptions

  1. Prepare an import file for the Subscription object (s_c__Subscription__c), with one row per subscription.
  2. Fill each field as shown in the table below.
  3. Import the file.
Field What to enter
Contact The subscriber. The same contact as Bill To Contact on the original order.
Original Order The order you created for this subscriber.
Product The StoreConnect subscription product. A subscription without one is never renewed.
Type evergreen for a subscription that runs until cancelled, fixed for a set number of payments.
Term Length and Term Unit The billing interval, for example 1 and month.
Term Price The amount charged each term.
Full Price For an evergreen subscription, the same as Term Price. For a fixed-term subscription, the total still to collect.
Start Date The date the subscription began. The original join date is fine.
Next Renewal Date The date the next term starts: the next charge the old platform would have taken.
Next Billing Date Next Renewal Date plus any billing delay. A subscription with this blank is never charged.
Renewal Order Date Only when the product has Renewal Order Days set: Next Renewal Date minus that many days. Otherwise leave it blank.
End Date For a fixed-term subscription, a few days after the final payment is due. For an evergreen subscription, leave it blank.
Skip Processing Checked, until you turn on billing.
Charge Payments Checked only when you also import a Payment Token. It is checked by default, so uncheck it on every other row.
Currency In a multicurrency org, the currency on the original order.

A fixed-term subscription stops charging when the payments recorded against it add up to Full Price. Term Count on the subscription does not limit the number of charges. For a customer who has already made 4 of 10 payments of 50.00, set Term Price to 50.00 and Full Price to 300.00.

For each subscription, StoreConnect looks for a product line on the original order that is linked to it. Without that link, an evergreen renewal is charged but the renewal order has no products on it, and a fixed-term subscription never counts as fully paid.

  1. Prepare an import file for the Order Product object (OrderItem), with one row per subscription.
  2. Set Order to the original order and Product to the subscription product, through the matching price book entry.
  3. Set Quantity to 1, and Unit Price to the Term Price (evergreen) or the Full Price (fixed-term).
  4. Set Subscription (s_c__Subscription_Id__c) to the subscription.
  5. Import the file.

If the link is missing and the customer later pays the original order through a payment link, StoreConnect creates a second, duplicate subscription instead of updating the one you imported.

Add saved cards to imported subscriptions

Use this when your StoreConnect payment provider connects to the gateway account that already holds the customers’ saved cards.

:::warning Payment Token points at a card stored at the gateway. A token copied onto the wrong row charges a different customer’s card. Match each token to the right subscription by the gateway’s customer ID or the subscriber’s email, never by row order. :::

  1. Export each customer’s token from the gateway or the old platform, in the format shown in the table below.
  2. On each subscription, set Payment Provider to the StoreConnect payment provider connected to that gateway account. The provider must be active, belong to the original order’s store, and be available on the web channel.
  3. Set Payment Token to the customer’s token.
  4. Check Charge Payments.
  5. (Optional) Set Payment Source Identifier to the card’s last four digits and Payment Source Expiry to the card’s expiry date, so staff and the customer can see which card is on file. StoreConnect does not use these fields to charge.

These are the providers that support recurring payments, and the token format each one expects:

Payment provider What goes in Payment Token
Stripe The Stripe customer ID and payment method ID, separated by a pipe: cus_PqR8sT2uVw\|pm_1NxYz4AbCdEf. A customer ID on its own also works, but then Stripe chooses which saved card to charge.
Authorize.Net, Authorize.Net ACH The customer profile ID, for example 796759134. StoreConnect picks the matching payment profile from it.
eWAY The TokenCustomerID, for example 918764523110.
NMI, NMI ACH, StoreConnect Pay The customer vault ID.
Square A JSON string holding the customer ID and card ID, with no spaces: {"customer_id":"7WQ0KXC8ZSD90","card_id":"ccof:uIbfJXhXETSP197M3GB"}
Adyen, Adyen ACH The storedPaymentMethodId. Also set Order Reference Number on the original order to the shopperReference the card was stored under, because Adyen only charges a stored card for the shopper it belongs to.
Flywire A JSON string holding the mandate ID and token: {"m":"<mandate ID>","t":"<token>"}
Westpac Online Pay The reuse token.
Zip The account token value, not the token ID.

A token issued to a different gateway account, or to a different provider, is declined when the subscription is charged. The subscription then goes delinquent and is suspended after the final retry. See Manage delinquent subscription payments.

Ask customers to add a card

Use this when you cannot bring saved cards across.

:::warning Never check Charge Payments on a subscription that has no Payment Token. The gateway declines every charge with no card to take it from, and the subscription is suspended after the day 8 retry. :::

  1. Import the subscriptions with Charge Payments unchecked and no Payment Token.
  2. Send each customer the link to their subscription: https://your-store-domain.com/account/subscriptions/<StoreConnect External ID>, substituting your store’s domain and the subscription’s StoreConnect External ID. Salesforce fills that ID when the record is inserted, so you can add it to an email template as a merge field.
  3. Ask the customer to log in and select Update Payment Details. See Manage customer subscriptions.
  4. Run a report of subscriptions where Payment Token is not blank and Charge Payments is unchecked.
  5. Check Charge Payments on each subscription in the report. Saving a card does not check it for you.

A subscription that reaches Next Billing Date before the customer adds a card renews without a charge, and the balance on the renewal order stays outstanding. Collect that amount from the customer and record the payment against the renewal order yourself.

Check the import before billing starts

StoreConnect only validates a subscription on the day it is due, so Validation Status stays blank after an import. Run a report or list view on Subscription for each check below. Each one should return no records.

  • Product, Contact, Original Order, Term Price, or Full Price is blank.
  • Next Billing Date or Next Renewal Date is blank or in the past.
  • Charge Payments is checked and Payment Token or Payment Provider is blank.
  • Contact is different from Bill To Contact on the original order. The customer’s account page lists the subscription under the order’s contact.
  • The original order has a blank Billing Country, or a country longer than two letters.
  • The original order has no order product whose Subscription is this subscription.

For the full list of conditions the daily job checks, see Subscription record requirements.

Turn on billing

  1. Confirm the old platform has stopped billing the subscribers you are about to turn on.
  2. Open a small set of test subscriptions, ideally one on a card your own team owns, with Next Billing Date set to today.
  3. Uncheck Skip Processing on them.
  4. After the next daily run, open each test subscription and confirm Next Billing Date has moved forward one term and Delinquent Date is blank. The order it was charged against has a Payment with Origin SU01 (evergreen) or SU02 (fixed-term).
  5. Uncheck Skip Processing on the remaining subscriptions.

Each subscription now renews on the Next Billing Date: the customer is charged once, a Payment is recorded, and Next Billing Date moves forward one term.

Example

A customer pays 29.00 a month for a coffee subscription on the old platform, which charges their saved Stripe card. Their next charge is due on November 15, 2026. You keep the same Stripe account.

Record Field Value
Order Bill To Contact The customer
Order Store Your store
Order Billing Country US
Order Send Confirmation Emails Unchecked
Subscription Type evergreen
Subscription Term Length and Term Unit 1 and month
Subscription Term Price and Full Price 29.00
Subscription Start Date 2023-04-15 (when they first subscribed)
Subscription Next Renewal Date and Next Billing Date 2026-11-15
Subscription Payment Provider Your Stripe provider
Subscription Payment Token cus_PqR8sT2uVw\|pm_1NxYz4AbCdEf
Subscription Charge Payments Checked
Order Product Subscription The subscription above

You cancel the customer’s subscription on the old platform before November 15, uncheck Skip Processing, and StoreConnect takes the November 15 charge.

Was this article helpful?

Was this article helpful?