Build with Codex

Codex is OpenAI's AI coding agent. It runs as a CLI, an IDE extension, and on the web.

This guide runs through setting up Codex for the best possible experience when building with Paddle.

Before you begin

You'll need:

• A Paddle account that you want to connect to — sandbox, live, or both.
• If connecting to a sandbox account, a sandbox API key with any permissions you plan to use.
• Codex installed.
• A project, with a Paddle SDK installed.

Install the Paddle plugin

The Paddle plugin bundles Paddle agent skills with the docs MCP server and Paddle MCP servers.

From your terminal, run:

codex plugin marketplace add PaddleHQ/paddle-agent-skills

Then open Codex and install the paddle plugin from the plugin directory.

To refresh later, run codex plugin marketplace upgrade paddle-agent-skills.

Connect the Paddle MCP servers

The plugin wires up two Paddle MCP servers so the agent can work in both sandbox and live environments. This is useful for porting data from one to the other.

paddle-sandbox reads a sandbox API key from an environment variable. Create a key at Paddle > Developer tools > Authentication, then export it in your shell profile (~/.zshrc, ~/.bashrc, or equivalent):

export PADDLE_SANDBOX_API_KEY= # Your sandbox API key

Restart Codex and your terminal after setting the variable so the MCP server picks it up.

paddle-live uses OAuth, so there's no API key to set. Authorize it in your browser:

codex mcp login paddle-live

Add Paddle conventions to your AGENTS.md

Codex reads project conventions from AGENTS.md at the project root. A focused Paddle section tells it which SDK to use, how to handle environments, and how to verify webhooks.

Create an AGENTS.md file at the project root, or add this to your existing AGENTS.md file.

## Paddle integration

When writing or modifying code that integrates with Paddle:

- Always check current Paddle documentation via the `paddle-docs` MCP server before suggesting code. The Paddle API and SDKs evolve frequently — do not rely on training data alone.
- Use the official Paddle SDK for the language in use:
  - Node.js → `@paddle/paddle-node-sdk`
  - Python → `paddle-python-sdk` (imports as `paddle_billing`)
  - Go → `github.com/PaddleHQ/paddle-go-sdk/v5`
  - PHP → `paddlehq/paddle-php-sdk`
- All development uses the sandbox environment. Sandbox API keys contain `_sdbx`; sandbox client-side tokens are prefixed with `test_`.
- Always verify webhook signatures before acting on the payload:
  - Node: `paddle.webhooks.unmarshal()`
  - Python: `Verifier().verify(request, secret)`
  - Go: `paddle.NewWebhookVerifier()` with `Middleware`
  - PHP: `(new Verifier())->verify($request, $secret)`
- For destructive account changes (updating prices, archiving products, canceling subscriptions), ask for explicit confirmation before calling the `paddle-sandbox` or `paddle-live` MCP server.
- Use `paddle-sandbox` by default. Only call `paddle-live` when the prompt explicitly mentions live, production, or real customer data.
- API keys and webhook secrets live in environment variables — never inline credentials into code.

Adjust the SDK list to match the languages your project uses. Codex will read this every time you start a session.

Prompt your first integration

With the plugin installed, the Paddle MCP server connected, and your AGENTS.md file in place, ask Codex to scaffold a Paddle integration.

Add a Paddle Checkout integration to this Next.js app. Use the paddle-docs MCP server to look up the current Paddle.js syntax. Then use the paddle-sandbox MCP server to create three products in my sandbox account — Starter ($10/mo), Pro ($30/mo), Enterprise ($300/mo) — and generate a /pricing page that opens checkout for each tier. Wire up a /api/webhooks route that verifies the signature and logs transaction.completed events.

Codex plans first, then uses the docs MCP for current syntax, the Paddle MCP to create the products in sandbox, and writes code that matches your AGENTS.md conventions.

Best practices

• Mention Paddle and the relevant MCP server explicitly.
  "Use the paddle-docs MCP server to look up X" beats hoping the agent calls it on its own.
• Be specific in prompts.
  Concrete pricing, event names, and entity IDs work better than vague descriptions.
• Review changes before applying.
  Codex shows pending tool calls before executing. Review every tool call, especially anything destructive.
• Never commit API keys.
  Keep API keys in environment variables.
• Create your own skills.
  When you find yourself repeating the same instructions over and over, package them as a skill. Run the $plugin-creator skill in Codex to walk through it.