Paddle

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the Paddle Billing API for test suites. Customers, addresses, businesses, products and prices behave as Paddle's do (validation, invalid_field errors, include=, cursor pagination). Transactions carry computed totals. Subscriptions are created the way Paddle creates them, when a transaction with recurring prices is paid, and the emulator's admin routes stand in for the hosted checkout and the billing engine: pay a transaction, complete a checkout in one call, run a renewal, fail a payment. Every change produces the event Paddle would emit, listed at GET /events and delivered as a Paddle-Signature webhook that the official SDK's paddle.webhooks.unmarshal verifies.

• Operation coverage: SUPPORT.md
• openapi.yaml is hand-authored from Paddle's API reference and the wire types of @paddle/paddle-node-sdk@3.10.0.

#Install

npm install -D @crvouga/mockingbird-service-paddle

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-paddle serve, createServer from ./server (Node), or createRuntime with any Fetch server.

#Usage

The SDK maps environment to a base URL and otherwise uses the value verbatim, so point it at the emulator by passing the emulator's URL as the environment. Give the app the same pdl_ntfset_… secret as --webhook-secret.

npx mockingbird-paddle serve --port 8795 --fixtures \
  --webhook-url http://127.0.0.1:3000/webhooks/paddle \
  --webhook-secret "$PADDLE_WEBHOOK_SECRET" \
  --payment-link https://pay.example.com/checkout
PADDLE_API_BASE_URL=http://127.0.0.1:8795 node app.js

import { createServer } from "@crvouga/mockingbird-service-paddle/server"
import { type Environment, Paddle } from "@paddle/paddle-node-sdk"

const emulator = await createServer({ paymentLink: "https://pay.example.com/checkout" })
// The app's own Paddle client. Only its environment changes.
const paddle = new Paddle("pdl_sdbx_apikey_test", { environment: emulator.url as Environment })

const product = await paddle.products.create({ name: "Pro plan", taxCategory: "saas" })
const price = await paddle.prices.create({
  productId: product.id,
  description: "Pro monthly",
  unitPrice: { amount: "2900", currencyCode: "USD" },
  billingCycle: { interval: "month", frequency: 1 },
})
const customer = await paddle.customers.create({ email: "ada@example.com" })
const address = await paddle.addresses.create(customer.id, { countryCode: "US" })
const transaction = await paddle.transactions.create({
  items: [{ priceId: price.id, quantity: 2 }],
  customerId: customer.id,
  addressId: address.id,
})
// transaction.status === "ready", transaction.details.totals.grandTotal === "5800",
// transaction.checkout.url === "https://pay.example.com/checkout?_ptxn=txn_…"

// The customer pays on the hosted checkout: the emulator's admin route stands in for it.
await fetch(`${emulator.url}/__admin/transactions/${transaction.id}/pay`, { method: "POST" })
const [subscription] = await paddle.subscriptions.list({ customerId: [customer.id] }).next()
// subscription.status === "active", subscription.nextBilledAt one month out
await emulator.close()

With fixtures: true the catalog is already seeded, and one admin call completes a checkout:

import { createServer } from "@crvouga/mockingbird-service-paddle/server"
import { type Environment, Paddle } from "@paddle/paddle-node-sdk"

const emulator = await createServer({ fixtures: true })
const paddle = new Paddle("pdl_sdbx_apikey_test", { environment: emulator.url as Environment })
const [product] = await paddle.products.list({ include: ["prices"] }).next()

// Test setup: one admin call stands in for a customer completing the hosted checkout.
const completed = await fetch(`${emulator.url}/__admin/checkout`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ email: "new@example.com", items: [{ price_id: product?.prices?.[0]?.id }] }),
})
const checkout = (await completed.json()) as { transaction: { id: string }; subscription: { id: string } }

const transaction = await paddle.transactions.get(checkout.transaction.id)
const subscription = await paddle.subscriptions.get(checkout.subscription.id)
// transaction.status === "completed", subscription.status === "trialing" (the fixture price has a trial)
await emulator.close()

#Routes

Every response is Paddle's envelope: {data, meta: {request_id}}, lists add meta.pagination: {per_page, next, has_more, estimated_total}. Lists take after=<id> (the cursor in next, an absolute URL the SDK follows as-is), per_page (default 50, max 200; transactions 30; more than the maximum gets the maximum, as Paddle documents) and order_by=id[ASC]|id[DESC] (default newest first). Errors are {error: {type, code, detail, documentation_url, errors?: [{field, message}]}, meta}.

