Go-live checklist

This checklist walks through everything you need to go live with Paddle. You build and test your integration in a sandbox account, then set up your live account, get verified, and run a final test before you open checkout to customers.

Each step has two tabs:

Use AI-assisted to copy a prompt into your AI agent.
Use Manual for a checklist of what to do in the Paddle dashboard or using the Paddle API.

You can switch between tabs any time. If your agent can't do something, like change a setting that it doesn't have permission for, it tells you what to do in the dashboard.

To change settings using the Paddle API or the Paddle MCP server, your API key or MCP connection needs the matching permissions. Choose permissions when you create an API key or authorize an MCP connection.

Overview

Before you begin, sign up for a sandbox account and create an API key. You can also set up your AI tools, if you're building with an AI agent. Then:

Create your catalog
Add products and prices to your sandbox account.
Build your pricing page and checkout
Show localized prices and open checkout using Paddle.js, then configure checkout and account settings.
Handle fulfillment and provisioning
Use webhooks to keep your app in sync with Paddle and grant customers access.
Test your integration
Test checkout, webhooks, and the subscription lifecycle end to end in sandbox.
Set up your live account
Recreate your setup in your live account, then switch your code over to live.
Verify your account
Complete account setup so Paddle can verify your business.
Test and go live
Run a real checkout in your live account, then open to customers.

When you're live, work through the steps after you launch.

Before you begin

Sign up for a sandbox account
A sandbox account is where you build and test your integration. It's separate from your live account and uses test cards, so no real money moves. You don't need to verify a sandbox account.
Sign up for a sandbox account, then confirm your email address.
Set up your AI tools
This step is optional. If you're building with an AI agent, install Paddle agent skills and the Paddle MCP servers.
Agent skills teach your agent how to integrate Paddle, and the Paddle MCP servers let it create and check data in your sandbox and live accounts. The docs MCP server gives it up-to-date Paddle documentation.
For Claude Code, Codex, or Gemini CLI, install the Paddle plugin. For other tools, install agent skills using the skills CLI, then add the MCP servers in your tool's MCP settings.
The sandbox MCP server authenticates with a sandbox API key. The live MCP server authenticates with OAuth, so there's no live key to set. It starts with read access, so grant write permissions under Paddle > Connectors > MCPs when you're ready for your agent to make changes in live.
To learn more, see Build with AI tools, Paddle MCP server, and Agent skills.
Create an API key and test it
API keys authenticate requests to the Paddle API, and the sandbox MCP server uses one too. Create a sandbox API key with the permissions your integration needs, then get the API root with it to check it works. A valid key returns the account it belongs to and its permissions.
Create API keys in Paddle > My account > Settings > Authentication.
To learn more, see Authentication, Permissions, and API root.

Build in sandbox

Build your integration against your sandbox account. Use test cards and simulated webhooks to try every scenario without real money.

Create your catalog

Your catalog is everything you offer, including subscription plans, recurring addons, and one-time charges. Each item is a product with one or more related prices. You can add more products and prices later.

Copy this example prompt into your AI agent, and change the plans and prices to match yours.

Create your catalog

Create my product catalog in my Paddle sandbox account.

I want to offer:
- Starter — USD 10.00/month, USD 100.00/year
- Pro — USD 40.00/month, USD 400.00/year
- Advanced — USD 120.00/month, USD 1200.00/year

Include a 7-day free trial on all plans.

Also create country price overrides for the UK (GBP), Ireland (EUR), and Australia (AUD), adjusted for local purchasing power. Pick sensible starting amounts and list them so I can adjust.

Notes:
- Paddle amounts are in the lowest denomination as strings — USD 10.00 is "1000", not "10" or "10.00".
- Create one product per plan, with its monthly and annual prices attached.
- When done, list every product and price you created with its Paddle ID, so I have the mapping.

This prompt asks your agent to:

Create a product for each plan, with a monthly and an annual price.
Add a 7-day free trial to each price.
Add country-specific prices for the United Kingdom, Ireland, and Australia.
List each product and price with its Paddle ID, so you can use them in your code.

Create products
A product describes an item you offer: its name, description, image, and tax category. A common pattern is one product for each plan tier, like Starter, Pro, and Advanced.
- Dashboard: Paddle > Catalog > Products
- API: Create a product
To learn more, see Create products and prices.
Create prices
Prices describe how much and how often customers pay for a product, like $30/month or $300/year. Add at least one price to every product. For plan tiers, give each tier both a monthly price and an annual price.
Trials are part of a price, so add a trial when you create a recurring price. To offer prices in other currencies, add country-specific prices. All items on a subscription must share the same billing period, so create prices for each billing period you offer.
- Dashboard: Paddle > Catalog > Products, then click a product
- API: Create a price
To learn more, see Create products and prices and Offer localized pricing.

Build your pricing page and checkout

Use Paddle.js to show localized prices on your pricing page and open Paddle Checkout when customers are ready to buy. Build against your sandbox account with a test client-side token, so you can test the whole flow using test cards.

Copy this example prompt into your AI agent, and change the details to match your stack.

Build a pricing page and checkout

Build a 3-tier pricing page with checkout, using my Paddle sandbox account. Change any stack-specific details below to match my framework.

