Paddle Billing cardless trials sample

Paddle Billing is the developer-first merchant of record. We take care of payments, tax, subscriptions, and metrics with one unified API that does it all.

This is a sample implementation of cardless trials with Paddle Billing and Next.js. It's designed to help you understand cardless trials and implement them in your own app quickly.

Important: This sample works with Paddle Billing. It does not support Paddle Classic. To work with Paddle Classic, see: Paddle Classic API reference

Features

• Pricing page that uses Paddle.js to fetch localized prices.
• Signup page that creates a customer, address, and transaction for a cardless trial.
• Dashboard page that displays the customer's subscription status.
• Workflow to collect payment method and convert a cardless trial to a paid subscription.

What's not covered

This sample is designed to be a simple implementation of cardless trials, not a complete starter kit. It doesn't cover:

• Auth and user management
  You should create customer and subscription records in your database when users sign up for a subscription.
• Fulfillment using webhooks
  For simplicity, this sample polls for the transaction status to get the subscription ID. This is not a reliable way to handle fulfillment in production. In a production environment, you should use webhooks to handle fulfillment.
• Complete error handling
  Errors are returned to the client, but not logged or handled. In a production environment, you should log errors and handle them appropriately.
• Duplicate user detection
  During the signup process, if an email address is already associated with a customer then the signup form errors. In a production workflow, you should check for duplicate users and handle them appropriately.
• Abuse detection
  To prevent free trial abuse, consider blocking known disposable email address domains or implementing a CAPTCHA using a service like reCAPTCHA or Cloudflare Turnstile.

For a complete Paddle Billing implementation, fork or clone our Next.js starter kit. It includes everything you need for subscription billing — including a localized pricing page, integrated checkout, auth and user management, and screens for customers to manage their payments.

Stack

This sample uses:

• Framework: Next.js
• Component library: shadcn/ui
• CSS framework: Tailwind

Prerequisites

• Node.js version > 20
• pnpm (recommended), Yarn, or npm
• Paddle Billing account — sandbox recommended

Run locally

1. Clone the repository and navigate to the project directory:

   git clone https://github.com/PaddleHQ/paddle-sample-cardless-trials
   cd paddle-sample-cardless-trials

2. Install dependencies using pnpm, Yarn, or npm:

   pnpm install

3. Set up environment variables:

   cp .env.example .env.local

   Add your Paddle API key and client token to the newly created .env.local file. You can get your Paddle API key and client token from Paddle > Developer tools > Authentication.

4. Create products and prices in Paddle, then update the pricing-tier.ts constants file with your new price IDs. For details, see Create a cardless trial → Create a price.

5. Start the development server:

   pnpm run dev

6. Open the app in your browser and test the cardless trial workflow:

   http://localhost:3000

Full tutorial

Follow our full tutorial to learn more about cardless trials and how to implement them in your own app.

Get help

For help, contact the Paddle DX team at [email protected].

Learn more

• Create a cardless trial
• Paddle API reference
• Sign up for Paddle Billing