Checkbox Docs

Connect Paddle Billing with a read-only API key so Checkbox reads your prices, trials and subscription events, and see what Paddle does for you as merchant of record.

Checks only. Checkbox checks your pages, emails and cancellation flow, and reads your Paddle plans and subscription events. Checkbox never changes anything in Paddle. For a test subscription, use a generic test run. Reminders need time travel, which only Stripe test runs have.

Selling through Paddle or Lemon Squeezy?

Paddle and Lemon Squeezy are merchants of record: they take the payment and are the seller on the receipt. Your pricing page, the renewal terms you write, your own emails and the cancel link on your account page are still yours, and Checkbox checks them on either platform. What differs today:

  • Paddle: Checkbox also connects with a read-only API key (below), reads your prices, trials and subscription events, and can send the required reminders for you (Notices).
  • Lemon Squeezy: no billing connection yet, so no Notices. Checkbox checks your pages, the emails you BCC or forward, and the cancellation flow it can reach from your site.
  • Both: a generic test run signs up through your real checkout with a 100%-off test coupon (or a test account), cancels online, and collects the acknowledgment and cancellation emails. It cannot move time forward, so reminders before a renewal are not observed; that and the hosted cancellation page need Stripe.

Who is responsible when two companies share the flow is a question for your lawyer; Selling through a merchant of record explains what is yours and what the merchant of record already does.

