.png)
Paddle Integration Guide
Connect Paddle Billing with enterprise applications through its REST API, authenticated webhook notifications, and Martini workflows.
Paddle integration options at a glance
Paddle Billing provides a versioned REST API for Products, Prices, Customers, Transactions, Subscriptions, Businesses, Addresses, and related billing resources. It also sends authenticated webhook notifications for selected transaction, subscription, customer, catalog, and adjustment events. Collection endpoints use pagination, so larger synchronizations require checkpoints, retries, and reconciliation logic rather than a general bulk API. Server-side requests use bearer API keys, while webhook requests include a Paddle-Signature header that must be verified. Martini can consume the REST API, receive webhook notifications, validate and transform payloads, orchestrate downstream workflows, and securely manage credentials and webhook secrets.
| Integration point | Supported by Paddle? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Paddle’s versioned REST API supports Products, Prices, Customers, Transactions, Subscriptions, Businesses, Addresses, adjustments, and related billing resources. It is the primary mechanism for retrieval and server-to-server operations. | Martini can consume Paddle REST endpoints from workflows, manage pagination and checkpoints, transform responses, apply business rules, and send results to downstream APIs or databases. |
| Webhooks and outbound callbacks | Yes | Paddle sends webhook notifications for selected transaction, subscription, customer, catalog, adjustment, address, and business lifecycle events. Coverage is event-specific rather than an unrestricted change feed. | Martini can expose a receiving API or webhook-triggered workflow, validate the Paddle-Signature header, deduplicate event IDs, route event types, and process downstream actions synchronously or asynchronously. |
| Authentication | Yes | Server-side Paddle API requests use bearer API keys. Webhook requests include a Paddle-Signature header that receiving systems should verify against the configured notification secret. | Martini can store API keys and webhook secrets in secure configuration, apply authorization headers to REST requests, and implement signature validation before business processing. |
| Bulk, asynchronous, or batch processing | Limited | Paddle supports paginated collection retrieval and asynchronous webhook-driven lifecycle processing, but a general-purpose bulk mutation API was not confirmed. | Martini can implement page-by-page extraction, synchronization checkpoints, overlap windows, bounded retries, and reconciliation workflows for larger data volumes. |
| JSON handling | Yes | Paddle REST responses and webhook notifications are exchanged as structured API payloads containing billing object fields and event metadata. | Martini can parse, validate, map, transform, enrich, and route Paddle JSON within workflows and APIs. |
| File and attachment APIs | Not confirmed | A general-purpose file or attachment API for Paddle Billing objects was not confirmed. Product imagery and related metadata should not be treated as a general attachment mechanism. | Martini should use confirmed Paddle REST resources or supported downstream file mechanisms rather than assuming a Paddle attachment API. |
| Database access | No | Paddle does not expose direct access to its internal billing database for integrations. Reporting and financial data should come through APIs, webhooks, exports, or supported reporting facilities. | Martini can write transformed Paddle data to a supported SQL database when an integration-owned data store or warehouse is required. |
How Paddle exposes data and business events
Paddle REST APIs
Paddle Billing provides a versioned REST API over HTTPS for catalog, customer, transaction, subscription, business, address, and adjustment resources. Collection endpoints are paginated, and API permissions should be limited to the operations required by the integration.
Martini implementation pattern
Martini uses a workflow to authenticate with a securely stored Paddle API key, call the required endpoint, follow pagination, and transform the response into a canonical or target-system model. The workflow can store checkpoints, apply business rules, and route transient failures to bounded retry handling.
Implementation sequence
Paddle Webhooks
Paddle sends webhook notifications for selected transaction, subscription, customer, catalog, adjustment, address, and business events. Delivery is asynchronous and may be retried, so event coverage and ordering should not be assumed to be universal.
Martini implementation pattern
Martini exposes a receiving API or webhook-triggered workflow for Paddle notifications. The workflow verifies the Paddle-Signature header before parsing the payload, records the event identifier, routes by event type, and retrieves the current Paddle object when the notification alone is not sufficient.
Implementation sequence
Paginated synchronization
Paddle does not provide a confirmed general-purpose bulk mutation API, so larger extracts should use paginated REST endpoints with checkpoints, overlap windows, rate-limit handling, and reconciliation logic.
Martini implementation pattern
Martini runs a scheduled workflow that retrieves Paddle collections page by page, records the last successful checkpoint, transforms each object, and writes it to the target system. A time overlap can capture late-arriving changes when downstream processing is idempotent.
Implementation sequence
Common Paddle integration patterns
Pattern 1: Sync Paddle subscriptions to a CRM
When to use this pattern
Use this pattern when sales, customer-success, or account teams need current subscription lifecycle information in Salesforce or HubSpot. Paddle webhook events provide near-real-time triggers, while REST retrieval provides authoritative current state when event ordering or payload coverage is insufficient.
Integration direction
Example Mapping
| Paddle Field | Canonical Field | Target Field |
|---|---|---|
| customer_id | customer.externalId | Account or Contact external ID |
| subscription.status | subscription.lifecycleStatus | Subscription status |
| subscription.items | subscription.planItems | Products or subscription line items |
| scheduled_change | subscription.pendingChange | Pending lifecycle change |
Martini implementation pattern
Martini validates the webhook signature, deduplicates the event, retrieves the current Customer and Subscription when needed, and maps Paddle lifecycle values to the CRM model. Customer matching prefers stable Paddle IDs, and failed updates are retried without repeating successfully completed actions.
Martini capabilities used
- workflows
- webhook consumption
- API consumption
- data mapping
- business rules
- error handling
Pattern 2: Reconcile Paddle transactions with accounting
When to use this pattern
Use this pattern when finance teams need Paddle purchases, charges, refunds, adjustments, taxes, and customer references in NetSuite, Xero, or QuickBooks Online. Scheduled incremental retrieval is suitable for reconciliation, with webhooks optionally supplementing the process.
Integration direction
Example Mapping
| Paddle Field | Canonical Field | Target Field |
|---|---|---|
| transaction.id | financialTransaction.externalId | External transaction ID |
| transaction.details.totals | financialTransaction.amounts | Transaction total |
| transaction.currency_code | financialTransaction.currency | Currency code |
| adjustment.type | financialTransaction.adjustmentType | Refund or credit type |
Martini implementation pattern
A scheduled Martini workflow follows Paddle pagination, uses a checkpoint and overlap window, preserves currency and decimal precision, and maps transaction and adjustment states to accounting objects. Stable external IDs and reconciliation reports prevent duplicate postings and highlight incomplete or rejected records.
Martini capabilities used
- scheduler triggers
- API consumption
- pagination orchestration
- data mapping
- validation
- retry handling
Pattern 3: Provision access after a successful Paddle purchase
When to use this pattern
Use this pattern when a successful transaction or active subscription should provision software access through an internal licensing, identity, or application API. Provisioning must depend on verified Paddle notifications and explicit transaction or subscription state rules.
Integration direction
Example Mapping
| Paddle Field | Canonical Field | Target Field |
|---|---|---|
| transaction.id | entitlement.sourceTransactionId | Purchase reference |
| customer.id | entitlement.customerId | Customer identifier |
| subscription.status | entitlement.status | Access status |
| subscription.items | entitlement.products | Licensed products |
Martini implementation pattern
Martini receives and verifies the Paddle event, checks the relevant transaction or subscription state, applies provisioning rules, and calls the internal API. The workflow records the Paddle event and target response, handles delayed payment states, and retries only operations protected by stable idempotency keys.
Martini capabilities used
- webhook-triggered workflows
- API orchestration
- business rules
- data transformation
- idempotency
- error handling
Pattern 4: Synchronize Paddle products and prices
When to use this pattern
Use this pattern when an internal catalog, commerce application, or warehouse must reflect Paddle Products and Prices. Scheduled synchronization is appropriate because price versions, currencies, billing intervals, and catalog relationships require controlled reconciliation.
Integration direction
Example Mapping
| Paddle Field | Canonical Field | Target Field |
|---|---|---|
| product.id | catalogProduct.externalId | Product external ID |
| product.name | catalogProduct.name | Product name |
| price.unit_price | catalogPrice.amount | Price amount |
| price.billing_cycle.interval | catalogPrice.billingInterval | Billing interval |
Martini implementation pattern
Martini retrieves paginated Products and Prices, normalizes relationships and commercial fields, validates currency and interval values, and writes changes to the target catalog or warehouse. Unknown optional fields are tolerated, while schema or mapping failures are logged for review.
Martini capabilities used
- scheduled workflows
- REST API consumption
- pagination
- mapping and transformation
- validation
- monitoring
Applications commonly integrated with Paddle
Paddle data can be routed to adjacent business applications for customer lifecycle management, financial reconciliation, support operations, analytics, and operational notifications. These are standards-based integration patterns rather than confirmed Paddle-certified application connectors.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize Paddle Customers, Transactions, and Subscriptions with accounts, contacts, and customer lifecycle records. | Paddle → Martini → Salesforce | Martini receives selected Paddle webhooks and supplements them with REST API retrieval when current object state is required. A workflow matches stable Paddle IDs, maps customer and subscription states, applies duplicate protection, and updates Salesforce with bounded retries. |
| HubSpot | Make customer and subscription lifecycle information available to sales, marketing, and customer-success teams. | Paddle → Martini → HubSpot | A Martini webhook workflow validates Paddle signatures, normalizes Customers and Subscriptions, and calls HubSpot APIs. Scheduled reconciliation can identify missed notifications and update lifecycle properties idempotently. |
| NetSuite | Reconcile Paddle Transactions, adjustments, refunds, taxes, currencies, and customer information with financial records. | Paddle → Martini → NetSuite | A scheduled Martini workflow retrieves paginated Transactions and relevant adjustments, stores a checkpoint, maps financial fields and currency codes, and writes records to NetSuite using stable transaction keys and retry-aware error handling. |
| Xero | Send transaction and refund information to support accounting and reconciliation processes. | Paddle → Martini → Xero | Martini consumes Paddle REST data or selected webhook events, preserves monetary precision, maps customer and transaction references, and calls Xero APIs. A durable cross-reference prevents duplicate accounting entries. |
| QuickBooks Online | Synchronize sales, payment, refund, and customer information with accounting workflows. | Paddle → Martini → QuickBooks Online | A Martini workflow transforms Paddle Transactions and adjustments into QuickBooks Online objects, validates required accounting fields, applies business rules for transaction status, and routes failures for controlled retry or review. |
| Zendesk | Give support agents subscription, transaction, and customer-status context when assisting Paddle customers. | Paddle → Martini → Zendesk | Paddle webhook events start a Martini workflow that retrieves current Customer or Subscription details when necessary, maps them to Zendesk customer or ticket context, and ignores already processed event IDs. |
| Snowflake | Centralize Paddle transaction, subscription, product, and price data for financial and customer analytics. | Paddle → Martini → Snowflake | Martini performs paginated and checkpointed Paddle extraction, normalizes JSON objects, preserves event and object identifiers, and writes structured data to Snowflake through a supported database or API pattern with reconciliation logging. |
| Slack | Notify finance, support, or operations teams about selected payment, subscription, refund, or catalog events. | Paddle → Martini → Slack | A Martini webhook workflow filters Paddle event types, applies business rules such as refund thresholds or subscription states, formats a concise notification, and sends it to Slack while preventing duplicate alerts. |
How to build a Paddle integration in Martini
Objective
Configure the Paddle API base URL, server-side API key, webhook secret, and environment-specific settings without embedding credentials in workflow definitions or source code.
Instructions in Martini
- Store the Paddle API key and webhook secret in Martini secure configuration.
- Use bearer authentication for server-side Paddle REST requests.
- Separate development, staging, and production credentials and webhook endpoints.
Objective
Select an event-driven, scheduled, or API-led entry point based on whether the integration needs near-real-time updates, reconciliation, or an on-demand operation.
Instructions in Martini
- Use a webhook-triggered workflow for selected Paddle lifecycle events.
- Use a scheduler trigger for paginated synchronization and reconciliation.
- Use a Martini API when another application must initiate a controlled Paddle operation.
Objective
Obtain the Paddle payload or resource state while accounting for signature validation, pagination, event-specific coverage, and possible event ordering differences.
Instructions in Martini
- Validate the Paddle-Signature header before processing webhook data.
- Call the relevant Paddle REST endpoint when authoritative current state is needed.
- Process collection responses page by page and persist a checkpoint.
Objective
Coordinate validation, enrichment, routing, target calls, and durable processing controls in a maintainable Martini workflow.
Instructions in Martini
- Route events by Paddle event type and object.
- Retrieve related Customers, Products, Prices, or Subscriptions when required.
- Separate prompt webhook acknowledgment from longer downstream processing where appropriate.
Objective
Convert Paddle Products, Prices, Customers, Transactions, Subscriptions, Businesses, and related data into the target system’s canonical model.
Instructions in Martini
- Map stable Paddle identifiers to target external IDs.
- Preserve currency codes and monetary precision.
- Normalize subscription states, billing intervals, customer references, and adjustment types.
Objective
Ensure downstream actions reflect verified Paddle state rather than relying on an unverified request or a single payment event.
Instructions in Martini
- Apply explicit rules for active, trialing, paused, past-due, and canceled subscriptions when relevant.
- Use idempotency checks based on event, transaction, and subscription identifiers.
- Validate required fields and route ambiguous or unsupported states for review.
Common Paddle data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Products | Defines software products or digital offerings being sold through Paddle. | Internal product catalogs, commerce applications, CRMs, data warehouses | Martini retrieves Products through the REST API or processes selected product events, maps catalog attributes, and synchronizes them using stable Paddle identifiers. |
| Prices | Defines billing terms, currency, amount, billing interval, and other pricing details associated with a Product. | Product catalogs, commerce applications, finance platforms, data warehouses | Martini maps currency, amount, interval, product relationship, and price version information while applying validation for required commercial fields. |
| Customers | Represents the customer associated with Paddle transactions and subscriptions. | Salesforce, HubSpot, Zendesk, accounting platforms, customer databases | Martini matches customers using stable Paddle IDs and controlled cross-reference logic, then maps profile, contact, business, and address data to target models. |
| Transactions | Represents purchases, charges, adjustments, and transaction lifecycle state. | NetSuite, Xero, QuickBooks Online, Snowflake, internal finance systems | Martini retrieves or receives transaction data, preserves currency and monetary precision, applies financial status rules, and prevents duplicate downstream postings. |
| Subscriptions | Represents recurring billing agreements, including status, items, billing period, and scheduled changes. | Salesforce, HubSpot, licensing platforms, access-control applications, support systems | Martini maps subscription states explicitly, retrieves current state when event ordering is uncertain, and coordinates provisioning or lifecycle updates idempotently. |
| Businesses | Represents business customer details collected by Paddle. | CRMs, accounting platforms, tax and customer-profile systems, data warehouses | Martini treats Businesses as related customer information, validates available fields, and maps business details alongside Customers, Transactions, or Subscriptions. |
Authentication and security considerations
API authentication
Paddle server-to-server API requests use bearer API keys. API keys should be limited to the permissions required by the integration and stored in Martini secure configuration rather than workflow definitions or source code.
Webhook verification
Paddle webhook requests include a Paddle-Signature header. Martini should validate the signature and required headers before accepting the event for business processing.
Environment separation
- Use separate Paddle credentials and webhook endpoints for development, staging, and production.
- Keep API keys and webhook secrets outside deployed workflow logic.
- Do not treat Paddle.js client-side tokens as interchangeable with server-side API keys.
Operational considerations for Paddle integrations
Pagination and checkpoints
Collection endpoints are paginated. Scheduled workflows should persist checkpoints and may use an overlap window for late-arriving updates.
Rate limits and retries
Distinguish authentication, authorization, validation, not-found, rate-limit, and transient server failures. Use bounded retries with backoff and avoid repeating non-idempotent operations without an idempotency strategy.
Events and idempotency
Webhook delivery can be retried and related events may not arrive in business order. Store event identifiers, retrieve current object state when necessary, and use stable transaction or subscription identifiers to prevent duplicate actions.
Financial and schema controls
- Preserve currency codes and monetary precision.
- Map subscription states explicitly rather than treating every payment event as an access decision.
- Record event types and API versions where available.
- Allow unknown optional fields without failing the complete workflow, while routing required-field and schema errors for review.
Why use Martini instead of scripts or point-to-point integrations?
Centralized orchestration
Martini provides a consistent workflow layer for Paddle API calls, webhook processing, downstream application updates, validation, business rules, and error handling.
Reusable integration logic
Shared mappings, authentication configuration, idempotency controls, and transformation logic can be reused across CRM, accounting, licensing, analytics, and notification flows.
Operational control
Compared with isolated scripts or point-to-point integrations, Martini makes checkpoints, retries, monitoring, environment configuration, and target-system routing explicit and maintainable.
Controlled API access
Martini can expose an API façade that applies authorization and canonical data contracts while shielding internal consumers from Paddle-specific implementation details.
Frequently asked questions
Paddle can be integrated through its versioned REST API and webhook notifications. REST endpoints provide access to Products, Prices, Customers, Transactions, Subscriptions, Businesses, Addresses, adjustments, and related resources, while webhooks provide selected asynchronous lifecycle events. Larger synchronizations should use pagination, checkpoints, retries, and reconciliation.
Yes. Martini can integrate with Paddle by consuming its REST API and receiving Paddle webhook notifications. Martini can securely manage API keys and webhook secrets, validate webhook signatures, orchestrate workflows, map Paddle objects, and write transformed data to enterprise applications or supported databases.
No. A dedicated Paddle connector is not required. Martini can use Paddle’s confirmed native integration mechanisms, including its REST API, webhook notifications, bearer API-key authentication, and Paddle-Signature verification, through workflows and APIs.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Paddle. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Paddle, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.
New implementations should use Paddle’s versioned REST API for server-to-server resource operations and webhook notifications for selected asynchronous lifecycle events. Paddle’s current integration model is REST and webhooks; no current official GraphQL API was confirmed, and SOAP is not supported.
Yes. Martini can receive Paddle webhook requests through an API or webhook-triggered workflow. The workflow should verify the Paddle-Signature header before parsing and processing the payload, record the event identifier for idempotency, and acknowledge valid events promptly.
A scheduled Martini workflow should retrieve Paddle collections page by page, store a checkpoint, and use bounded retries for transient failures or throttling. Event IDs, transaction IDs, subscription IDs, and other stable identifiers should be retained so overlapping runs and retried webhooks do not create duplicate downstream actions.
Yes. Martini can expose a controlled API that hides Paddle-specific details from internal consumers, applies authorization and business rules, invokes Paddle REST operations, and returns a canonical response. This façade can also centralize validation, error handling, and audit logging.
Related Martini documentation
Connect Paddle with your enterprise systems
Use Martini to integrate Paddle Billing APIs and webhook events with your CRM, accounting, licensing, analytics, and operational workflows.