Substack

Welcome to Buttondown! After you've read through our "Getting Started" guide, we're here to help you with your next step: transferring your subscribers from your old email platform to Buttondown.

To export your subscriber data, navigate to the “Subscribers” tab of your Substack dashboard. Then, scroll down to “All subscribers,” and click Export to generate a CSV file of all your subscribers.

This video shows the "Export" option in the Substack dashboard.

What’s a CSV file, you may ask? As a quick refresher, CSV files consist of “comma-separated values.” Your CSV file from Substack should look a little something like this:

Buttondown can use the CSV from Substack to automatically import the following values for each of your subscribers:

• Their email
• The date they joined your newsletter
• Any assigned tags, which you can use to group your subscribers or send tailored content
• Any assigned metadata, such as your subscriber’s name, location, or other structured-key values
• Any free-form notes you may have jotted down for your personal reference

Other than your subscriber’s email, all the above values are completely optional, and don’t have to be included in your CSV file. Note that you can also add details like tags, metadata, and notes to subscribers after they’ve been imported to Buttondown.

If you’d like to add more information (including tags, metadata, or notes) to your CSV file, here are a few tips for formatting it:

• You don’t need to include a header row unless it’s for your own reference. If you do choose to include a header row, feel free to format it however you like.
• Any dates should follow the “Day/Month/Year” format.
• If you have multiple tags for a given subscriber, we recommend adding them all in the same column and separating each tag with a comma, like so: “Sports, Politics”
• If you have multiple instances of metadata for a given subscriber, it’s best to add them in separate columns rather than lumping them all into the same column.
• Last but not least, you can format your subscriber notes however you like. If you don’t have any notes, that’s completely fine too!

After you’re happy with the contents of your CSV file, you can import it to Buttondown. Here's how:

1. Navigate to the “Subscribers” tab of your Buttondown dashboard.
2. Click Import. A pop-up window appears.
3. Drag your CSV file over to the pop-up window,
4. Follow the prompts that appear. These prompts ask you to pick the values you’d like to assign as tags, metadata, notes, and more.
5. Click Done.

This video shows the process of importing a CSV and assigning values.

It can take anywhere from a few seconds to a few hours for Buttondown to import all of your data, depending on the number of subscribers you’re adding. In some cases, if you’re importing a large quantity of new subscribers, we may temporarily deactivate your account to make sure everything is working correctly.

After your import completes, you’ll receive a notification from Buttondown, and will be able to view your subscriber data in the “Subscribers” tab of your dashboard. You’ll also see your data reflected in the “Tags” tab.

Here's how to generate an export of your Substack data and upload it to Buttondown:

1. Navigate to the “Settings” tab of your Substack dashboard, and scroll to the “Exports” section.
2. Click Create new export. This generates a ZIP file filled with your posts, subscriber list, and other related information.
3. Navigate to the “Emails” tab of your Buttondown dashboard.
4. Click Import and select “Substack” from the pop-up menu.
5. Drag your ZIP file to the pop-up window to begin the upload.

This video shows the process of exporting data from Substack and importing it to Buttondown.

Your data import should only take a few moments to complete. Your past Substack posts should now appear in the “Emails” tab of your Buttondown dashboard. Buttondown will automatically parse your ZIP file to mark each email as either free or paid.

Here's how to import your paid Substack subscriptions to Buttondown.

Substack and Buttondown use the same payment processor: Stripe. Because you're not changing your payment processor, your subscribers won't have to re-enter their credit card information or re-confirm their subscriptions.

In addition to a Stripe account, you'll also need a paid Buttondown account to manage your paid subscriptions. After you set that up, scroll down to the “Features” section in your Buttondown settings, and click the “Connect to Stripe” button. From there, follow the prompts to connect to your existing Stripe account. Be sure to use the same email and login as you do for Substack, because Stripe needs to access previous account information and payments in order to ensure that subscribers are mapped over gracefully.

This video shows the process of enabling Stripe payments in Buttondown.

For further help with setting up your account, reviewing your tax settings, or customizing your payment methods, read our dedicated Stripe integration guide.

After you've completed the procedure above, we advise you to use your Stripe dashboard to disconnect your Substack account. Don't use your Substack dashboard. If you disconnect your account from your Substack dashboard, you run the risk of canceling and refunding your existing subscriptions, which means you won’t be able to transfer them over to Buttondown. To avoid this, and to make sure each and every one of your paid subscriptions transfers over, initiate any connection changes from Stripe.

Disconnect your Substack account under “Installed apps” in the “Business settings” section of your Stripe dashboard.

This video shows how to locate the "Installed apps" section of your Stripe account.

Alternatively, you can submit a request to Substack to disconnect Stripe without canceling your subscriptions.

After you have connected your Stripe account to your newsletter, Buttondown will honor your existing Substack subscriptions. You’ll also have the option to add paid subscription plans in your Buttondown settings, which will apply to new subscribers.

Here's how:

1. Navigate to the “Paid Subscriptions” section, and click the toggle to Enable paid subscriptions.
2. Click Add Plan. A pop-up appears that prompts you to choose your subscription style, price, currency, and cadence (billing cycle).
3. Configure the pop-up as you wish and click Save.

You also have the option to add a “Pay what you want” subscription plan. When you migrate from Substack, Buttondown maintains the existing price for each subscriber’s subscription. If a subscriber wants to change their subscription amount, we recommend that they unsubscribe and then resubscribe with a different amount.

This video shows how to enable a "Pay what you want" plan option.

You’ve done it! Your subscriber, archive, and paid subscription data have been moved over to Buttondown.

There’s just one last thing to check before you’re free to delete your Substack account: Your newsletter images. Buttondown automatically replaces the images that are hosted on Substack’s CDN with ones that are hosted on Buttondown’s infrastructure so that your images won’t disappear. However, this replacement process can take some time. Check to confirm that all the images from your Substack posts appear in your newsletter archives.

After you’ve double checked that all of your images have been replaced, feel free to sign off of Substack.

If you have a question about importing your data, the Buttondown team is here to help.

Yes! "Comped" subscriptions technically don't exist in Stripe, but Buttondown detects them from your export and automatically maps them over to your Buttondown account. (Our parlance is a little bit different; we refer to them as gift subscriptions.)

No! Buttondown can import as many plans and subscription types as you have in your Stripe account, including historical plans or one-off subscriptions that you've created.

No! Buttondown can import as many archives and posts as you have in your Substack account. In addition, we:

• pull in your draft posts (if you have any)
• respect any paywalled posts you have in your Substack account and mark them as "premium"

If you’ve already disconnected your Substack account from Stripe, and you’re still seeing Substack take a 10% cut of your revenue, we recommend reaching out to Substack’s support team. They'll be able to programmatically remove the 10% cut from your revenue.

(We also have an ad-hoc script we can run to remove the application fees from your Substack subscriptions, but please reach out to Substack first to see if they can help resolve this issue for you.)

If you're using a custom domain on Substack, your archived URLs look something like this:

newsletter.sarah.com/p/hello-world

It's very important for SEO (and just for good internet hygiene) to make sure that those URLs continue to work!

By default, Buttondown's archived URLs have a slightly different format:

newsletter.sarah.com/archive/hello-world

But, for emails migrated in from Substack, we automatically redirect your old URLs to the new Buttondown URL format, so that all of your links continue to work. (No need to do anything additional on your end!)

After you've migrated your Substack account to Buttondown and handled any other necessary tasks, you can safely delete your Substack account.

However, you may want to keep that account around, if the following things apply to you:

1. You were not using a custom domain on Substack (and your account lives on a subdomain like sarah.substack.com)
2. You want to make sure links from other blogs or websites to your Substack account continue to work, so as to collect subscribers from those links

If that applies to you, we recommend the following options:

1. Keep your Substack account around, and use it to collect any lingering subscribers.
2. Delete all posts from your Substack account. This ensures that Google and other search engines don't penalize you from having the same posts on your Substack account and Buttondown account.
3. Set up a recurring reminder to periodically migrate any new subscribers from your Substack account to Buttondown.