Checkbox reads your products, prices and trials through the Paddle API (Paddle Billing, API version 1; Paddle Classic isn't supported), and turns Paddle webhooks (sign-ups, renewals, price changes on a plan, cancellations) into lifecycle events. The reminder and cancellation checks use those events, and so do Notices.

Connect

  1. Register the site with platform: "paddle":
curl https://app.checkbox.site/v1/sites \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://acme-saas.example", "platform": "paddle" }'
  1. Create an API key in Paddle: Developer tools → Authentication → API keys → New API key (Paddle's current docs call the menu My account → Settings → Authentication). Name it Checkbox and give it read permissions only:

    PermissionWhy
    Products: Read, Prices: ReadYour plans, billing periods and trials
    Subscriptions: ReadSubscription counts (no customer data)
    Notification settings: ReadWhether the Checkbox webhook is added
    Transactions: Read (recommended)Telling a price increase apart from other subscription changes
    Customers: Read, Addresses: Read (recommended)The subscriber's email and US state, for Notices

    Paddle keys expire (90 days by default, at most a year). When yours does, connect a new one.

  2. In the dashboard, open Site → Settings → Billing connection, choose Paddle and paste the key. Live keys (pdl_live_apikey_…) read api.paddle.com; sandbox keys (pdl_sdbx_apikey_…) read your sandbox. Checkbox reads your prices once to check the key, then stores it encrypted. With the API, call connectBillingPlatform with { "platform": "paddle", "credentials": { "apiKey": "pdl_live_apikey_…" } }. Only keys made before Paddle added the live/sdbx prefix need "environment": "live" or "sandbox".
  3. Add the webhook. After you connect, the dashboard shows the URL and the events to send (also under Billing connection → Paddle webhook, and in webhook_setup in the API response). In Paddle, open Developer tools → Notifications → New destination (Events → Notifications in newer menus), choose Webhook, paste the URL, select the events, and choose platform events only (simulated events would count as real ones).
  4. Copy the destination's secret key (the destination's menu → Edit destination) and paste it under Billing connection → Paddle webhook. Paddle signs every event with it; Checkbox refuses events until it's saved, and events more than 5 minutes old. Checkbox doesn't create the destination for you: it only reads.

Once the key can read notification settings, the dashboard says whether Paddle lists the destination, and which events it doesn't send yet. Click Sync on the connection to check again.

What Checkbox reads

SettingRead from Paddle?
Recurring prices: amount, currency, billing periodYes. Country-specific prices are noted; plans show the base price
Free trials (length, and whether a card is needed) and paid trialsYes, from each price
Subscription counts by statusYes. Counts only, no customer data
Subscription events: created, trialing, activated, updated, canceled, renewal paymentsYes, through the webhook
Whether the Checkbox webhook is addedYes, with Notification settings: Read
Customer portal settingsNo. Not checked yet
Paddle's customer emails (wording, timing)No. Not checked yet until Checkbox sees the emails
Paddle Checkout wording and consentNo. Checkbox checks your page in a real browser instead

Checkbox never treats a setting it can't read as passing. It shows Not checked yet until it has evidence.

Paddle's webhooks include the whole subscription, so Checkbox needs no lookup to see dates and amounts. With the recommended permissions it also reads the subscriber's email and state for Notices, and the last payment to spot a price increase on the same plan.

What Paddle does for you

Paddle is the merchant of record: it runs checkout, takes payments and sends some customer emails itself. From Paddle's developer docs:

  • Customer portal with cancellation. "The customer portal is included by default with Paddle. You don't need to do anything to turn it on." Customers can cancel there; Paddle cancels at the end of the billing period (Customer portal, Cancel a subscription).
  • Receipts. "Paddle automatically sends customers an email receipt when a transaction is completed, like when a customer completes checkout or a subscription renews" (Revise customer details).
  • Trial-ending email, for trials that took a card. "When the trial period is getting close to ending, Paddle sends an email to the customer" (Trials). Not for cardless trials: "Paddle doesn't email customers trial ending reminders for cardless trials" (Cardless trials).

Paddle's docs describe no renewal reminder, yearly terms reminder, price-change notice or cancellation-confirmation email. Send those yourself, or let Notices send them. Checkbox still checks each requirement on evidence: forward one of Paddle's receipts and trial-ending emails to your site's inbound address so Checkbox can check what they say.

What to check

  • Disclosure and consent on your page. Paddle Checkout opens from your page. Put the full renewal terms and a required, unchecked renewal-consent checkbox directly above the button that opens it. A required box only blocks a form's submit button, and Paddle.Checkout.open() is usually called from a plain button, so put the box and the button in one form and open checkout from the form's submit handler (or keep the button disabled until the box is ticked). Pass the consent in customData so Paddle stores it on the transaction:

    HTML
    <form id="subscribe">
      <p>Renews automatically every month at $9.00 until you cancel. Cancel anytime online at …</p>
      <label><input type="checkbox" required> <span>I agree to the automatic renewal terms above.</span></label>
      <button type="submit">Subscribe</button>
    </form>
    <script>
      document.getElementById('subscribe').addEventListener('submit', function (event) {
        event.preventDefault(); // reached only once the required box is ticked
        Paddle.Checkout.open({
          items: [{ priceId: 'pri_…', quantity: 1 }],
          customData: { auto_renew_consent: { at: new Date().toISOString(), label: this.querySelector('label span').textContent } },
        });
      });
    </script>

    The ready-made fix in the dashboard (Fixes) has this block filled in with your terms, and a Lemon Squeezy version (LemonSqueezy.Url.Open with the consent as checkout[custom][…] on the checkout URL).

  • Online cancellation. Link to Paddle's customer portal from your account page with a clear "Cancel subscription" link. If you use Retain → Cancellation Flows, keep the survey optional and show at most one offer.
  • Reminder emails. Check timing against checkNoticeSchedule. Paddle sends no trial-ending or upcoming-renewal webhooks; Notices work the dates out from each subscription's trial end and next billing date.
  • Price changes. When you move subscribers to a higher price on the same plan, Checkbox records it as a price change and asks you to confirm the notice went out. Notify subscribers before you change the price.

Rules written and maintained by the Checkbox team from the text of each law, each cited to its source. Automated checks, not legal advice.

Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). You remain solely responsible for your subscription program, and Checkbox takes on no legal liability for it (Terms). Checkbox is a System1 company; Trust center · Status. For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.