Paddle User Management API Guide

Auth method: API Key (Bearer token) – Paddle uses server-side API keys passed as Bearer tokens in the Authorization header. No OAuth 2.0 flow is documented for server-to-server calls.

Setup steps

1. Log in to the Paddle dashboard (sandbox: sandbox-vendors.paddle.com; production: vendors.paddle.com).
2. Navigate to Developer Tools > Authentication.
3. Generate an API key (default key or a named key with restricted permissions).
4. Store the key securely; it is shown only once.
5. Include the key in every request: Authorization: Bearer {API_KEY}.
6. For sandbox testing, use base URL https://sandbox-api.paddle.com and a sandbox API key.

Required scopes

List customers

• Method: GET
• URL: https://api.paddle.com/customers
• Watch out for: Pagination is cursor-based; use meta.pagination.next as the after param. Filtering by email requires exact match.

Request example

GET /customers?per_page=50&status=active
Authorization: Bearer {API_KEY}

Response example

{
  "data": [{"id":"ctm_01h...","email":"user@example.com","name":"Jane Doe","status":"active"}],
  "meta": {"pagination":{"per_page":50,"has_more":true,"next":"ctm_01h..."}}
}

Get customer

• Method: GET
• URL: https://api.paddle.com/customers/{customer_id}
• Watch out for: Returns 404 if the customer_id does not exist in the environment (sandbox vs. production keys are separate).

Request example

GET /customers/ctm_01h...
Authorization: Bearer {API_KEY}

Response example

{
  "data": {"id":"ctm_01h...","email":"user@example.com","name":"Jane Doe","status":"active","custom_data":{}}
}

Create customer

• Method: POST
• URL: https://api.paddle.com/customers
• Watch out for: Duplicate email addresses are allowed; Paddle does not enforce email uniqueness across customers.

Request example

POST /customers
Authorization: Bearer {API_KEY}
Content-Type: application/json

{"email":"user@example.com","name":"Jane Doe","locale":"en-US"}

Response example

{
  "data": {"id":"ctm_01h...","email":"user@example.com","name":"Jane Doe","status":"active","created_at":"2024-01-01T00:00:00Z"}
}

Update customer

• Method: PATCH
• URL: https://api.paddle.com/customers/{customer_id}
• Watch out for: PATCH is partial; only supplied fields are updated. Setting custom_data to {} clears all custom metadata.

Request example

PATCH /customers/ctm_01h...
Authorization: Bearer {API_KEY}
Content-Type: application/json

{"name":"Jane Smith","custom_data":{"plan":"pro"}}

Response example

{
  "data": {"id":"ctm_01h...","email":"user@example.com","name":"Jane Smith","status":"active"}
}

List addresses for customer

• Method: GET
• URL: https://api.paddle.com/customers/{customer_id}/addresses
• Watch out for: Addresses are sub-resources; they must be managed separately from the customer object.

Request example

GET /customers/ctm_01h.../addresses
Authorization: Bearer {API_KEY}

Response example

{
  "data": [{"id":"add_01h...","country_code":"US","postal_code":"10001","status":"active"}]
}

Create address for customer

• Method: POST
• URL: https://api.paddle.com/customers/{customer_id}/addresses
• Watch out for: country_code is required and must be a valid ISO 3166-1 alpha-2 code.

Request example

POST /customers/ctm_01h.../addresses
Authorization: Bearer {API_KEY}
Content-Type: application/json

{"country_code":"US","postal_code":"10001"}

Response example

{
  "data": {"id":"add_01h...","country_code":"US","postal_code":"10001","status":"active"}
}

List subscriptions for customer

• Method: GET
• URL: https://api.paddle.com/subscriptions?customer_id={customer_id}
• Watch out for: Subscriptions are not nested under /customers; filter via query param on the /subscriptions endpoint.

Request example

GET /subscriptions?customer_id=ctm_01h...
Authorization: Bearer {API_KEY}

Response example

{
  "data": [{"id":"sub_01h...","status":"active","customer_id":"ctm_01h...","current_billing_period":{}}]
}

Get customer portal session (magic link)

• Method: POST
• URL: https://api.paddle.com/customers/{customer_id}/portal-sessions
• Watch out for: Portal session URLs are single-use and expire. Do not cache or reuse them.

Request example

POST /customers/ctm_01h.../portal-sessions
Authorization: Bearer {API_KEY}
Content-Type: application/json

{"subscription_ids":["sub_01h..."]}

Response example

{
  "data": {"id":"cpls_01h...","customer_id":"ctm_01h...","urls":{"general":{"overview":"https://customer-portal.paddle.com/..."}},"created_at":"2024-01-01T00:00:00Z"}
}

