Become a Paddle partner
Join the Paddle partner program to read this content. You'll also get access to our partner API and agent tooling. Let us know a few details about your business to get started. Already a partner? Log in to view this page.
When a user is ready to monetize their app, you can check they're eligible and guide them through the Paddle signup process by collecting their details. You can do all of this through the partner API, so users don't have to leave your platform.
You'll typically want to start the onboarding process when a user says something like, "I want to add payments to my app."
When a signup is attributed to a partner, we suppress our usual emails and other flows so you can handle onboarding in your platform.
Overview
Onboard a seller in three steps:
- Check that a seller is eligible for Paddle
Screen out users that are likely to fail verification later in the process, like companies selling physical goods. - Collect their details and pre-validate them
Before creating a seller, check that their email, business, and other details are valid. - Create a seller account and store API keys
Send a request to create a seller, store details your side, then store their API keys securely.
Check that a seller is eligible for Paddle
- Layer
- Your agent
Before you present a user with the option to monetize with Paddle, you should first check:
- Are they based in a supported country?
- Do they want to sell a supported category of product?
If a seller is based in a country we don't support, or they're selling products that fall outside of Paddle's acceptable use policy (AUP), then you should block them in your frontend before they start the onboarding process.
Physical goods, non-digital products, and regulated professional advice are the top reasons for product category verification failures in embedded billing integrations.
Preventing users who aren't eligible for Paddle from starting the onboarding process means that they won't build an integration with Paddle that they're not allowed to use.
Collect user details and prevalidate
- Layer
- Your platform
- Authentication
- Partner API key
- Environment
- Sandbox, Live
Once you've checked a user's eligibility, build a workflow in your frontend to capture their details. You should capture:
- First name and last name
- Email address
- Business name and address
- What kind of product they're building
- Confirmation that they accept the Paddle terms of service
For accuracy, we recommend collecting this using a modal or form launched by your chat, rather than in the agent chat itself.
You can prefill the payload with data you already know about the user, or data they supplied during the chat, but we recommend allowing them to review and change the values.
Pre-validate and surface feedback
Build a payload with the information you collected, then send a POST request to the /accounts/validate endpoint. This operation performs the same validation as when you create a Paddle account, but doesn't create the account. Make this request to both the sandbox and live endpoints.
If successful, it returns 204 with no body. If there's a problem, Paddle returns an error object with details of what went wrong.
{ "user": { "first_name": "Sam", "last_name": "Miller", "email": "sam@example.com", "marketing_consent": false }, "business": { "name": "AeroEdit", "address": { "country_code": "GB" } }, "display_name": "AeroEdit", "product_categories": ["apps"], "accepted_terms_of_service": true}{ "error": { "type": "request_error", "code": "invalid_field", "detail": "Request does not pass validation", "documentation_url": "https://developer.paddle.com/v1/errors/shared/invalid_field", "errors": [ { "field": "user.email", "message": "user.email may be invalid or already associated with an existing account." } ] }, "meta": { "request_id": "970bc7bc-6428-47df-9d8e-185e0b96e2ab" }}Common problems to handle in your frontend:
- Email already in use: Email addresses must be unique. You should validate an email against both sandbox and live and reject if it exists in one environment. You can suggest using an alias, like
sam+paddle@example.com. - Business name conflict: There's already a seller with this business name using Paddle. Use another.
- Invalid characters in business name: Names with punctuation aren't allowed. This is mainly colons, like
"Habitual: Track Your Day". Strip or sanitize before submission, or tell users to remove them.
An email address in Paddle may exist in one environment but not another. You should use the same email address in sandbox and live. Validate an email against both sandbox and live and reject if it exists in either environment.
Revalidate once the user has supplied updated information.
Create a seller account and store API keys
- Layer
- Your platform
- Authentication
- Partner API key
- Environment
- Sandbox, Live
When validation comes back successful on both sandbox and live environments, send a POST request to the /accounts endpoint to create the account. Make this request to both the sandbox and live endpoints.
The payload at this point is the same as during validation, but you can also include an external_id to link the account on Paddle to a record on your platform.
If successful, Paddle returns a 201 with the created account entity.
{ "user": { "first_name": "Sam", "last_name": "Miller", "email": "sam@example.com", "marketing_consent": false }, "business": { "name": "AeroEdit", "address": { "country_code": "GB" } }, "display_name": "AeroEdit", "product_categories": ["apps"], "accepted_terms_of_service": true, "external_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"}{ "data": { "id": "sel_01jqx8k5z9r2m4n6p8s0t2v4w6", "display_name": "AeroEdit", "user": { "id": "165042", "first_name": "Sam", "last_name": "Miller", "email": "sam@example.com", "marketing_consent": false }, "business": { "name": "AeroEdit", "type": null, "address": { "first_line": null, "second_line": null, "city": null, "postal_code": null, "region": null, "country_code": "GB" }, "registration_number": null, "stock_ticker_symbol": null }, "created_at": "2026-03-06T07:33:15.000000Z", "updated_at": "2026-03-06T07:33:17.000000Z", "api_key": "pdl_sdbx_apikey_01jqx8k5z9r2m4n6p8s0t2v4w6_aB3dEf5gHi7jKl9mNpQrS2_Xyz", "user_api_key": "pdl_sdbx_apikey_01jqy2m7b4c6d8e0f2g4h6j8k0_zZ9yX8w7V6u5T4s3R2q1P0_oNm" }, "meta": { "request_id": "87df0819-0213-44c5-90d7-f15162738a9c" }}The format for data.user.id may change. Paddle currently returns an integer as a string, but we're migrating to a Paddle ID format (usr_). Don't parse this value or assume an integer.
Store data and API keys securely
We recommend storing the id for both sandbox and live accounts against the account in your database. If your platform supports multiple users, you should also store the user.id against your user record. This identifies the particular Paddle user that initiated the onboarding process.
The response contains two API keys that must be stored securely:
api_key: Lets you take action on behalf of the seller. Use this key for creating products, prices, discounts, and other data in this Paddle account.user_api_key: Lets you take action on behalf of the user. Use this to generate pre-authenticated magic links to log the user into the Paddle dashboard.
Store these keys securely. They grant full access to a seller's Paddle account. If keys are exposed on GitHub, Paddle automatically revokes them.