How Paddle works: a primer for partners

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.

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:

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

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

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:

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

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.

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.

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.