Paddle Data Source

Paddle is a payment processing and subscription management platform for SaaS and digital products. The Paddle connector enables you to ingest transactions, subscriptions, products, pricing, customer, and payment data from your Paddle account into Nexla for analysis, reporting, and downstream processing. Follow the instructions below to create a new data flow that ingests data from a Paddle source in Nexla.

Paddle

Create a New Data Flow

1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

2. Select the Paddle connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Paddle instance, and click Next; or, create a new Paddle credential for use in this flow.

3. In Nexla, Paddle data sources can be created using pre-built endpoint templates, which expedite source setup for common Paddle endpoints. Each template is designed specifically for the corresponding Paddle endpoint, making source configuration easy and efficient.
   • To configure this source using a template, follow the instructions in Configure Using a Template.

   Paddle sources can also be configured manually, allowing you to ingest data from Paddle endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
   • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Paddle endpoints. Each template is designed specifically for the corresponding Paddle endpoint, making data source setup easy and efficient.

Endpoint Settings

• Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

List transactions

Retrieves a paginated list of all transactions in your Paddle account. Use this endpoint to ingest the complete history of billing transactions, including payments, invoices, and subscription charges. This endpoint is ideal for revenue reporting, reconciliation, and audit workflows.

• No additional parameters are required. This endpoint automatically retrieves all transactions accessible with your API key, fetching up to 200 records per page and following pagination automatically until all results have been collected.
• Nexla extracts individual transaction records from the $.data[*] path in the API response, so each transaction becomes a separate record in the resulting Nexset.

This endpoint returns all transaction types including one-time charges, subscription charges, and manual invoices. For complete details on the transaction object schema, see the Paddle List Transactions documentation.

Get a transaction

Retrieves detailed information for a single transaction identified by its Paddle transaction ID. Use this endpoint when you need to fetch and monitor a specific transaction rather than the full transaction history.

• Enter the Paddle transaction ID in the Transaction ID field. Paddle transaction IDs follow the format txn_ followed by an alphanumeric string (for example, txn_01gw4rs4ks8h0kc5dh7gyaghph). Transaction IDs can be found in your Paddle dashboard under Revenue > Transactions, or by first using the List transactions endpoint.

• This endpoint returns a single transaction object from the $.data path in the API response.

For complete details on transaction ID formats and the transaction object schema, see the Paddle Get a Transaction documentation.

Get a PDF invoice for a transaction

Retrieves a PDF invoice download URL for a specific transaction. Use this endpoint when you need to access, archive, or distribute invoice documents for billing transactions.

• Enter the Paddle transaction ID in the Transaction ID field. Only completed transactions with billing details will have an associated PDF invoice. Transaction IDs can be found in your Paddle dashboard under Revenue > Transactions, or by using the List transactions endpoint.

• The response contains a $.data object with a URL field pointing to the generated PDF invoice. The URL is time-limited and should be accessed promptly after retrieval.

Not all transactions have a PDF invoice. Transactions that are not yet completed or were created without invoice details may not return a valid invoice URL. For additional details, see the Paddle Get PDF Invoice documentation.

List subscriptions

Retrieves a paginated list of all subscriptions in your Paddle account. Use this endpoint to monitor recurring billing relationships, track subscription statuses, and build churn or retention analytics.

• No additional parameters are required. This endpoint automatically retrieves all subscriptions accessible with your API key, fetching up to 200 records per page and following pagination automatically until all results have been collected.
• Nexla extracts individual subscription records from the $.data[*] path in the API response. Each subscription record includes details such as status, billing cycle, plan, customer, and next billing date.

Subscription statuses in Paddle include active, canceled, past_due, paused, and trialing. For complete details on the subscription object schema, see the Paddle List Subscriptions documentation.

Get a subscription

Retrieves detailed information for a single subscription identified by its Paddle subscription ID. Use this endpoint when you need to track or audit the state of a specific customer subscription.