Auth is Authorization: Bearer <key>; any key works. No header is 403 authentication_missing, a non-Bearer header is 403 authentication_malformed. Validation failures are 400 invalid_field with errors: [{field, message}] (email: required field); a malformed JSON body is 400 invalid_json; unknown entities are 404 not_found (Entity ctm_… not found). Ids look like Paddle's (ctm_01…, pri_01…, txn_01…, sub_01…, evt_01…: a prefix and 26 lower-case alphanumerics) and are deterministic for a given history.

#Checkout and billing (admin)

Paddle has no API to pay a transaction or create a subscription: the hosted checkout does that, and the billing engine renews. These routes stand in for them (all under /__admin, namespaced like everything else):

--fixtures (or createRuntime({fixtures: true})) seeds every namespace on first use, and again after every reset, with: Ada Lovelace (ada@example.com, a US address, a business), a Pro plan product with monthly ($29), yearly ($290) and one-time onboarding ($99) prices, a Starter plan with a 14-day trial ($19/month), an active monthly subscription, a trialing Starter subscription (Grace Hopper, grace@example.com), an unpaid ready transaction and a billed manual invoice. seedFixtures() returns the records; seeding a namespace twice clashes on the emails. Fixture events are listed (GET /events) but never delivered as notifications: they are the account's pre-existing state, not activity.

#Webhooks

Every event is published to the configured endpoints as Paddle's notification body:

{"event_id": "evt_01…", "event_type": "subscription.created", "occurred_at": "…",
 "notification_id": "ntf_01…", "data": {"id": "sub_01…", "status": "active", "transaction_id": "txn_01…", "items": [ … ], … }}

Types: customer|address|business|product|price.created|updated, transaction.created|ready| billed|paid|completed|canceled|payment_failed|past_due|updated, subscription.created| activated|trialing|updated|paused|resumed|canceled|past_due. Each delivery carries Paddle-Signature: ts=<unix seconds>;h1=<hex HMAC-SHA256(secret, "<ts>:<raw body>")> with a wall-clock ts (even when the emulator clock moves), which paddle.webhooks.unmarshal(body, secret, signature) and isSignatureValid accept. Non-2xx answers are retried (immediately, 5 s, 5 min, 30 min, 2 h). GET /__admin/webhooks, …/events, …/flush, …/:id/replay and PUT /__admin/webhook-endpoints (per-namespace receivers, events: ["subscription.*"]-style filters are exact types or *) come with the contract.

Fault presets (POST /__admin/faults {"preset": "<name>", "count"?: n}; GET /__admin/faults/presets): invalid_token (403 on every request), rate_limited (429 too_many_requests with retry-after: 2, the SDK's ApiError.retryAfter), transactions_500 (POST /transactions answers 500 internal_error), bad_gateway_html (reads answer a 502 HTML page), network_drop (POST /transactions drops the connection), webhook_duplicate, webhook_reorder, webhook_drop.

#Namespaces

new Paddle(key) cannot add a namespace header on its own (it can with customHeaders), so map API keys to namespaces: PUT /__admin/credentials {"credentials": {"<PADDLE_API_KEY>": "<namespace>"}}. Also x-mockingbird-namespace, or a /__admin/ns/<name> prefix on the base URL (meta.pagination.next keeps it).

#Deliberately not modelled

• Tax and discounts. Totals carry tax: "0" and discount: "0" whatever the address or tax_mode; there are no discounts, discount groups or adjustments (refunds, credits), and no credit balances. unit_price_overrides are honoured for the address's country.
• Proration. Changing a subscription's items with a *_immediately mode bills what the change adds in full, credits nothing for what it removes; the next-period modes bill nothing now. PATCH /subscriptions/{id}/preview and …/charge/preview are unsupported.
• The hosted checkout, customer portal pages and Paddle.js. checkout.url, management_urls and portal-session links are URLs, not pages; POST /__admin/checkout and …/pay replace the checkout. POST /customers/{id}/portal-sessions returns the temporary https session links.
• Payment methods and payment method changes, payouts, reports, simulations, invoice revisions, the imported events, API key events and client tokens.
• Notification destinations are the vendor API (GET|POST /notification-settings, GET|PATCH /notification-settings/{id}). An active url destination is delivered with its own pdl_ntfset_… secret. The secret is returned on create only. --webhook-url and PUT /__admin/webhook-endpoints stay as extra receivers and are not replaced by the vendor list.
• Time. Nothing renews on its own: call …/renew (or …/payment-failed) when the test's clock reaches next_billed_at. Retry schedules for past-due subscriptions are not modelled.
• Rate limits, except through rate_limited. Legacy (pre-2025) API key formats are accepted like any other key.

#API

Part of mockingbird.