Requirements:
- Show country-localized prices for Starter, Pro, and Advanced.
- Let the user toggle monthly/yearly billing.
- Each tier has a Subscribe button that opens Paddle Checkout as a one-page overlay for the exact price shown, via Paddle.Checkout.open with settings.displayMode: 'overlay' and settings.variant: 'one-page'.
- Redirect to `/welcome` on success.

Implementation:
- Use @paddle/paddle-js: `Paddle.PricePreview()` for prices, `Paddle.Checkout.open()` for Subscribe.
- Detect the user's country server-side from request headers (e.g. Vercel sets `x-vercel-ip-country`) and pass it to the client component that fetches prices. If the header is absent, do NOT pass a country code — `Paddle.PricePreview()` auto-detects location from the visitor's IP. If you use an internal "unknown" sentinel like 'OTHERS', keep it app-side only; never pass it to Paddle as a country code.
- Use the sandbox environment and a sandbox client-side token (prefixed `test_`). Read environment and token from env vars; never hard-code them. Create the token with the `paddle-sandbox` MCP if available, otherwise ask me. Create/update `.env.example`.
- Default payment link — set it to my sandbox checkout page with the `paddle-sandbox` MCP (`PATCH /settings/checkout-url`). It must be a page on my own domain, not localhost. On live, the domain must also be approved for my account; sandbox doesn't need approval. If the call fails — it returns `forbidden`, the domain isn't approved yet, or the tool isn't available — tell me to set it under Checkout > Checkout configuration.
- Read my current payment methods, sales tax mode, and balance currency with the `paddle-sandbox` MCP (`GET /settings/checkout-payment-methods`, `GET /settings/tax`, `GET /settings/balance-currency`). Tell me what they are, and ask me before changing any of them.
- Make tiers easy for me to edit, e.g.:

    export interface Tier {
      name: 'Starter' | 'Pro' | 'Advanced'
      description: string
      features: string[]
      priceId: { month: string; year: string }
    }

Notes:
- Display only the totals Paddle returns (`formattedTotals`). Do no price math on the frontend, and don't re-format Paddle's already-formatted strings (no Intl.NumberFormat, no rounding).
- The server-side API key must never appear in client / 'use client' code.
- Never silently default the environment — read it from an env var and fail loudly if that var is unset, so you never run against the wrong Paddle account.
- Prefill the customer's email if they're signed in.
- Writing settings needs permissions like `checkout_settings.write`. If a call returns `forbidden`, tell me to grant the permission (API key permissions, or Connectors > MCPs for live) or do it in the dashboard.

Before you finish, confirm the integration in sandbox. On sandbox: confirm checkout opens, completes, and redirects end-to-end. On live: don't take a real payment yet — live transactions can't complete until verification passes and your domains are approved — so just confirm checkout opens and shows the right prices; a live test transaction comes later in "Test and go live".

This prompt asks your agent to:

Build a pricing page that shows localized prices for three plans, with a toggle for monthly and annual billing.
Open an overlay checkout when a customer subscribes, then redirect to a success page.
Create a sandbox client-side token, and store it in an environment variable.
Set your default payment link.
Check your payment methods, sales tax setting, and balance currency, and ask you before changing them.
Check that checkout opens, completes, and redirects in your sandbox account.

Create a client-side token
Client-side tokens authenticate Paddle.js in your frontend. Sandbox tokens start with test_ and live tokens start with live_. Never use an API key in your frontend.
- Dashboard: Paddle > My account > Settings > Authentication
- API: Create a client-side token
To learn more, see Client-side tokens.
Set your default payment link
Paddle uses your default payment link to open checkouts for transactions and payment method updates, including from links in emails it sends to customers. Set it before you open any checkout, or checkout fails with "Something went wrong."
It should be a page that includes Paddle.js, typically your checkout page. Use your own domain, not localhost. Checkout itself still opens on localhost in sandbox, so you can test locally.
In sandbox, its domain doesn't need to be approved. In live accounts, it must be on an approved domain. You get your domains approved when you set up your live account.
- Dashboard: Paddle > Checkout > Checkout configuration, then expand Default payment link
- API: Update checkout URL settings
To learn more, see Set your default payment link.
Turn on payment methods
Choose the payment methods customers can use at checkout. You don't need to sign up for merchant or partner accounts. Card is always on for checkouts, and bank transfer is always on for invoices.
- Dashboard: Paddle > Checkout > Checkout configuration, then expand Payment methods
- API: Update checkout payment method settings
To learn more, see Payment methods.
Choose your sales tax setting
Choose whether prices include tax by default: exclusive of tax, inclusive of tax, or set automatically based on the customer's location. Prices are typically exclusive of tax for business customers, and in regions with sales taxes.
Paddle uses this setting for prices with a tax_mode of account_setting.
- Dashboard: Paddle > My account > Settings > Sales tax
- API: Update tax settings
To learn more, see Create products and prices.
Set your balance currency
Paddle converts what customers pay into your balance currency and holds your earnings in it, ready for payout. We recommend choosing a currency that matches your bank account.
- Dashboard: Paddle > My account > Settings > Currencies
- API: Update balance currency settings
To learn more, see Supported currencies.
Build your pricing page
Use Paddle.PricePreview() to get localized prices for your plans, and show the formatted totals that Paddle returns. Paddle detects the customer's country automatically, so you don't need to do any currency math.
To learn more, see Build a pricing page.
Build your checkout
Include Paddle.js, call Paddle.Environment.set("sandbox"), then initialize it with your client-side token. Call Paddle.Checkout.open() with the price IDs to open a checkout.
If the customer is logged in, prefill their email to skip the first screen.
To learn more, see Build an overlay checkout or build an inline checkout.
Handle checkout success
When checkout completes, you can redirect customers to your own success page, or run your own logic using Paddle.js events. Use webhooks to grant access, rather than the redirect.
To learn more, see Handle checkout success.
Make a test purchase
Open your pricing page and complete a purchase using test card 4242 4242 4242 4242, any name, any future expiry date, and CVV 100.
- Dashboard: Check the transaction appears in Paddle > Transactions.
- API: List transactions
To learn more, see Card.