• Enter the Paddle subscription ID in the Subscription ID field. Subscription IDs follow the format sub_ followed by an alphanumeric string (for example, sub_01gvne45dvdhg5gdbraa374kcm). Subscription IDs can be found in your Paddle dashboard under Subscriptions, or by first using the List subscriptions endpoint.

• This endpoint returns a single subscription object from the $.data path in the API response, including full billing schedule, status, and associated customer and product details.

For complete details on subscription ID formats and the subscription object schema, see the Paddle Get a Subscription documentation.

Get a transaction to update payment method

Retrieves a transaction that can be used to update the payment method on file for a specific subscription. Use this endpoint to initiate or support payment method update workflows, for example, when a customer's card has expired and you need to redirect them to update their billing details.

• Enter the Paddle subscription ID in the Subscription ID field. The subscription must be in an active or past_due state for this endpoint to return a valid transaction. Subscription IDs can be obtained from the List subscriptions or Get a subscription endpoints.

• This endpoint returns a transaction object from the $.data path. The transaction contains a checkout URL that can be presented to the customer to allow them to update their payment details securely via Paddle's hosted checkout.

For complete details, see the Paddle Get Update Payment Method Transaction documentation.

List products

Retrieves a paginated list of all products in your Paddle catalog. Use this endpoint to ingest your complete product inventory for reporting, catalog management, or synchronization with other systems.

• No additional parameters are required. This endpoint automatically retrieves all products accessible with your API key, fetching up to 200 records per page and following pagination automatically.
• Nexla extracts individual product records from the $.data[*] path. Each product record includes the product name, description, tax category, status, and associated metadata.

Products in Paddle represent what you sell. Prices are a separate entity linked to products and can be retrieved using the List prices endpoint. For complete details, see the Paddle List Products documentation.

Get a product

Retrieves detailed information for a single product identified by its Paddle product ID. Use this endpoint when you need to fetch current metadata for a specific product in your catalog.

• Enter the Paddle product ID in the Product ID field. Product IDs follow the format pro_ followed by an alphanumeric string (for example, pro_01gsz4t5hdjse780zja8vvr7jg). Product IDs can be found in your Paddle dashboard under Catalog > Products, or by using the List products endpoint.

• This endpoint returns a single product object from the $.data path in the API response.

For complete details on the product object schema, see the Paddle Get a Product documentation.

List prices

Retrieves a paginated list of all prices in your Paddle account. Use this endpoint to ingest pricing configurations for your products, including recurring and one-time price definitions, trial periods, and billing intervals.

• No additional parameters are required. This endpoint automatically retrieves all prices accessible with your API key, fetching up to 200 records per page and following pagination automatically.
• Nexla extracts individual price records from the $.data[*] path. Each price record includes the associated product ID, billing interval, amount, currency, trial period settings, and status.

Prices in Paddle are linked to products. A product can have multiple prices (for example, monthly and annual billing options). For complete details, see the Paddle List Prices documentation.

Get a price

Retrieves detailed information for a single price identified by its Paddle price ID. Use this endpoint when you need to fetch the configuration for a specific pricing option in your catalog.

• Enter the Paddle price ID in the Price ID field. Price IDs follow the format pri_ followed by an alphanumeric string (for example, pri_01gsz8ntbeh05w9c3sxs39sw3q). Price IDs can be found in your Paddle dashboard under Catalog > Prices, or by using the List prices endpoint.

• This endpoint returns a single price object from the $.data path in the API response, including the full billing configuration, trial settings, and associated product.

For complete details on the price object schema, see the Paddle Get a Price documentation.

List payment methods for a customer

Retrieves a paginated list of all payment methods saved for a specific customer. Use this endpoint to audit saved payment methods, support dunning workflows, or check payment method availability for a customer.

• Enter the Paddle customer ID in the Customer ID field. Customer IDs follow the format ctm_ followed by an alphanumeric string (for example, ctm_01grnn4zta5a1mf02jjze7y2yt). Customer IDs can be found in your Paddle dashboard under Customers, or by using the List customers or Get a customer endpoints.

• Nexla extracts individual payment method records from the $.data[*] path. Each record includes the payment method type (card, PayPal, etc.), last four digits, expiry details, and billing address.

