Paddle.js checkout not opening: do I need Paddle.Environment.set("sandbox")?

What initializePaddle() does with the environment and the token

Paddle.Environment.set() takes sandbox or production, defaults to production, and Paddle says to call it before any other Paddle.js method, ideally just before Initialize(). In @paddle/paddle-js (src/utils/initialize.ts), initializePaddle() makes that call only when the options include an environment, then calls Initialize() the first time and Update() on later calls. On 2026-10-31 we ran the package with a stub in place of the script from the Paddle CDN and logged what it called:

The loader still returns the instance when Initialize() throws. The failure is a console warning and nothing else, so a bad option shows up only in the browser console.

initializePaddle({ token: "test_..." })
  -> Initialize(token=test_...)
initializePaddle({ environment: "sandbox", token: "test_..." })
  -> Environment.set(sandbox), Initialize(token=test_...)
the same call a second time
  -> Environment.set(sandbox), Update
Initialize() throws
  -> [Paddle] Paddle Initialization failed. Please check the inputs
run on the server, with no window
  -> [Paddle] Error Loading Paddle, and the promise resolves undefined

Why paddle.Checkout.open() can do nothing on Vercel

The loader README keeps the instance in state and calls paddle?.Checkout.open(). Until the CDN script has loaded, and on the server, that state is undefined, so the optional chain turns the click into nothing. Disable the button until the instance exists, and log the checkout.error event. Paddle says errors occur when the data passed to Paddle.js stops a checkout from opening at all, and the payload carries a type, a code and a detail string. The wording of detail can change, so do not branch on it.

A Next.js app adds a second trap. A NEXT_PUBLIC_ variable is inlined into the JavaScript bundle by next build, and the Next.js docs say the app no longer responds to changes in it after it is built. Vercel also applies a changed variable only to new deployments. So fixing the token in the Vercel dashboard changes nothing on the deployment that is already live.

"use client"
import { useEffect, useState } from "react"
import { initializePaddle, type Paddle } from "@paddle/paddle-js"

export function BuyButton({ priceId }: { priceId: string }) {
  const [paddle, setPaddle] = useState<Paddle>()
  useEffect(() => {
    initializePaddle({
      environment: process.env.NEXT_PUBLIC_PADDLE_ENV === "sandbox" ? "sandbox" : undefined,
      token: process.env.NEXT_PUBLIC_PADDLE_CLIENT_TOKEN!,
      eventCallback: (event) => {
        if (event.name === "checkout.error") console.error(event)
      },
    }).then(setPaddle)
  }, [])
  return (
    <button disabled={!paddle} onClick={() => paddle?.Checkout.open({ items: [{ priceId, quantity: 1 }] })}>
      Buy
    </button>
  )
}

Which token goes with which environment

Tokens are made per account, under Settings, Authentication, Client-side tokens: in sandbox-vendors.paddle.com for sandbox and in vendors.paddle.com for live. Paddle says sandbox tokens work only in sandbox accounts and live tokens only in live accounts, and never to use an API key with Paddle.js. For live accounts the docs also list a domain approved under Website approval, while in sandbox the checkout opens on any domain, including localhost. A checkout that opens on localhost and not on your live domain therefore points first at domain approval, not at the environment. The variable names below are your own choice.

Preview and Development   NEXT_PUBLIC_PADDLE_CLIENT_TOKEN=test_...   NEXT_PUBLIC_PADDLE_ENV=sandbox
Production                NEXT_PUBLIC_PADDLE_CLIENT_TOKEN=live_...   (no NEXT_PUBLIC_PADDLE_ENV)

Checklist

How to fix it, then check the fix

1. 01
   Find a Paddle client-side token the repo does not document. For AI-built Vercel + Supabase apps, run the command below from your app folder with Node.js 20 or newer. When code reads process.env.NEXT_PUBLIC_PADDLE_CLIENT_TOKEN and .env.example does not list it, it reports env_var_drift as a warning that names the variable, but it cannot see the variables set in Vercel, so it cannot tell which environment holds a test_ token and which a live_ one. It is a repository check, not a live database test: it does not open your checkout or contact Paddle.

   npx -y viberaven@1.7.1 check

2. 02
   Find where the token and the environment are set, including committed .env files:

   grep -rnE "initializePaddle|Paddle.Initialize|Environment.set|PADDLE" --exclude-dir=node_modules --exclude-dir=.next .

3. 03Make the token prefix and the environment agree: test_ with environment: "sandbox", live_ with no environment option. Open the checkout with a price ID from the same Paddle account the token came from.
4. 04In Vercel, give Preview and Development the test_ token and the sandbox flag, give Production the live_ token, and leave the sandbox flag out of Production.
5. 05Redeploy so Next.js builds again with the new values. A changed variable does not reach a deployment that already exists.
6. 06Keep the button disabled until initializePaddle() has returned an instance, and pass an eventCallback that logs checkout.error, so its type, code and detail reach the browser console.
7. 07Open the checkout on the deployed URL. It should load, and the console should show no "[Paddle] Paddle Initialization failed" warning.

Related

Related guides

• Paddle[Paddle] Webhook signature verification failedGuide
• Are NEXT_PUBLIC_ environment variables exposed to the browser?Guide
• VercelWhich env vars does my app read that are missing in Vercel production?Guide

Sources

Official docs behind this checklist

• Paddle, Manage client-side tokens
• Paddle, Include and initialize Paddle.js
• Paddle, Paddle.js overview (sandbox tokens, Website approval)
• Paddle, Paddle.Environment.set()
• Paddle, Paddle.Initialize()
• Paddle, Paddle.Checkout.open()
• Paddle, checkout.error event
• Paddle.js wrapper, src/utils/initialize.ts
• Paddle.js wrapper, src/index.ts
• Next.js, Environment variables
• Vercel, Environment variables

FAQ

FAQ for builders before launch