Handle fulfillment and provisioning

Use webhooks to keep your app in sync with Paddle. When a customer completes checkout, Paddle sends a webhook so you can record the customer, mirror their subscription, and grant access to what they bought. The same events keep your app in sync through upgrades, cancellations, pauses, and payment failures.

Copy this example prompt into your AI agent, and change the details to match your stack.

Handle fulfillment and provisioning

We have a 3-tier Paddle pricing page and checkout (monthly and annual plans). Build the fulfillment and provisioning layer in three parts, server-side only, against my Paddle sandbox account.

## 1. Webhook handler with signature verification

Build a route handler that receives Paddle webhook deliveries, verifies the signature, and routes events to typed handlers.

- Verify the signature with the Paddle SDK before doing anything else. In Node this is `paddle.webhooks.unmarshal(rawBody, secret, signature)`.
- Pass the RAW request body to unmarshal (read it as text, e.g. `await request.text()` / `express.raw()`). Do NOT JSON.parse it first — a parsed body fails verification.
- Use the webhook notification SIGNING SECRET to verify, not the API key. They're different.
- If verification fails, don't return a 2xx. A 2xx tells Paddle the delivery succeeded and it stops retrying.
- Deliveries are at-least-once and can arrive out of order: make handlers idempotent (upsert keyed on the Paddle ID, don't blind-insert).
- Route verified events to handlers for subscription.created/updated/canceled, customer.created/updated, transaction.completed. Safely ignore other types.
- Create the sandbox notification destination with the `paddle-sandbox` MCP if available (otherwise tell me to create one under Events > Notifications) and read back the signing secret. Store secrets in env vars; create/update `.env.example`.

## 2. Mirror subscription state and grant access

Mirror Paddle subscription and customer state into my database from verified events, plus a helper that decides whether a subscription currently grants paid access.

- Inspect my database first and match its existing conventions — use a database MCP if I have one connected (e.g. Supabase, or another Postgres/database MCP) to read my live schema directly; otherwise infer it from my data layer or ask me. If there are no tables, create `customers` and `subscriptions` (example below is Postgres — adapt to my DB).
- Access helper: treat `active` AND `trialing` as access-granting. Do NOT revoke access just because a `scheduled_change` to cancel or pause exists — only revoke when `status` is actually `canceled` (and handle `paused`/`past_due` per my rules).

    CREATE TABLE customers (
      customer_id TEXT PRIMARY KEY,
      email TEXT NOT NULL,
      created_at TIMESTAMP NOT NULL DEFAULT NOW(),
      updated_at TIMESTAMP NOT NULL DEFAULT NOW()
    );

    CREATE TABLE subscriptions (
      subscription_id TEXT PRIMARY KEY,
      customer_id TEXT NOT NULL REFERENCES customers(customer_id),
      status TEXT NOT NULL,
      price_id TEXT NOT NULL,
      product_id TEXT NOT NULL,
      scheduled_change_action TEXT,
      scheduled_change_at TIMESTAMP,
      created_at TIMESTAMP NOT NULL DEFAULT NOW(),
      updated_at TIMESTAMP NOT NULL DEFAULT NOW()
    );

## 3. Customer portal for self-service

Add an account screen that mints a Paddle customer portal session for the signed-in user and redirects to the returned URL. The portal is Paddle-hosted: customers update payment method, cancel, and view invoices there.

- Verify the user is authenticated FIRST. Resolve their Paddle customer ID server-side from the session — never trust a customer ID supplied by the client.
- Look up the customer (and subscription) in the tables above, then mint the session with the Paddle SDK. Read API key and environment from env vars.

## Guardrails — persistent entities you must NOT delete or offer to clean up

Some Paddle entities are part of the running system, not test litter. At no point — not now, not after testing, not when I say we're done — do you delete them or offer/suggest deleting them as "cleanup." Treat the following as permanent infrastructure:

- The webhook notification destination (and its signing secret) created in Part 1.
- Products and prices backing the 3-tier pricing page.
- Any customers, subscriptions, or transactions in Paddle or in my database — these are live state mirrored from real events, never disposable.

The events these entities drive — transaction.completed, subscription.created/updated/canceled, customer.created/updated — are the fulfillment path. Deleting their backing entities breaks fulfillment.

The one exception: a throwaway artifact YOU just created purely to test (e.g. a simulated event fired through the webhook simulator) that nothing above depends on — you may clean up ONLY that, and only after naming it and asking me first. It never covers the entities listed above, and if a step's completion depends on an entity, leave it. When in doubt, leave it and ask — never delete a Paddle entity or DB row to "tidy up."

This prompt asks your agent to:

Create a sandbox notification destination, and store its secret key in an environment variable.
Build a webhook handler that verifies signatures and handles subscription, customer, and transaction events.
Store customers and subscriptions in your database, and add a helper that checks whether a customer has access.
Add an account page that opens the customer portal.

Create a notification destination
A notification destination tells Paddle where to deliver webhooks and which events to send.
Subscribe to transaction.completed for fulfillment, and subscription.created, subscription.updated, and subscription.canceled for lifecycle changes. To keep customer records up to date, also subscribe to customer.created and customer.updated. Copy the endpoint secret key for signature verification.
- Dashboard: Paddle > Events > Notifications
- API: Create a notification setting
To learn more, see Create notification destinations.
Verify webhook signatures
Every webhook includes a Paddle-Signature header. Verify it against the raw request body using your endpoint secret key before you process the payload, then respond with a 2xx within five seconds.
To learn more, see Verify webhook signatures and Handle webhook delivery.
Mirror subscriptions and grant access
Store the subscription ID, customer ID, status, price ID, and product ID against the user in your database, then use them to decide which features to grant. Webhooks can arrive more than once and out of order, so make your handlers idempotent.
Grant access for active and trialing subscriptions, and revoke it when status is canceled. A scheduled cancellation isn't a cancellation yet, so keep access until the status changes. Keep access for past_due subscriptions while Paddle retries payment, and limit or remove access for paused subscriptions. To spot upgrades and downgrades, check the items on subscription.updated.
To learn more, see Handle provisioning and fulfillment.
Add the customer portal
The customer portal is a Paddle-hosted page where customers can update payment details, view invoices, and cancel. Create a portal session for the logged-in customer, then redirect them to the returned URL. You can build your own screens using the Paddle API later.
- API: Create a customer portal session
To learn more, see Customer portal.

Test your integration

Test your integration end to end in sandbox before you go live: checkout, webhooks, access, and the subscription lifecycle. If anything fails, fix it before you move on.

Copy this prompt into your AI agent.

Test your integration in sandbox

Test my Paddle integration end-to-end in sandbox before going live.

Work through the steps in order, using the `paddle-sandbox` MCP to perform every action against real sandbox test data. Each action triggers real webhooks — verify my handler processes each one correctly.

To check the resulting database state, use a database MCP if I have one connected (e.g. Supabase, or another Postgres/database MCP) to query my tables directly; otherwise verify through my app's data layer or tell me exactly what to confirm. Where you can't do something via MCP, tell me what to check in the dashboard.

## 1. Confirm sandbox configuration

Check that:
- The frontend is initialized with the sandbox environment and a `test_`-prefixed client-side token
- Server-side API calls go to `sandbox-api.paddle.com`, not `api.paddle.com`
- The webhook handler points at a sandbox notification destination, not a live one

Fix anything pointed at the wrong environment before continuing.

## 2. Run a full end-to-end checkout

Guide me through at least one full test purchase. Test cards — enter any cardholder name and any future expiry date:

- Successful payment: 4242 4242 4242 4242
- Declined payment: 4000 0000 0000 0002 (to confirm decline handling)

For the successful flow, verify each step: checkout opened with the correct localized price; transaction status is `completed`; the webhook was received and returned 2xx; customer and subscription records were created; the access helper would unlock the right features for the plan.

## 3. Verify webhook delivery

Use the `paddle-sandbox` MCP to confirm the endpoint received events and returned 2xx. If you can't check via MCP, tell me to go to Events > Notifications and confirm delivery status.

If any delivery failed, show me the full error and suggest a fix.

## 4. Exercise the subscription lifecycle via MCP

Using the subscription created in step 2, perform these three operations with the `paddle-sandbox` MCP, in order. After each one, confirm my handler processed the resulting webhook and my database/access logic ended up in the right state.

#### (a) Plan upgrade, applied immediately without billing

Change the subscription's items to a higher tier, applying the change immediately with no charge (proration billing mode `do_not_bill`). Confirm the handler processed the `subscription.updated` event and the mirrored row now reflects the new price and product — with no transaction charged.

#### (b) Scheduled cancellation at end of billing period

Schedule the subscription to cancel at the end of the current billing period (effective_from `next_billing_period`). Confirm the subscription is NOT yet canceled: status should still be `active` (or `trialing`, if the plan has a trial) with a pending scheduled change, and the access helper should still grant access. This verifies the handler doesn't treat a scheduled cancellation as a terminal cancellation.

#### (c) Immediate cancellation
Cancel the subscription immediately (effective_from `immediately`). Confirm the handler processed `subscription.canceled`, the database status is now `canceled`, and the access helper now denies paid features for that customer.

If anything fails at any step, stop and fix it before continuing. Don't proceed to go-live until everything above passes cleanly.

This prompt asks your agent to:

Check that your frontend, server, and webhook handler all use your sandbox account.
Walk you through a test purchase, then check the transaction, webhooks, database records, and access.
Check that your webhook endpoint received each event.
Upgrade the test subscription, schedule a cancellation, then cancel it, checking your handler after each change.

You also need to:

Complete the test purchase yourself, using the test cards that your agent gives you.

Check your sandbox configuration
Check that your frontend calls Paddle.Environment.set("sandbox") and uses a test_ client-side token, server-side requests go to sandbox-api.paddle.com, and your webhook handler uses the secret for your sandbox notification destination.
To learn more, see Sandbox.
Run a test checkout
Complete a purchase using test card 4242 4242 4242 4242, then try 4000 0000 0000 0002 to check how you handle a declined payment. Use any name, any future expiry date, and CVV 100.
For the successful purchase, check that the transaction is completed, a subscription was created, and the customer has access.
- Dashboard: Paddle > Transactions and Paddle > Subscriptions
- API: List transactions
To learn more, see Card.
Check webhook delivery
Check your endpoint received each event and returned a 2xx. Failed deliveries show the full response, so you can fix your handler.
- Dashboard: Paddle > Events > Notifications
- API: List notifications
To learn more, see Simulate webhooks.
Test the subscription lifecycle
Using your test subscription, upgrade to a higher plan immediately with proration_billing_mode set to do_not_bill, then schedule a cancellation for the end of the billing period. The subscription should keep its status, trialing if it's on a trial or otherwise active, and keep access.
Then cancel immediately, and check it's canceled and access is revoked. After each change, check your handler and database.
- API: Update a subscription and Cancel a subscription
To learn more, see Upgrade or downgrade a subscription and Cancel a subscription.

Go live

When your sandbox integration passes testing, move to your live account. Sandbox and live accounts are separate, so they don't share products, prices, credentials, settings, or notification destinations.

Set up your live account

Recreate your sandbox setup in your live account, switch your code over to live, and finish configuring live settings. Until you verify your account and test in live, don't open your live build to customers.

Before you start, sign up for a live account, connect the live MCP server, and give it write access in Paddle > Connectors > MCPs. Then copy this prompt into your AI agent.

Set up your live account

Migrate my tested sandbox integration into my live Paddle account and finish configuring live so it's ready for verification. I may have already done some or all of this while switching to live, so start by checking what's already in place — then only do what's missing or broken. Do this once my sandbox integration has passed testing.

Heads-up: this step gets my live account and code ready — it does NOT start verification or take a live payment. Those are the next two steps ("Verify your account", then "Test and go live"). Migrating points my code at live, but I can't take live payments until verification passes and my domains are approved, so don't open the live build to real customers yet — verify locally or in staging.

I have two MCP servers:
- `paddle-sandbox` — my sandbox account (source)
- `paddle-live` — my live account (destination)

## 1. Check what's already migrated

Before changing anything, audit the current state and report what's done vs outstanding. I may have completed some of this already — don't redo work that's correct.
- Catalog: compare my sandbox products, prices, and discounts against live (`paddle-sandbox` vs `paddle-live`). List what already exists in live and what's missing.
- Credentials: check my env vars and code for live client-side tokens (`live_`), a live API key, and live notification destinations with a signing secret.
- Code: check whether my code already points at live — live `pri_`/`pro_` IDs, `api.paddle.com`, no `Paddle.Environment.set('sandbox')`, and `pwCustomer` set for Retain.

Give me a short summary of what's already done and what's left, then work through the remaining items below. Skip anything that's already correct; if something exists but looks wrong or partial, fix it.

## 2. Recreate my catalog and credentials in live

For anything missing from the audit:
1. Read my products, prices, and discounts from sandbox and create equivalents in live with the `paddle-live` MCP. Skip test/junk items. Capture the sandbox → live ID mapping — I need it for step 3.
2. Create new live client-side tokens (prefixed `live_`) with the `paddle-live` MCP if it supports it; prompt me to create a live API key in the dashboard. Read both from env vars; never hard-code them. Create/update `.env.example`.
3. Create live notification destinations pointing at my live webhook URLs, and read back the new signing secret (`endpoint_secret_key`). Update the secret my webhook handler uses.

## 3. Swap my code over to live

For anything not already pointing at live, find and replace every sandbox value with its live equivalent:
- Every sandbox price ID (`pri_`) and discount ID → matching live IDs, across pricing page, checkout, upgrade/downgrade logic, and subscription lifecycle code.
- Remove `Paddle.Environment.set('sandbox')` from the frontend (live is the default).
- `sandbox-api.paddle.com` → `api.paddle.com` server-side.
- For Paddle Retain, add `pwCustomer` to `Paddle.Initialize()` — the signed-in customer's Paddle customer ID, e.g. `pwCustomer: { id: 'ctm_...' }`. It must be the Paddle customer ID, not my internal ID or email.

## 4. Finish configuring my live account

Do these via `paddle-live` where you can; otherwise tell me exactly where to go in the dashboard:
- Payment methods — read what's enabled in `paddle-sandbox` and `paddle-live` (`GET /settings/checkout-payment-methods`), ask me which ones I want in live, then enable them with `paddle-live` (`PATCH /settings/checkout-payment-methods`). If you can't, tell me to enable them under Checkout > Checkout configuration.
- Sales tax and balance currency — live settings are separate from sandbox. Read the sales tax mode (`GET /settings/tax`) and balance currency (`GET /settings/balance-currency`) from both `paddle-sandbox` and `paddle-live`, show me any differences, and ask me before mirroring the sandbox values to live with `paddle-live` (`PATCH /settings/tax`, `PATCH /settings/balance-currency`). If you can't, tell me to set them under My account > Settings > Sales tax and My account > Settings > Currencies.
- Submit my domains for approval under My account > Settings > Website approval. This is a dashboard step — there's no API for submitting a domain, so tell me to do it. Checkout won't run on live until a domain is approved (sandbox approves automatically; live does not). Submit now so approval can process while I verify.
- Default payment link — once my domain is approved, set it to my live checkout page with `paddle-live` (`PATCH /settings/checkout-url`). Check first with `GET /checkout-domains`: for live it must be on an approved domain, not localhost, or live checkouts will fail. If my domain isn't approved yet, tell me to set it under Checkout > Checkout configuration once Paddle approves it. If the call fails — it returns `forbidden` or the tool isn't available — tell me to set it there too.
- Add my bank details under Business account > Payouts > Payout settings.

Writing settings needs permissions like `checkout_settings.write`. If a call returns `forbidden`, tell me to grant the permission under Connectors > MCPs or do it in the dashboard.

For webhook security, fetch Paddle's current live IPs from https://api.paddle.com/ips (addresses are in `data.ipv4_cidrs`, as /32 CIDRs), allowlist them on my webhook server, and reject anything else. Don't hard-code the list — the endpoint is the source of truth and can change.

## 5. Pre-verification readiness check

Audit my app and report what's ready vs missing, so I'm set up to pass verification next:
- Live, publicly accessible Terms & Conditions, Privacy Policy, and Refund/Cancellation Policy. List the URLs; flag any that 404 or redirect to a generic page.
- A clear description of what my product does.
- Contact details reachable from the homepage in two clicks or fewer.
- Site pricing matches my live Paddle catalog. List discrepancies.
- Every domain where I run Checkout resolves and serves my real product (not parked, 404, or placeholder).

For each gap, suggest a specific fix. These are common verification checks — confirm exact current requirements against Paddle's verification guidance rather than treating any item as definitively required.

When this is done, my live account and code are ready. Move on to "Verify your account" to complete business verification, then "Test and go live".

## Guardrails — this is my LIVE account; destructive actions are off-limits

Live entities may already have real customers, subscriptions, and payment history attached. Migration here is ADDITIVE and CODE-SIDE only. You must NOT delete, archive, deactivate, or recreate any live entity, and must NOT offer to do so as "cleanup." Specifically:

- The live notification destination or its signing secret. Never delete or recreate one that already exists — recreating rotates endpoint_secret_key and silently breaks verification of every future delivery. If a live destination exists, reuse it; only CREATE one if none exists.
- Live products, prices, or discounts — never delete, archive, or recreate them, especially any with active subscriptions. Editing a price only changes it for new purchases; existing subscriptions keep the version they were created with. If a live price is wrong, show me the fix and ask before you edit it.
- Live customers, subscriptions, or transactions, and their mirrored DB rows — never change them.
- My sandbox account. It is the source of truth for this migration — do not delete or modify any sandbox entity, and do not offer to "clean up sandbox" when done.

"Fix if wrong or partial" (above) means: prefer update-in-place; if a genuine fix would require deleting or recreating any live entity, STOP, name the entity and the exact change, and ask me before doing anything. Default to leave-and-ask.

This prompt asks your agent to:

Check what's already set up in your live account, and only do what's missing.
Recreate products, prices, and discounts in your live account, and map each sandbox ID to its live ID.
Create a live client-side token and live notification destinations, and update your environment variables.
Switch your code to live, and pass pwCustomer to Paddle.js for Paddle Retain.
Turn on payment methods, and mirror your sales tax setting and balance currency, asking you first.
Set your default payment link, if your domain is approved.
Allowlist Paddle IP addresses on your webhook server.
Check that your website is ready for verification, including your terms of service, privacy policy, and refund policy pages.

In the Paddle dashboard, you also need to:

Create a live API key in Paddle > My account > Settings > Authentication.
Submit your domains for approval in Paddle > My account > Settings > Website approval.
When Paddle approves your domain, set your default payment link in Paddle > Checkout > Checkout configuration, if your agent couldn't.
Add your payout details in Paddle > Business account > Payouts > Payout settings.
Review your dunning settings in Paddle > Retain.
Set up cancellation flows in Paddle > Retain > Cancellation Flows.

Verify your account

Before you can accept live payments, Paddle needs to verify your business. This keeps the Paddle platform safe for everyone. You only need to verify your live account.

You start verification by completing account setup in the dashboard. Paddle then reviews your business, which typically takes about 10 minutes but may take longer for more complex businesses.

Complete account setup in Paddle > Get started first. An account administrator needs to do this. Then copy this prompt into your AI agent to check your verification status.

Check your verification status

Check whether my live Paddle account is verified and ready for live payments.

Check with the `paddle-live` MCP (`GET /verifications?verification_type=onboarding`): my account is verified when the onboarding verification's `status` is `completed`. Verification only applies to live accounts, so don't check sandbox. Verifications are read-only, so don't try to change anything.

Tell me the verification's `status` and what's outstanding:
- `completed` — my account is verified, so I can move on to testing in live.
- `pending`, `in_progress`, or `in_review` — Paddle is working on it. Verification is usually ~10 minutes but can take longer for more complex businesses. If the `account_setup` step isn't `completed`, tell me to start verification under Get started in the dashboard. If `automated_review` is `pending`, check my domain verifications (`verification_type=domain`) too, because automated review waits until a domain is approved. Ignore `canceled` domain verifications: they belong to domains that were deleted.
- `action_required` — list the steps that aren't `completed` and tell me to finish them under Get started in the dashboard.
- `failed` — tell me to check my email for details from Paddle.
- `canceled` — this isn't expected for an onboarding verification, and it won't continue. Tell me to contact Paddle support.

If there's no onboarding verification, or you can't check, ask me to confirm in the dashboard.

For full details, fetch https://developer.paddle.com/api-reference/verifications.md or use the paddle-docs MCP server.

This prompt asks your agent to:

Check your verification status, and tell you what's outstanding.
Check whether your domains are approved, if automated review is waiting for them.

In the Paddle dashboard, you also need to:

Finish anything else that Paddle asks for, like documents.
Optionally, verify your domains for Apple Pay in Paddle > My account > Settings > Website approval.

Prepare your website
Before you submit, check your website has:
- Publicly accessible terms of service, privacy policy, and refund policy pages.
- Prices that match your Paddle catalog.
- A contact email address or form that's reachable from your homepage.
Complete account setup
Tell Paddle about you, your business, and what you offer. You need:
- Your personal details, including your date of birth and home address.
- Your business details, including its legal name and address.
- A link to your website.
- Information about what you plan to offer through Paddle.
An account administrator needs to complete account setup.
- Dashboard: Paddle > Get started, then start verification in Verify your account
- API: You can't complete account setup using the API.
Check your verification status
After account setup, Paddle reviews your business. If Paddle needs anything else, like documents, the dashboard shows what's needed and Paddle emails you. An automated review also waits until at least one of your domains is approved.
Your account is verified when your onboarding verification has a status of completed. If it's pending, in_progress, or in_review, Paddle is still reviewing your business. If it stays pending, check that at least one of your domains is approved using List checkout domains. If it's action_required, finish what's outstanding in the dashboard. If it's failed, check your email for details from Paddle.
- Dashboard: Paddle > Get started
- API: List verifications, filtered by verification_type=onboarding
To learn more, see Verifications.
Verify your domains for Apple Pay
This step is optional. Verify your domains for Apple Pay to remove a step from the Apple Pay checkout flow. You can come back to this later.
- Dashboard: Paddle > My account > Settings > Website approval
- API: Verify a payment method for a checkout domain
To learn more, see Apple Pay.

Test and go live

Run a final end-to-end test in your live account to check everything works before you open checkout to customers. Use a 100% discount so you can run a real checkout without paying anything.

Copy this prompt into your AI agent when your account is verified and your domain is approved.

Test in live and go live

Test my Paddle integration end-to-end in live, with a real checkout, before I open to customers.

This mirrors the sandbox test but against real money — so we'll use a 100% discount to run a genuine checkout at zero cost, then clean it up. Use the `paddle-live` MCP to perform and verify every action against my live account. To check database state, use a database MCP if I have one connected (e.g. Supabase, or another Postgres/database MCP); otherwise verify through my app's data layer or tell me exactly what to confirm. Where you can't act via MCP, tell me what to do in the dashboard.

## 1. Pre-flight checks

Confirm all of these before testing — stop and fix anything that's off:
- My integration points at live everywhere: live API key, `live_`-prefixed client-side token, live `pri_`/`pro_` IDs, server-side calls to `api.paddle.com` (not `sandbox-api.paddle.com`), and no leftover `Paddle.Environment.set('sandbox')`.
- My domain is approved. List my checkout domains with the `paddle-live` MCP (or the Checkout Domains API: https://developer.paddle.com/api-reference/checkout-domains/list-checkout-domains/) and confirm the status is approved — checkout won't open on an unapproved domain.
- Business and identity verification is complete. Check with the `paddle-live` MCP (`GET /verifications?verification_type=onboarding`): my account is verified when the onboarding verification's `status` is `completed`. If it's anything else, tell me what's outstanding and to finish it in the dashboard. If there's no onboarding verification, or you can't check, ask me to confirm in the dashboard before continuing. Verification is usually ~10 minutes but can take longer for more complex businesses. Checkout won't open until it's passed.
- My app is deployed to the live domain. Ask me to confirm; checkout must run on the real approved domain, not localhost.

## 2. Set up a safe, zero-cost test

Create a 100% off discount with the `paddle-live` MCP and give me the code to apply at checkout. Tell me you're doing this and why: it lets us run a real end-to-end checkout — real card, real webhooks, real records — at zero cost, so there's nothing to refund afterwards. Paddle still creates a real transaction and subscription at a $0 total, so the rest of the test exercises the full flow.

## 3. Hand over to me to complete the checkout

Pause here and ask me to complete one real purchase myself — don't open a browser or try to pay on my behalf:
- Open checkout on my live domain, apply the discount code from step 2, and complete the purchase with a real card.
- When I confirm it's done, continue. If I hit any problems — checkout doesn't load, the discount doesn't apply, the price looks wrong — I'll tell you and we'll work through them together.

## 4. Verify the result

Once I've confirmed the purchase, verify each step as in the sandbox test:
- Transaction status is `completed`.
- My live webhook endpoint received the events and returned 2xx (check the `paddle-live` MCP or Events > Notifications).
- Customer and subscription records were created/updated in my database.
- The access helper would unlock the right features for the plan.

## 5. Exercise the subscription lifecycle

Find the completed transaction and the subscription it created, then run the same three operations as the sandbox test with the `paddle-live` MCP. After each, confirm my handler processed the webhook and my database/access logic ended up correct:
- (a) Plan upgrade applied immediately with no charge (proration billing mode `do_not_bill`).
- (b) Scheduled cancellation at end of billing period (`effective_from: next_billing_period`) — status should still be `active` (or `trialing`, if the plan has a trial) with a pending scheduled change, and access still granted.
- (c) Immediate cancellation (`effective_from: immediately`) — status `canceled`, access denied.

## 6. Clean up — this is real data, leave nothing live

- Make sure the test subscription is canceled.
- Archive the 100% discount with the `paddle-live` MCP so nobody else can use it.

Confirm everything above passed before I open to customers. If anything fails at any step, stop, troubleshoot it the same way, and re-run.

If a 100% discount isn't workable for my setup, the alternative is to pay with a real card and refund it by creating an adjustment with the `paddle-live` MCP. Avoid this if you can — refunds hurt my seller reputation and can raise my chargeback rate. Talk me through other options first, and only take the refund path if I explicitly choose it.

This prompt asks your agent to:

Check that your code uses live credentials and IDs, your domain is approved, and your account is verified.
Create a 100% discount, so you can run a real checkout at no cost.
Check the transaction, webhooks, database records, and access after your purchase.
Upgrade the test subscription, schedule a cancellation, then cancel it, checking your handler after each change.
Make sure the test subscription is canceled, and archive the discount.

You also need to:

Deploy your app to your approved domain.
Complete the live purchase yourself, using the discount code that your agent creates and a real card.

Run preflight checks
Before you test, check that:
- Your integration uses your live API key, a live_ client-side token, live Paddle IDs, and api.paddle.com, with no Paddle.Environment.set("sandbox").
- Your domain is approved.
- Your default payment link is set to your live checkout page.
- Your account is verified.
- Your app is deployed to your approved domain, not localhost.
Check domain approval and verification status in the dashboard or using the API:
- Dashboard: Paddle > My account > Settings > Website approval and Paddle > Get started
- API: List checkout domains and List verifications
Create a 100% discount for testing
A 100% discount lets you run a real checkout with a real card, real webhooks, and real records, at zero cost. Paddle still creates a transaction and subscription with a total of zero, so there's nothing to refund afterward.
The discount needs a code that you can enter at checkout. Set one, or let Paddle generate one. Using the API, set enabled_for_checkout to true, and Paddle generates a code if you leave out code.
- Dashboard: Paddle > Catalog > Discounts
- API: Create a discount
To learn more, see Create discounts.
Complete a live purchase
Open checkout on your live domain, apply your discount code, and pay with a real card. Then check the transaction is completed, your live webhook endpoint received the events and returned a 2xx, and the customer has access.
- Dashboard: Paddle > Transactions and Paddle > Events > Notifications
- API: List transactions and List notifications
Test the live subscription lifecycle
Run the same lifecycle tests as in your sandbox account: upgrade immediately with proration_billing_mode set to do_not_bill, schedule a cancellation for the end of the billing period, then cancel immediately. After each change, check your handler and database.
- API: Update a subscription and Cancel a subscription
Clean up test data
Make sure the test subscription is canceled, then archive the 100% discount so nobody else can use it.
- Dashboard: Paddle > Subscriptions and Paddle > Catalog > Discounts
- API: Update a discount with status set to archived
If a 100% discount doesn't work for your setup, test with a low amount instead, then refund it by creating an adjustment.

When you've seen the full flow work in live, you're ready to open checkout to customers.

After you launch

Once you're live, keep up to date with changes to the Paddle platform and keep your credentials secure.

Sign up for developer changelog updates
The developer changelog lists all changes to the Paddle API and developer tools. Check it regularly, or sign up for emails to get updates about new features and changes.
To learn more, see Developer changelog.
Sign up for Paddle status page updates
Paddle posts details of any incidents affecting the Paddle platform on its status page in real time. Subscribe to updates by email, webhook, RSS, or Slack.
To learn more, see Paddle status.
Rotate API keys regularly
API keys grant access to the data in your Paddle account. Rotate your API keys periodically, and revoke keys that you no longer use.
- Dashboard: Paddle > My account > Settings > Authentication
To learn more, see Rotate API keys.

Go-live checklist

Overview

Before you begin

Build in sandbox

Create your catalog

Build your pricing page and checkout

Handle fulfillment and provisioning

Test your integration

Go live

Set up your live account

Verify your account

Test and go live

After you launch

Was this page helpful?