Payment method records do not include full card numbers—only the last four digits are returned for security. For complete details, see the Paddle List Payment Methods documentation.

Get a payment method for a customer

Retrieves a specific payment method for a customer identified by both a customer ID and a payment method ID. Use this endpoint when you need to inspect a single saved payment method for a customer.

• Enter the required identifiers in the corresponding fields:

  • Customer ID: The Paddle customer ID (format: ctm_...). Customer IDs can be found in your Paddle dashboard or via the List customers endpoint.
  • Payment Method ID: The Paddle payment method ID (format: paymtd_...). Payment method IDs can be obtained using the List payment methods for a customer endpoint.
• This endpoint returns a single payment method object from the $.data path in the API response.

For complete details, see the Paddle Get a Payment Method documentation.

List discounts

Retrieves a paginated list of all discounts defined in your Paddle account. Use this endpoint to review and audit your promotional pricing strategies, coupon codes, and discount configurations.

• No additional parameters are required. This endpoint automatically retrieves all discounts accessible with your API key, fetching up to 200 records per page with automatic pagination.
• Nexla extracts individual discount records from the $.data[*] path. Each record includes the discount code, type (percentage or flat amount), usage limits, expiry date, and redemption count.

For complete details on the discount object schema, see the Paddle List Discounts documentation.

List discount groups

Retrieves a paginated list of all discount groups in your Paddle account. Discount groups allow you to organize discounts into logical collections for easier management. Use this endpoint to audit discount group configurations.

• No additional parameters are required. This endpoint retrieves all discount groups accessible with your API key, fetching up to 200 records per page with automatic pagination.
• Nexla extracts individual discount group records from the $.data[*] path. Each record includes the group name, associated discounts, and metadata.

For complete details, see the Paddle List Discount Groups documentation.

Get a customer

Retrieves detailed information for a single customer identified by their Paddle customer ID. Use this endpoint when you need to fetch current profile data for a specific customer.

• Enter the Paddle customer ID in the Customer ID field. Customer IDs follow the format ctm_ followed by an alphanumeric string (for example, ctm_01grnn4zta5a1mf02jjze7y2yt). Customer IDs can be found in your Paddle dashboard under Customers, or by using the List customers endpoint.

• This endpoint returns a single customer object from the $.data path in the API response, including name, email, status, locale, and marketing consent.

For complete details on the customer object schema, see the Paddle Get a Customer documentation.

List customers

Retrieves a paginated list of all customers in your Paddle account. Use this endpoint to ingest your complete customer database for CRM synchronization, analytics, or customer success workflows.

• No additional parameters are required. This endpoint automatically retrieves all customers accessible with your API key, fetching up to 200 records per page and following pagination automatically.
• Nexla extracts individual customer records from the $.data[*] path. Each record includes the customer name, email, locale, status, and custom data fields.

For complete details on the customer object schema, see the Paddle List Customers documentation.

Get a client-side token

Retrieves the details of a specific client-side token by its ID. Client-side tokens are used with Paddle.js to securely power frontend checkout and billing interactions. Use this endpoint to audit or inspect existing client-side token configurations.

• Enter the client-side token ID in the Client Token ID field. Client-side token IDs can be found in your Paddle dashboard under Developer Tools > Client-side Tokens.

• This endpoint returns a single client-side token object from the $.data path in the API response, including the token description, status, and allowed origins.

Client-side tokens are distinct from API keys. They are intended for use in browser-based environments with Paddle.js and do not grant server-side API access. For complete details, see the Paddle Get a Client-side Token documentation.

Get a PDF credit note for an adjustment

Retrieves a PDF credit note document URL for a specific billing adjustment. Adjustments in Paddle represent refunds or credits applied to a transaction. Use this endpoint to access credit note documents for accounting, compliance, or customer communication purposes.

• Enter the Paddle adjustment ID in the Adjustment ID field. Adjustment IDs follow the format adj_ followed by an alphanumeric string. Adjustment IDs can be found in your Paddle dashboard under Revenue > Adjustments, or in the response of a transaction record where adjustments are referenced.

