Migrating Subscriptions
  • 27 Sep 2022
  • 3 Minutes to read
  • Dark

Migrating Subscriptions

  • Dark

There's no right or wrong way to do this. You can enter Products and Prices in Stripe, Subscription data in Salesforce, Tiers in Stripe, or Payment Gateway Customers in Salesforce; whatever floats your boat. This is our guide on an opinionated way to do it!

Typical entities to manage

  • Salesforce Accounts
  • Salesforce Contacts
  • Stripe Payment Gateway Customers
  • Stripe Charges
  • Stripe Cards & Bank Accounts
  • Stripe Products
  • Stripe Prices
  • Stripe Subscriptions

Salesforce and Stripe have records that relate to each other, so it's important to migrate records in the order in which one entity requires the other. For instance, you can't create a Stripe Subscription without a Stripe Payment Gateway Customer.


  1. Backup your data.

  2. Setup Webhooks. This creates a data mirror between Salesforce and Stripe.

Migrating from outside of Stripe to using Stripe

  1. Set the Data Loader batch size to "1" (each insert will fire an outbound Stripe REST callout and a few triggers will fire).
  2. Export your Salesforce Accounts to a CSV file.
  3. In the Account CSV file, add the columns "Email" and "Description". Keep the ID (Account ID) column and the Account Name. Delete the other columns.
  4. Now it's time to create Stripe Payment Gateway Customers. With Data Loader, insert Payment Gateway Customer records. Map the ID field to the Account ID, Email should be the primary email used to either identify this Account (your main contact) or the main billing contact, and the Description should be either the Account Name, Contact Name, or something like "Account - Contact" such as "Matrix - Morpheus Neo".
  5. With the success file, you can now go in a few directions. You can next migrate Payment Methods if you have raw card data or you can migrate Products and Prices next.
  6. If Payment Methods, prepare a file with the correct Record Type (Charge Card vs ACH), Account and Contact IDs, the Stripe Payment Gateway Customer Salesforce record ID, and the respective raw card ID data.
  7. Products. If you want to go right into migrating Subscriptions, Stripe Subscriptions require three things: a [Stripe] Payment Gateway Customer, at least one Product, and its associated Price. They may also include a Coupon (discount code). Prices may contain Tiers. So first, you want to migrate Products. Products can start in either Salesforce that push to Stripe, or in Stripe that then push to Salesforce. Product sync 1:1 between Salesforce and Stripe.
  8. Prices. Prices are similar to Price Book Entries in Salesforce, but they have a lot more data, such as the frequency (interval) of the billing. You can enter these in Salesforce or Stripe once you have your Products entered.
  9. OPTIONAL Tiers. If you have tiered-based pricing, you can create Tier records related to your Prices in either Stripe or Salesforce.
  10. Subscriptions. If you have one Product & Price per Subscription, you only need 1 CSV to migrate these into Salesforce. If you have multiple Products & Prices per Subscription, you'll need 2 (parent/child relationship). Stripe has a shortcut when you only have 1 Product & Price per Subscription. Your first CSV needs: Account ID, 13. (Stripe) Payment Gateway Customer ID, and applicable Subscription field values to see (see our Subscriptions & Subscription Items documentation for details. Your second CSV needs: Quantity, Price, and other Subscription Item fields as applicable.
  11. (Stripe) Payment Gateway Customers push to Stripe automatically. Products, Prices, and Subscriptions each have Push to Stripe checkbox fields you can set either on import or update once you're confident the data migrated correctly. This will trigger the push to Stripe. If you're creating these records in Stripe, they'll appear in Salesforce via Webhooks every 5 minutes as part of our batch.

Currently using Stripe and want to use Blackthorn Payments with Stripe Billing

  1. Go to the Payment Gateway tab, click on your Payment Gateway. Click Sync with Stripe.
  2. Make sure you have Account and Contact records in your Salesforce org that align with your Stripe records. We attempt to match Stripe Payment Gateway Customer emails against Contact emails to set lookups.
  3. Click each button from left to right, one at a time, waiting for the process to finish as viewed in Setup | Apex Jobs. Start with Payment Gateway Customers.