paddle-billing-history

Render the user's billing history in Next.js

When to use this skill

Use this skill when adding a "Billing history" or "Invoices" section to the authenticated user's account page. The user expects to see their past transactions with dates, amounts, and the ability to download invoices. This skill covers a Next.js 15 (App Router) Server Action that lists transactions for the authenticated customer with proper pagination, status filtering, and currency display.

This is the read side of transaction data. Pair it with:

• subscription-sync — provides the customers table you join on to find the user's Paddle customer_id.
• webhooks — populates the customers table from customer.created events.
• customer-portal — an alternative if you want Paddle to host the entire billing UI (see "Should you build this yourself?" below).

Should you build this yourself?

The Paddle customer portal already provides a hosted billing-history view (see customer-portal). Build your own when:

• You want the billing surface to live inside your dashboard, with consistent navigation and styling.
• You want to combine billing data with app-specific context (e.g. usage details, custom invoice fields).
• You want to control what gets shown — the portal shows everything; a custom view can omit, group, or relabel transactions for your audience.

If none of those apply, send users to the portal and skip this skill.

Prerequisites

• A Paddle account with at least one customer that has transactions (sandbox is fine).
• Server-side PADDLE_API_KEY available — this action runs in a Server Action, never in the browser.
• A customers table mirrored from webhooks (see subscription-sync). You'll look up the authenticated user's Paddle customer_id here via the email bridge.
• An auth system. Examples use Supabase.

NEXT_PUBLIC_PADDLE_ENV=sandbox             # or "production"
PADDLE_API_KEY=pdl_sdbx_apikey_...

NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...              # or SUPABASE_SECRET_KEY (new opaque sb_secret_*)