How an embedded billing integration works

Embedded billing with Paddle lets you offer billing and 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 how an embedded billing integration works, including all the moving parts and touchpoints.

How embedded billing works

At a high-level, there are three layers to an embedded billing integration:

• Platform: You build a partner integration
  You offer your users the option to add payments to their apps using Paddle. Use our partner API, MCPs, and embed library to build a native-feeling experience quickly.
• User: Your users integrate with Paddle
  Your users (sellers) use your platform to integrate Paddle in their apps. Our modern, agent-ready API and developer tooling make integration predictable and repeatable.
• Paddle: Customers make a purchase
  When customers make a purchase in one of your user's apps, Paddle runs the whole transaction as merchant of record. This includes payments, tax, compliance, fraud prevention, and paying out the seller.

Here's what a single purchase looks like:

sequenceDiagram
    participant B as Customer
    participant App as Seller's app
    participant PD as Paddle (MoR)
    participant Plat as Partner platform
    B->>App: Start checkout (Paddle.js)
    App->>PD: Open checkout for a price
    B->>PD: Pay
    PD->>PD: Process payment · calculate & collect tax
    PD-->>App: transaction.completed / subscription.created
    App->>App: Provision access / entitlements
    PD-->>Plat: Platform webhooks (metrics, payouts)
    Note over PD: Paddle remits tax, fights chargebacks,<br>and pays out the seller (minus fees)

Your platform guides users through onboarding and your agent builds an integration for them, but once a user is live with Paddle then billing runs entirely inside their own app. Your platform isn't involved in the payments or subscription billing path beyond integration.

To build a native experience for your users, you can build dashboards and observe seller, subscription, and transaction lifecycle events by using webhooks or querying the partner API. This means users don't need to interact with the Paddle dashboard, using your platform as the source of truth.

What each layer does

Each layer has a different set of responsibilities:

Here's how each layer works together:

flowchart 
    subgraph plat["Your platform (backend + UI)"]
        direction TB
        prov["Provision seller<br>Partner API"]
        surf["Surface status &<br>revenue metrics"]
    end
    subgraph agent["Your AI agent"]
        direction TB
        scaffold["Scaffold the<br>seller integration"]
        golive["Check readiness<br>& go live"]
    end
    subgraph paddle["Paddle"]
        direction TB
        mor["Verify · tax ·<br>fraud · payouts"]
    end
    subgraph seller["Seller's app"]
        direction TB
        billing["Live billing -<br>customers pay & use"]
    end
    prov --> scaffold
    scaffold --> billing
    scaffold --> surf
    golive --> mor
    billing --> mor

How you build an integration

Platform layer: integrate Paddle with your platform

To build the platform layer:

• Onboard sellers and configure account settings using the partner API.
• Walk sellers through verification (KYB/KYC) using the @paddle/partner-embeds library, partner API, and magic sessions.
• Surface status and revenue metrics natively in your app using the public API.
• Use our partner agent skills to build your platform integration using an AI coding tool.

This is a one-time integration between your platform and Paddle. You handle seller onboarding, verification, and metrics natively in your app, so sellers never have to interact with the Paddle dashboard.

Agent layer: build seller integrations

Most of the seller integration is built by your agent, on demand, inside each seller's app. You steer it using:

• Paddle's docs: the reference for how Paddle works.
• Your own skills: skills you author that wrap your platform's helper functions, proxies, and business logic, so your agent builds against your backend the same way every time.

In practice, building an embedded billing integration is largely a matter of authoring skills for your agent so that it can consistently scaffold a working Paddle integration for every seller. You can use our public agent skills as a starting point, but you'll need to include them to mention your platform's helper functions and business logic.

Throughout these guides, each step shows whether your Platform or your Agent runs it, so you can see what to turn into a skill. We also have an author-agent-skills skill to help you transform our agent skills into skills for your own agent.

Developer tools

You don't need to build a payments stack from scratch. To build each layer, you can use developer tools provided by Paddle:

What an integration looks like

Integrate with AI

You can use our agent skills for each step of the integration:

• Partner skills: the platform layer
  For the one-time integration you build against the partner API: onboarding, verification, go-live, and metrics.
• Public skills: the agent layer
  For the seller integration your agent scaffolds inside each seller's app: catalog, checkout, webhooks, and subscriptions.

To get started, we recommend using integrate-partner-platform for the end-to-end journey and partner-api-basics for the auth and environment model.

See Integrate with AI for the full set of partner skills, plus Paddle's agent plugins and MCP servers.