Become a Paddle partner
Join the Paddle partner program to read this content. You'll also get access to our partner API and agent tooling. Let us know a few details about your business to get started. Already a partner? Log in to view this page.
Paddle is an all-in-one payments and billing merchant of record for modern SaaS, mobile app, AI, and digital product companies. It supports checkout, subscriptions, global tax compliance, metrics, fraud protection, and retention tooling.
With an embedded billing integration, you can offer payments as a native feature of your platform without the complexity of managing payments, taxes, subscription billing compliance, and buyer support.
This guide walks through core Paddle platform concepts, so you can understand how Paddle works when integrating embedded billing.
The merchant of record model
With a traditional payments integration, a payment service provider (PSP) gives you the technical infrastructure to process payments. You have to build and maintain a payments stack around your PSP, both technical and financial.
In practice, this means spending your time optimizing payments, integrating local payment methods, handling tax and subscription billing compliance, building fraud prevention mechanisms, and dealing with buyer support and chargebacks.
The merchant of record (MoR) is different. An MoR like Paddle is the legal entity responsible for selling goods or services to an end customer. We manage payments and take on the associated liabilities.
It's ideal for platforms, since it means you can offer payments as a native feature of your platform without becoming a payments company yourself. Paddle handles the hard parts of selling online for both you and your users.
From you and your user's perspective:
- You don't register for VAT, GST, or sales tax in the countries where you operate.
- You don't carry chargeback or PCI scope.
- You don't operate a buyer support function for billing issues.
- You don't need local entities to accept local payment methods.
From a customer's perspective:
- Customers go through a modern checkout experience, with Apple Pay, Google Pay, PayPal, cards, and local payment methods.
- Checkout appears branded or fully embedded as part of your user's app or website.
- Paddle handles the transaction, including collecting sales tax and handling refunds and chargebacks.
- Your user's name appears on the customer's statement alongside Paddle's.
Understand what Paddle is and how it helps sellers.
Learn about the features in Paddle for SaaS businesses.
Open the Paddle merchant of record reference site.
Product catalog
In Paddle, products and prices are flexible entities you compose into the structure you need. Products describe what you sell, and related prices describe how you sell a product.
This means you can build any pricing structure you need, from flat, good-better-best, per-seat, usage-based, and feature based pricing.
- Recurring plans with any billing period, optional trials, and multiple items on a subscription.
- Good-better-best, like Starter, Pro, Enterprise, by creating one product per tier.
- Per-seat billing by adding seats as a quantity on a price item.
- Add-ons on top of a base plan, billed on the same cycle or a different one.
- Usage-based charges for metered features, billed via custom items on the next invoice.
- Plan changes with proration calculated to the minute, and your choice of whether to bill now, on the next renewal, or skip billing.
- One-time charges alongside subscriptions for things like activation fees, overage, or single purchases.
A typical three-tier pricing structure
As an example, a good-better-best pricing plan with monthly and annual options might look something like this:
| Starter | Pro | Enterprise | |
|---|---|---|---|
| Monthly | $10.00 | $30.00 | $300.00 |
| Annual | $100.00 | $300.00 | $3000.00 |
In Paddle, you can model this as three products with two prices each:
graph LR Starter["Product: Starter"] Pro["Product: Pro"] Enterprise["Product: Enterprise"] Starter_Monthly["Price: Starter (monthly)"] Starter_Yearly["Price: Starter (yearly)"] Pro_Monthly["Price: Pro (monthly)"] Pro_Yearly["Price: Pro (yearly)"] Enterprise_Monthly["Price: Enterprise (monthly)"] Enterprise_Yearly["Price: Enterprise (yearly)"] Starter --> Starter_Monthly Starter --> Starter_Yearly Pro --> Pro_Monthly Pro --> Pro_Yearly Enterprise --> Enterprise_Monthly Enterprise --> Enterprise_Yearly
Model and build your catalog to start billing.
Improve conversion rates by localizing prices.
Transactions and subscriptions
Transactions and subscriptions are the core billing entities in Paddle:
- When a transaction (checkout or invoice) is completed, Paddle creates a related subscription.
- When a subscription renews, Paddle creates a new transaction to collect payment for it.
- Upgrades, one-time charges, and other changes to a subscription create transactions, too.
The entire subscription lifecycle can be understood in terms of these two entities, meaning it's easy to determine the state of a subscription at any given time.
flowchart LR
checkout["Checkout / invoice"] --> txn["Transaction<br>captures payment"]
txn -->|completed| sub["Subscription<br>recurring mandate"]
sub -->|"renewal ยท upgrade ยท<br>one-time charge"| txn
Transactions calculate and capture revenue.
Subscriptions are a mandate for recurring billing.
The subscription lifecycle
The subscription billing engine in Paddle handles the complete subscription lifecycle, including signup, renewal, upgrade and downgrade, pause, and cancellation.
flowchart LR
S[sign up] --> A[trialing]
A --> B[active]
B <--> C[past_due]
B --> D[paused]
D --> B
B --> E[canceled]
C --> E
Order fulfillment and provisioning
When a customer makes a purchase, they need to get what they paid for. Provisioning is how you grant customers access to your app, as well as determine which features they should have access to.
To handle provisioning, you can listen for webhooks for the subscription lifecycle and update your database accordingly. Paddle includes over 50 webhooks, but a basic billing workflow involves listening to just two:
| Event | Purpose |
|---|---|
subscription.created | A new subscription exists. Save the customer and subscription IDs against your user, and grant access. |
subscription.updated | Something about the subscription has changed, like its status, items, scheduled changes, or billing period. Re-read the cached fields you store. |
Here's how fulfilling an order and granting access typically works:
sequenceDiagram
participant C as Customer
participant App as Seller's app
participant PD as Paddle
participant BE as Seller's backend
C->>App: Buy a plan
App->>PD: Open checkout (Paddle.js)
C->>PD: Pay
PD-->>BE: subscription.created
BE->>BE: Store IDs, grant access
PD-->>BE: subscription.updated
BE->>BE: Update access to match
App<<->>BE: Check subscription state
C->>App: Use unlocked features
Use webhooks to keep your app in sync with Paddle, then decide what access to grant.
Understand the Paddle event model and how to work with webhooks.
Subscription management
Customers expect to manage their own subscription without filing a support ticket. The customer portal gives customers a hosted page where they can:
- Update payment methods.
- View past invoices and download receipts.
- Cancel, with a cancellation flow that surfaces offers before the customer leaves.
You can link to the portal directly from your app, or generate per-customer authenticated sessions for a more seamless handoff.
For a completely custom experience, you can build your own billing management screens in your app using the API or SDKs. Everything the portal offers is available for developers, too.
Let customers see and manage their own subscriptions.
Add customer portal links to your app to hand off core billing workflows to Paddle.
Balance and payouts
As a seller on Paddle, you have an account balance. When a customer makes a purchase, Paddle adds the earnings on the purchase to your account balance.
Earnings are the total amount set to be paid out to you as the seller after the Paddle fee has been taken. You can see the fees taken for each transaction against the transaction itself in the dashboard and using the API.
When your account balance hits your payout threshold, Paddle initiates a monthly payout.
| Date | Webhook | Description |
|---|---|---|
| 1st of the month | payout.created | Your account balance is converted to a payout. The amount being paid out is removed from your balance. |
| 2nd to 15th of the month | payout.paid | Paddle sends your payout to your bank account. You should receive the amount within three working days, depending on your bank. |
Currency conversion and FX
Customers can pay in over 30 currencies. When customers pay in a currency that's different to your balance currency, Paddle automatically converts your earnings into your balance currency.
You can choose the currency that your account balance is held in, as well as the currency you want to be paid in. If you hold your account balance in a different currency to payout currency, Paddle converts your balance currency into your payout currency.
We recommend choosing the same payout currency as your bank account. If they differ, the transfer must be sent internationally using SWIFT and Paddle charges a wire fee. Your bank may also charge you fees in this case.