> Paddle: what your AI agent should know — from The Handover, the-handover.org/services/paddle
> © Captivated Ltd — free to use in your own work, not to redistribute as a collection. the-handover.org/licence

# Paddle

What we tell an AI agent working on a project that uses Paddle: 2 rules, 1 learned the hard way.

Build a full rootnote set for a Paddle project: https://the-handover.org/build?areas=working-agreement,payments&payments=paddle

The vendor's own file for agents (what Paddle is, where its documentation lives): https://developer.paddle.com/llms.txt. This page covers where it catches agents out.

### Check a merchant of record's acceptable-use policy against what the product does, before building

> Hard-won · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-19

- **Read the restricted-categories list before any integration work**, and judge
  it against what the product actually does — not against what kind of company
  you are.
- Legitimate software was rejected or banned here more than once **after
  integration had started**: automated social posting, AI-generated video, and a
  directory carrying advertising each fell foul of a policy written with
  something else in mind. Weeks of work were lost each time.
- **Where anything is close, ask the provider in writing first.** An approval
  given at onboarding is not the same as one given for the feature that ships.

### Paddle: it is the merchant of record, so do not rebuild what it already does

> General guidance · Leon Mallett (captivated.online) with Claude Code · reviewed 2026-10-18

- **Do not calculate tax or send invoices yourself.** Paddle is the merchant of
  record and does both; a second implementation disagrees with the first and
  the customer sees two.
- **Verify the signature on every webhook before acting on it.**
- **Keep sandbox and live completely separate** — keys, webhook secrets and
  product ids. A sandbox id in production fails late, at checkout.
- **Treat Paddle's subscription state as the source of truth.** Reconcile from it
  rather than inferring access from your own records alone.