> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Build with Lovable

Use Lovable to prompt-build apps that integrate Paddle Checkout, subscriptions, and webhooks — backed by the Paddle MCP server and docs MCP server.

---

[Lovable](https://lovable.dev) generates working applications from natural-language prompts — frontend, backend, database, and integrations included. To ship a Paddle integration with Lovable, connect the **Paddle docs MCP server** so Lovable's agent generates current Paddle code, and the **Paddle MCP server** so it can read and act on your account during development.

This guide covers the integration model. For full MCP setup details across other clients, see the [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp.md) and [docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp.md) reference pages.

## Before you begin

- A Paddle [sandbox account](https://developer.paddle.com/sdks/sandbox.md) and [API key](https://developer.paddle.com/api-reference/about/api-keys#create-api-key.md).
- A Lovable workspace.
- Paddle's webhook secret if you'll wire up webhooks (optional for first prototypes).

## How Lovable integrates with Paddle

Lovable supports three integration mechanisms:

- **Chat connectors** — MCP servers attached to Lovable's agent during development. The agent uses them to look up information and take actions while it writes code, but they don't ship in the deployed app.
- **App connectors** — managed integrations for production apps (analytics, CMS, etc.).
- **Custom APIs** — direct HTTP integrations the deployed app calls at runtime, with secrets stored in Lovable Cloud.

For Paddle, the right mix is **Chat Connectors for development context** and **the Paddle SDK or API in your generated code for runtime calls**.

## 1. Add the Paddle docs MCP server as a chat connector {% step=true %}

The docs MCP server gives Lovable's agent access to current Paddle documentation, the OpenAPI spec, and SDK references. This is the highest-leverage step — it stops the agent generating outdated code from training data.

The docs MCP server runs at `https://paddlehq.mcp.kapa.ai`. In Lovable, add it as an HTTP-transport MCP server in your workspace's chat connector settings.

<!-- TODO: verify exact Lovable UI path for adding chat connectors -->

```json
{
  "name": "paddle-docs",
  "type": "http",
  "url": "https://paddlehq.mcp.kapa.ai"
}
```

You may be prompted to authenticate with Kapa.ai the first time you use it. See [docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp.md) for the full setup guide.

## 2. Add the Paddle MCP server (optional but recommended) {% step=true %}

The Paddle MCP server lets Lovable's agent read and act on your Paddle account — create products, preview pricing, simulate webhooks, debug failed payments — without you leaving the chat.

Add it as a `stdio` chat connector with your **sandbox** API key. Start with `--tools=non-destructive` so the agent can create and read but not update or archive.

<!-- TODO: verify Lovable supports stdio transport in chat connectors -->

```json
{
  "name": "paddle",
  "command": "npx",
  "args": [
    "-y",
    "@paddle/paddle-mcp",
    "--api-key=YOUR_SANDBOX_API_KEY",
    "--environment=sandbox",
    "--tools=non-destructive"
  ]
}
```

{% callout type="warning" %}
The Paddle MCP server has access to your account. Use a sandbox API key during development — never paste a live API key into a workspace shared with collaborators. See [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp.md) for tool scoping options.
{% /callout %}

## 3. Add Paddle context to your knowledge base {% step=true %}

Lovable's [knowledge base](https://docs.lovable.dev) gives the agent persistent context across prompts in a project. Paste a short Paddle primer there so the agent knows your defaults — sandbox vs production environment, which SDK to use, whether you're shipping subscriptions or one-time products, and any pricing model decisions.

Example knowledge entry:

```markdown
## Paddle integration

- Use the Paddle Node SDK (@paddle/paddle-node-sdk) for backend calls.
- Use Paddle.js (@paddle/paddle-js) for the checkout overlay on the frontend.
- All development uses the sandbox environment with API keys containing _sdbx.
- Always verify webhook signatures with paddle.webhooks.unmarshal() before
  acting on the payload.
- Pricing model: three-tier monthly subscription (Starter, Pro, Enterprise).
```

## 4. Prompt your first integration {% step=true %}

With both MCP servers connected and your knowledge base set, ask Lovable to scaffold the integration. Be specific about what you want — Lovable's agent works better with concrete prompts than vague ones.

```markdown {% wrap=true %}
Build a pricing page with three subscription tiers (Starter $10/mo, Pro $30/mo, Enterprise $300/mo). Use Paddle Checkout in overlay mode. Pull current pricing from Paddle.js with localized prices. Set up a Next.js API route that handles webhook events from Paddle — verify the signature and provision access on transaction.completed. Use the Paddle MCP server to create the products in my sandbox account first, then generate the code that uses them.
```

The agent will use the docs MCP server to look up the current Paddle.js syntax, use the Paddle MCP server to create the products in your sandbox, then generate the working app.

## Best practices

- **Mention Paddle explicitly.** "Use Paddle Checkout" is less ambiguous than "add a checkout."
- **Be specific.** Pass price IDs, subscription terms, and event names rather than letting the agent guess.
- **Ask for a plan first.** For complex integrations, get the agent to draft a plan before writing code. Approve, then run.
- **Sandbox-only credentials.** Lovable workspaces are shared — never paste a live API key.
- **Check the generated code.** AI agents make mistakes. Review the webhook signature verification, environment switching, and error handling before deploying.

## Troubleshooting

{% accordion %}
{% accordion-item title="Agent generates outdated Paddle code" %}
Make sure the docs MCP server is connected and authenticated. If the agent isn't calling it, prompt it explicitly: *"Check the current Paddle docs before generating this — use the paddle-docs MCP server."*
{% /accordion-item %}
{% accordion-item title="Paddle MCP server isn't taking actions" %}
Confirm your API key is valid and that the `--tools` flag allows the action you're asking for. `read-only` blocks creates and updates; `non-destructive` allows creates but blocks updates and archives.
{% /accordion-item %}
{% accordion-item title="Webhook signature verification fails in deployed app" %}
The webhook secret is environment-specific. Check that your deployed app uses the live webhook secret in production and the sandbox secret during testing.
{% /accordion-item %}
{% /accordion %}