Everything you need to do to transition to live when you've set up Paddle in sandbox.
Ready to start selling with Paddle? This guide walks through all the steps that you need to move from sandbox to live. By the end, you'll be ready to take your first real payment.
Going live involves swapping API keys in your existing integration, as well as re-creating some data in your live account from sandbox. It's a good chance to review entities that you created to make sure you're only porting across good data.
The steps in this guide apply to your live account. It assumes that you've set up and tested Paddle in your sandbox account. We walk through setting up sandbox in our setup checklist.
Port over key settings like your balance currency, whether prices include tax, and payment methods you support from your sandbox account.
Create subscription plans, recurring addons, one-off charges, and other items that you sell in your live account.
Make some changes to your sandbox integration so that it points to your live account.
Create new notification destinations to get notified when events happen in your live account, and handle signature verification.
When you're live, sign up for updates about new features or changes to the Paddle API and developer tools.
Configure key settings for your live account. You set most of these in your sandbox account when testing, so mirror these settings in your live account.
Set default payment link
Set up payment methods
Choose the payment methods you'd like to use with Paddle Checkout. You can turn on payment methods in a couple of clicks — no need to sign up for merchant or partner accounts.
Go to Paddle > Checkout > Checkout settings, expand Payment methods, then check the payment methods you'd like to offer.
Card is always on for checkout, and wire transfer is always on for invoices.
Learn more: Payment methods
Set sales tax settings
Choose whether prices should be inclusive or exclusive of taxes by default. Typically, prices are exclusive of tax when selling to businesses and in regions with sales taxes.
Go to Paddle > Checkout > Sales tax settings to set your sales tax setting.
Set balance currency
Choose the currency that you want to hold earnings in. Paddle automatically converts payments in other currencies to your balance currency, ready for payout.
Go to Paddle > Business account > Currencies to set your balance currency.
We recommend choosing a currency that matches your bank account.
Set dunning and recovery settings
Paddle integrates with Retain to handle dunning and payment recovery. Retain automatically retries failed payments, sends reminders, and gives customers frictionless ways to retry payment.
Go to Paddle > Retain to set dunning and recovery settings.
Learn more: ProfitWell Retain by Paddle
Provide payout details
Paddle initiates payouts on the 1st of each month when your balance meets the minimum threshold. You can get paid by Paddle by wire transfer, PayPal, or Payoneer.
Go to Paddle > Business account > Payouts > Payout settings to enter your payout details and set your minimum threshold.
Learn more: How and when do I get paid?
Your product catalog contains the items that you sell to your customers. This includes subscription plans, recurring addons, and one-off items.
To start selling, re-create your sandbox product catalog in your live account. You should only create products that you plan to sell. We don't recommend copying test products to your live account.
Create products and prices
Products describe the items that you sell. They have related prices that describe how you charge for them. Add products and prices to Paddle for your subscription plans, recurring addons, and one-off items.
Go to Paddle > Catalog > Products to start adding products and prices.
Learn more: Create products and prices
Discounts let you reduce the amount a customer has to pay by a percentage or fixed amount. They can be one-time or recurring, and apply to an entire transaction or just items that you choose.
Go to Paddle > Catalog > Discounts to start adding discounts.
Learn more: Create products and prices
Request approval for taxable categories
Taxable categories determine what kinds of items you're able to sell with Paddle. They make sure that you charge the correct amount of tax for your products. Standard Digital Goods is available by default, but you should request approval for other taxable categories if you require them.
Go to Paddle > Catalog > Taxable categories to request approval for other taxable categories.
Update your integration with Paddle so that it points to your live account rather than your sandbox account.
Update base URLs for API endpoints
The Paddle API has different base URLs for sandbox and live accounts. Update your base URLs so Paddle knows which environment you're working with.
api.paddle.comin API endpoint URLs.
Generate live API keys and swap them
API keys are separate for your sandbox and live accounts. Generate new API keys for your live account, then swap sandbox keys for live ones in your code.
Go to Paddle > Developer tools > Authentication to generate API keys.
Send a request to the
/event-typesendpoint to test your authentication.
Learn more: Authentication
Update client-side tokens in your frontend
Client-side tokens are separate for your sandbox and live accounts. You use a client-side token when including and initializing Paddle.js. Generate a new client-side token and replace in your frontend.
Go to Paddle > Developer tools > Authentication to generate a new client-side token.
Swap the value for the
tokenparameter passed to
Paddle.Setup()in your frontend.
Learn more: Include Paddle.js
Paddle.js integrates with Retain, so you don't have to include a separate Retain script. Client-side tokens for live accounts authenticate with both Paddle Billing and Paddle Retain, too. When transitioning to live, make sure you pass the
Paddle.Setup()when including Paddle.js so that Retain works correctly.
Paddle.Setup()calls to include
pwCustomer, passing either the Paddle ID or email address of a customer.
Learn more: Initialize Paddle.js and Retain
Remove sandbox environment setting in your frontend
Sandbox integrations use the
Paddle.Environment.set()method to tell Paddle.js that you're working with a sandbox account. Remove this so Paddle.js defaults to the live environment.
Paddle.Environment.set("sandbox")from your frontend code.
Learn more: Paddle.Environment.set()
Swap Paddle IDs in your frontend
As your sandbox and live accounts are separate, your products, prices, discounts, and other entities in Paddle have different Paddle IDs. Price and discount IDs are used with Paddle.js to open or update items on a checkout. Replace sandbox Paddle IDs with live Paddle IDs.
Replace price and discount IDs in your integration with price and discount IDs for the newly created entities in your live account.
Swap Paddle IDs in subscription lifecycle logic
You may have used Paddle IDs for price, discount, or entities in your sandbox in logic that handles subscription lifecycle events like upgrades or downgrades. Replace sandbox Paddle IDs with live Paddle IDs.
Notifications let you get notified when key events happen in Paddle. They can be delivered as webhooks or emails. You'll typically use webhooks to keep your app in sync with Paddle.
To receive webhooks for live events, create new notification destinations in your live account. We recommend using separate webhook destination URLs for your sandbox and live accounts.
Create notification destinations
Create notification destinations to tell Paddle where to deliver webhook notifications and which events you'd like to receive notifications for.
Go to Paddle Developer tools > Notifications to create notification destinations.
Learn more: Work with notification destinations
Allowlist Paddle IP addresses
Paddle sends webhooks from different IP addresses for sandbox and live environments. For security, we recommend that you allowlist Paddle IP addresses and reject responses from others.
Allowlist Paddle IP addresses on your webhook server.
Learn more: Webhooks
Verify webhook signatures
All webhooks sent by Paddle include a signature that you can use to check that they were genuinely sent by Paddle. We recommend that you verify webhook signatures to make sure that they weren't tampered with in-transit.
Build logic to handle webhook signature verification.
Learn more: Verify webhook signatures
Once you've completed the steps above, you're live — congratulations! We recommend keeping up-to-date with changes to the Paddle platform.
Sign up for developer changelog updates
We document all changes to our API and developer tools on our developer changelog. We recommend all developers check our changelog regularly or sign up for emails to get updates about new features and changes.
Check our developer changelog and use the email form to sign up for updates.
Learn more: Developer changelog
Sign up for Paddle status page updates
We post details of any incidents impacting the Paddle platform in real-time on our status page. We recommend subscribing to updates by email, webhook, RSS, or Slack.
Check our status page and use the subscribe button to sign up for updates.
Learn more: Paddle status
Refresh API keys regularly
Your API keys grant access to the data in your Paddle system. It's good practice to refresh your API keys periodically and revoke keys that you're no longer using.
Go to Paddle > Developer tools > Authentication to generate API keys. Swap API keys for your new keys, then revoke old keys.
Learn more: Authentication