Buttondown Documentation
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:
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:
Sports
, Politics
”After you’re happy with the contents of your CSV file, you can import it to Buttondown. Here's how:
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:
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:
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:
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:
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:
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:
sarah.substack.com
)If that applies to you, we recommend the following options: