Create a seller account

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:

1. 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.
2. Collect their details and pre-validate them
   Before creating a seller, check that their email, business, and other details are valid.
3. 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.

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.

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.

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"
  }
}

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.