• Rate limits: Paddle enforces rate limits per API key. The documented limit is 100 requests per second per API key for the Paddle Billing API. Exceeding the limit returns HTTP 429.
• Rate-limit headers: Yes
• Retry-After header: Yes
• Rate-limit notes: HTTP 429 is returned when the limit is exceeded. Paddle recommends exponential backoff. Specific header names (e.g., X-RateLimit-Limit, Retry-After) are referenced in the API overview but exact header names should be confirmed against live responses.
• Pagination method: cursor
• Default page size: 50
• Max page size: 200
• Pagination pointer: after (cursor-based; use the has_more flag and meta.pagination.next cursor from the response)

• Webhooks available: Yes
• Webhook notes: Paddle sends signed HTTP POST webhooks to a configured endpoint for all major billing and customer lifecycle events. Webhook payloads are signed with HMAC-SHA256 using a secret key configurable in the dashboard.
• Alternative event strategy: Polling the /customers and /subscriptions endpoints with updated_at filters can substitute for webhooks in low-volume scenarios.
• Webhook events: customer.created, customer.updated, subscription.created, subscription.updated, subscription.canceled, subscription.paused, subscription.resumed, subscription.past_due, transaction.created, transaction.updated, transaction.completed, transaction.payment_failed, address.created, address.updated

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not documented
• Endpoint: Not documented

Limitations:

• Paddle does not offer a SCIM 2.0 API. User/customer provisioning must be done via the Paddle REST API directly.
• No public documentation for SSO or SCIM integration exists as of the policy date.

The primary integration pattern for identity graph maintenance is mapping Paddle's ctm_-prefixed customer ID to your internal user record at creation time.

POST /customers to create a billing contact, store the returned ctm_ ID against your user record, and use it as the stable join key for all downstream subscription and transaction calls.

Paddle does not enforce email uniqueness - multiple customer records can share the same email address - so deduplication must be owned by the caller before issuing a POST.

For profile sync, use PATCH /customers/{customer_id} with only changed fields; sending custom_data: {} in any PATCH payload will silently clear all existing custom metadata. For subscription lifecycle sync, configure signed webhooks (HMAC-SHA256 via the Paddle-Signature header) and listen for customer.

updated, subscription. created, subscription.

updated, and subscription. canceled; implement idempotency on the event id field to handle Paddle's exponential-backoff retry behavior.

Pagination across /customers and /subscriptions is cursor-based: use meta. pagination.

next as the after parameter, with a default page size of 50 and a maximum of 200.

Provision a new customer on signup

1. POST /customers with email, name, and any custom_data (e.g., internal user ID).
2. Store the returned ctm_ ID in your application database mapped to the internal user record.
3. Optionally POST /customers/{customer_id}/addresses if billing address is collected at signup.
4. Use the ctm_ ID in subsequent transaction or subscription creation calls.

Watch out for: Paddle does not enforce email uniqueness. Always check your own database for an existing ctm_ ID before creating a new customer to avoid duplicates.

Update customer profile on user account change

1. Retrieve the stored ctm_ ID for the user from your database.
2. PATCH /customers/{customer_id} with only the changed fields (name, locale, custom_data, etc.).
3. Handle 404 gracefully in case the customer was archived or the ID is stale.

Watch out for: Sending custom_data: {} in a PATCH will clear all existing custom metadata. Only include custom_data in the payload if you intend to update it.

Sync customer subscription status to your application

1. Configure a webhook endpoint in the Paddle dashboard and note the webhook secret.
2. Listen for customer.updated, subscription.created, subscription.updated, and subscription.canceled events.
3. Verify the Paddle-Signature header on each inbound webhook using HMAC-SHA256 and your webhook secret.
4. Extract customer_id and subscription status from the payload and update your application database.
5. Return HTTP 200 promptly; process asynchronously if needed to avoid timeout-triggered retries.

Watch out for: Paddle retries failed webhook deliveries with exponential backoff. Implement idempotency using the event id field to avoid processing duplicate events.

There is no SCIM 2.0 API and no public SSO documentation for Paddle - provisioning and deprovisioning of dashboard team members has no programmatic path. The Paddle API manages billing contacts (customers), not application-level user accounts; there is no concept of user passwords, sessions, or application roles in the API surface.

This distinction matters for identity graph integrations: ctm_ records represent payers, not authenticated users, and the two must be explicitly joined in your own data layer. custom_data fields accept only string values - nested objects will return a validation error.

Portal session URLs (magic links, generated via POST /customers/{customer_id}/portal-sessions) are single-use and short-lived; they must be generated on demand and never cached.

For teams building on top of Paddle through an MCP server with 60+ deep IT/identity integrations, the absence of SCIM means any identity lifecycle automation must be constructed entirely against the REST API with caller-managed deduplication and no standardized provisioning contract.