• This endpoint returns a data object from the $.data path containing a URL to the PDF credit note. The URL is time-limited and should be accessed promptly after retrieval.

Only adjustments of type refund or credit will have an associated PDF credit note. For complete details, see the Paddle Get PDF Credit Note documentation.

Endpoint Testing

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually

Paddle data sources can be manually configured to ingest data from any valid Paddle API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Paddle sources, such as sources that use chained API calls to fetch data from multiple endpoints or that apply custom query parameters to filter results by status, date range, customer, or other criteria supported by the Paddle API.

API Method

1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

2. Select the API method that will be used for calls to the Paddle API from the Method pulldown menu. Most Paddle data retrieval operations use:

   • GET: For retrieving data from the Paddle API (the most common method for data sources)
   • POST: For endpoints that require a request body to filter or preview results (for example, pricing preview endpoints)

API Endpoint URL

3. Enter the URL of the Paddle API endpoint from which this source will fetch data in the Set API URL field. The base URL depends on the environment configured in your Paddle credential:

   • Sandbox: https://sandbox-api.paddle.com/{endpoint_path}
   • Production: https://api.paddle.com/{endpoint_path}

   For example, to list all customers in production, enter https://api.paddle.com/customers. To filter results, you can append query parameters directly to the URL (for example, https://api.paddle.com/transactions?status=completed&per_page=200).

Ensure the API endpoint URL matches the environment (sandbox or production) configured in your Paddle credential. A mismatch between the credential environment and the URL will result in authentication errors. For a full list of available Paddle endpoints and supported query parameters, see the Paddle API Reference.

Date/Time Macros (API URL)

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Date/time macros are particularly useful for Paddle endpoints that support date filter query parameters such as billed_at[gte] or created_at[lte] on the transactions or subscriptions endpoints. This enables you to build incremental data pipelines that retrieve only new or updated records on each run, reducing API calls and data volume.

1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

   • {now} – The current datetime
   • {now-1} – The datetime one time unit before the current datetime
   • {now+1} – The datetime one time unit after the current datetime
   • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}. Paddle date filters typically use ISO 8601 format (for example, 2024-01-01T00:00:00Z).

3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are useful when building Paddle data pipelines that require dynamic identifiers—for example, iterating over a list of customer IDs from another data source to retrieve payment methods or subscription details for each customer.

1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data

Optional

If only a subset of the data returned by the Paddle API endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response. Paddle API responses follow a consistent structure where the primary data payload is nested within a data field, with pagination metadata in a meta field.

For example, when fetching a list of transactions, the Paddle API returns an array of transaction records within a data field, along with pagination details. By specifying the path to the data array, you can configure Nexla to treat each element as a separate record.

For Paddle list endpoints (which return collections), the JSON path is typically $.data[*]. For Paddle single-object endpoints (which return one record), the JSON path is typically $.data.

• To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

  • For responses in JSON format enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (for example, $.data[*] to access all items in the data array, or $.data to access a single data object).
  Path to Data Examples:

  For Paddle list endpoints (such as List transactions, List subscriptions, List products): enter $.data[*] to treat each item in the array as a separate record.

  For Paddle single-object endpoints (such as Get a transaction, Get a subscription): enter $.data to retrieve the single object as one record.

Autogenerate Path Suggestions

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

• To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

• Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

  

Metadata

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. Paddle API responses typically include a meta field containing pagination information such as pagination.total, pagination.per_page, and pagination.next, which may be useful to preserve alongside each record for auditing or debugging purposes.

• To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

  • For responses in JSON format, enter the JSON path to the object or array that contains the metadata. For example, to include Paddle pagination metadata, enter $.meta.

Request Headers

Optional

• If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (for example, header1:value1,header2:value2). Additional headers may be needed for Paddle API versioning or custom integrations.

  You do not need to include the Authorization header—this is automatically handled by Nexla using the API key configured in your Paddle credential. The Paddle API does not require a Content-Type header for GET requests.

Endpoint Testing

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source

1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Paddle data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.