Skip to main content

Paddle Destination

Nexla's bi-directional connectors allow data to flow both to and from any location, making it simple to create a FlexFlow data flow that sends data to a Paddle location.
paddle_api.png

Paddle

Create a Paddle Destination​

  1. Click the + icon on the Nexset that will be sent to the Paddle destination, and select the Send to Destination option from the menu.

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

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

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

Configure Using a Template​

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

  • To configure this destination using a template, select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

    Create a transaction

    Creates a new transaction in your Paddle account. Use this endpoint to programmatically generate transactions for one-time charges, invoice-based billing, or other revenue events that are not automatically handled by Paddle's subscription engine.

    • No additional template parameters are required. Nexla will send the Nexset record data as a JSON body to the Paddle /transactions endpoint using an HTTP POST request.

    • Each Nexset record that is sent must include the required fields for the Paddle transaction object. At minimum, a valid transaction body should include:

      • items: An array of line items, each containing a price_id (the Paddle price ID, format: pri_...) and a quantity.
      • customer_id or customer: Either an existing Paddle customer ID (format: ctm_...) or an inline customer object with at least an email field.

    For the complete list of supported fields and their formats, see the Paddle Create a Transaction documentation.

    Preview a transaction

    Previews a transaction without creating it in Paddle. Use this endpoint to calculate totals, taxes, and discounts for a given set of items and customer details before committing to a transaction—useful for displaying pricing estimates or validating checkout data.

    • No additional template parameters are required. Nexla sends the Nexset record data as a JSON body to the Paddle /transactions/preview endpoint using an HTTP POST request.

    • The request body should include the items and customer details to be previewed. Required fields typically include:

      • items: An array of items to preview, each containing a price_id and quantity.
      • customer_ip_address or address: Used for tax calculation purposes.
    • The Paddle API response will include calculated totals, tax amounts, and applied discounts. No transaction is created.

    For the complete list of supported fields and response format, see the Paddle Preview a Transaction documentation.

    Update a subscription

    Updates an existing subscription in Paddle, such as changing the plan, adjusting billing dates, or modifying the items on a subscription. Use this endpoint to manage subscription lifecycle changes programmatically.

    • Enter the Paddle subscription ID in the Subscription ID field. Subscription IDs follow the format sub_ followed by an alphanumeric string. Subscription IDs can be found in your Paddle dashboard under Subscriptions, or by using the List subscriptions or Get a subscription data source endpoints.

    • Nexla sends the Nexset record data as a JSON body to the subscription endpoint using an HTTP PATCH request. Only the fields included in the request body will be updated—all other subscription fields will remain unchanged.

    • Common updatable fields include:

      • items: To change the products or prices on the subscription.
      • next_billed_at: To reschedule the next billing date.
      • proration_billing_mode: To control how proration is handled when making changes mid-cycle.

    For the complete list of updatable fields and their formats, see the Paddle Update a Subscription documentation.

    Cancel a subscription

    Cancels a specific subscription in Paddle. Use this endpoint to handle customer churn, subscription downgrades, or end-of-term cancellations programmatically. Paddle allows you to control whether the cancellation takes effect immediately or at the end of the current billing period.

    • Enter the Paddle subscription ID in the Subscription ID field. Subscription IDs follow the format sub_ followed by an alphanumeric string. Subscription IDs can be obtained from the List subscriptions or Get a subscription data source endpoints.

    • Nexla sends the Nexset record data as a JSON body using an HTTP POST request. The request body can include an effective_from field to control when the cancellation takes effect. Supported values are immediately (cancel the subscription now) or next_billing_period (cancel at the end of the current billing cycle).

    Canceling a subscription is irreversible. The subscription status will change to canceled and the customer will no longer be billed. For complete details, see the Paddle Cancel a Subscription documentation.

    Pause a subscription

    Pauses a specific subscription in Paddle, temporarily halting billing without canceling the subscription. Use this endpoint to accommodate customers who need a temporary break from their subscription.

    • Enter the Paddle subscription ID in the Subscription ID field. Subscription IDs follow the format sub_ followed by an alphanumeric string.

    • Nexla sends the Nexset record data as a JSON body using an HTTP POST request. The request body can include an effective_from field to control when the pause takes effect, and a resume_at field to schedule an automatic resumption date.

    A paused subscription will have the status paused. The subscription can be resumed using the Resume a paused subscription endpoint. For complete details, see the Paddle Pause a Subscription documentation.

    Resume a paused subscription

    Resumes a subscription that has been paused, reinstating billing on the configured schedule. Use this endpoint when a customer is ready to resume their subscription after a pause.

    • Enter the Paddle subscription ID in the Subscription ID field. The subscription must be in a paused status for this operation to succeed. Subscription IDs can be found in your Paddle dashboard or via the List subscriptions endpoint.

    • Nexla sends the Nexset record data as a JSON body using an HTTP POST request. The request body can include an effective_from field to control when billing resumes.

    For complete details, see the Paddle Resume a Subscription documentation.

    Activate a trialing subscription

    Activates a subscription that is currently in a trial period, starting full billing immediately rather than waiting for the trial to end. Use this endpoint when a customer chooses to convert to a paid plan before their trial expires.

    • Enter the Paddle subscription ID in the Subscription ID field. The subscription must be in trialing status for this operation to succeed. Subscription IDs can be obtained from the List subscriptions endpoint.

    • Nexla sends the Nexset record data as a JSON body using an HTTP POST request. This endpoint typically does not require a request body beyond the subscription ID included in the URL.

    Create a one-time charge for a subscription

    Creates a one-time charge that will be applied to an existing subscription's next invoice. Use this endpoint to bill a customer for ad hoc services, setup fees, or any additional charges outside of the regular subscription price.

    • Enter the Paddle subscription ID in the Subscription ID field. Subscription IDs follow the format sub_ followed by an alphanumeric string. The subscription must be in an active status.

    • Nexla sends the Nexset record data as a JSON body using an HTTP POST request. The request body must include:

      • items: An array of one-time items to charge, each containing a price_id (or inline price details) and a quantity.
      • effective_from: Controls when the charge is applied. Use immediately to bill at once, or next_billing_period to add it to the next scheduled invoice.

    For complete details on supported fields, see the Paddle Create a One-time Charge documentation.

    Create a product

    Creates a new product in your Paddle catalog. Use this endpoint to programmatically add products when launching new offerings or synchronizing your product catalog from an external system.

    • No additional template parameters are required. Nexla sends the Nexset record data as a JSON body to the Paddle /products endpoint using an HTTP POST request.

    • Each record must include the required fields for a Paddle product object:

      • name: The name of the product (required).
      • tax_category: The Paddle tax category for the product, such as standard or saas (required).
      • description: An optional product description.
      • image_url: An optional URL for the product image.

    Products are the top-level catalog entity in Paddle. After creating a product, you can create associated prices using the Create a price endpoint. For complete field details, see the Paddle Create a Product documentation.

    Update a product

    Updates the details of an existing product in your Paddle catalog. Use this endpoint to modify product names, descriptions, images, or status when your catalog changes.

    • Enter the Paddle product ID in the Product ID field. Product IDs follow the format pro_ followed by an alphanumeric string. Product IDs can be found in your Paddle dashboard under Catalog > Products, or by using the List products or Get a product data source endpoints.

    • Nexla sends the Nexset record data as a JSON body using an HTTP PATCH request. Only the fields included in the request body will be updated.

    For the complete list of updatable fields, see the Paddle Update a Product documentation.

    Preview prices

    Previews price calculations for a given pricing configuration without saving any data. Use this endpoint to calculate totals, taxes, and discounts for a set of items and customer details before presenting a pricing summary to a customer or performing a checkout.

    • No additional template parameters are required. Nexla sends the Nexset record data as a JSON body to the Paddle /pricing-preview endpoint using an HTTP POST request.

    • The request body should include the items and address information needed to calculate a localized price estimate. Key fields include:

      • items: An array of items to preview, each with a price_id and quantity.
      • customer_ip_address or address: Used for localized tax calculations.
      • currency_code: Optional. The currency in which to display prices.
    • The API response includes calculated totals, tax amounts, and line-item breakdowns. No data is saved to your Paddle account.

    For complete details on the request and response format, see the Paddle Preview Prices documentation.

    Create a price

    Creates a new price for a product in your Paddle catalog. Prices define how much a customer is charged and on what schedule. Use this endpoint to add pricing options such as monthly, annual, or one-time charges to an existing product.

    • No additional template parameters are required. Nexla sends the Nexset record data as a JSON body to the Paddle /prices endpoint using an HTTP POST request.

    • Each record must include the required fields for a Paddle price object:

      • product_id: The ID of the product this price applies to (format: pro_..., required).
      • description: A brief description of the price (required).
      • unit_price: An object with amount (in the smallest currency unit, e.g., cents) and currency_code (required).
      • billing_cycle: For recurring prices, an object specifying the interval (e.g., month, year) and frequency.

    For the complete list of supported fields and their formats, see the Paddle Create a Price documentation.

    Update a price

    Updates an existing price in your Paddle catalog. Use this endpoint to modify price descriptions, unit amounts, billing intervals, or trial periods when your pricing strategy changes.

    • Enter the Paddle price ID in the Price ID field. Price IDs follow the format pri_ followed by an alphanumeric string. Price IDs can be found in your Paddle dashboard under Catalog > Prices, or by using the List prices or Get a price data source endpoints.

    • Nexla sends the Nexset record data as a JSON body using an HTTP PATCH request. Only the fields included in the request body will be updated—all other price fields will remain unchanged.

    For the complete list of updatable fields, see the Paddle Update a Price documentation.

    Delete a payment method for a customer

    Deletes a specific saved payment method associated with a customer in Paddle. Use this endpoint to remove outdated or unwanted payment methods from a customer's profile.

    • 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 data source endpoint.
    • Nexla sends an HTTP DELETE request to the payment method endpoint. No request body is required. A successful response will return an HTTP 204 No Content status.

    Deleting a payment method is permanent and cannot be undone. Ensure that the customer has an alternative payment method on file before deleting, particularly if they have active subscriptions. For complete details, see the Paddle Delete a Payment Method documentation.

    Create a customer

    Creates a new customer record in your Paddle account. Use this endpoint to register customers programmatically when onboarding new users, importing from an external CRM, or creating customers ahead of checkout.

    • No additional template parameters are required. Nexla sends the Nexset record data as a JSON body to the Paddle /customers endpoint using an HTTP POST request.

    • Each record must include the required fields for a Paddle customer object:

      • email: The customer's email address (required).
      • name: The customer's full name (optional but recommended).
      • locale: The customer's locale (optional, used for localization of invoices and checkout).
      • custom_data: An optional JSON object for storing custom key-value metadata associated with the customer.

    For complete field details and formatting requirements, see the Paddle Create a Customer documentation.

    Update a customer

    Updates details for an existing customer in your Paddle account, such as name, email address, locale, or custom metadata. Use this endpoint to keep customer records synchronized with your CRM or user database.

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

    • Nexla sends the Nexset record data as a JSON body using an HTTP PATCH request. Only the fields included in the request body will be updated.

    For complete field details, see the Paddle Update a Customer documentation.

    Generate an authentication token for a customer

    Generates a new short-lived authentication token for a customer to enable secure client-side access. Customer authentication tokens are used with Paddle.js to allow authenticated customers to interact with Paddle's client-side APIs (for example, to manage their own subscriptions or payment methods in a customer portal).

    • Enter the Paddle customer ID in the Customer ID field. Customer IDs follow the format ctm_ followed by an alphanumeric string. Customer IDs can be found in your Paddle dashboard or via the List customers endpoint.

    • Nexla sends an HTTP POST request to the customer authentication token endpoint. No additional request body fields are required beyond the customer ID included in the URL. The API response will include the generated token and its expiry time.

    Customer authentication tokens are short-lived and should be generated immediately before use. They are not the same as API keys—they are intended for use in client-side contexts such as embedded customer portals. For complete details, see the Paddle Generate Customer Auth Token documentation.

    Create a client-side token

    Creates a new client-side token for use with Paddle.js in your application's frontend. Client-side tokens control which domains can use Paddle.js and which features are available via the client-side API. Use this endpoint to programmatically manage your Paddle.js integration credentials.

    • No additional template parameters are required. Nexla sends the Nexset record data as a JSON body to the Paddle /client-tokens endpoint using an HTTP POST request.

    • The request body can include:

      • description: A descriptive label for the token (optional).
      • allowed_origins: An array of domain origins that are authorized to use this token with Paddle.js (for example, ["https://yourapp.com"]).

    For complete field details, see the Paddle Create a Client-side Token documentation.

    Update a client-side token

    Updates the properties of an existing client-side token, such as its description or allowed origins. Use this endpoint to update your Paddle.js token configuration when your application's domain setup changes.

    • 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.

    • Nexla sends the Nexset record data as a JSON body using an HTTP PATCH request. Only the fields included in the request body will be updated.

    For complete field details, see the Paddle Update a Client-side Token documentation.

Configure Manually​

Paddle destinations can be manually configured to send data to any valid Paddle API endpoint.

Using manual configuration, you can also configure Nexla to automatically send the response received from the Paddle API after each call to a new Nexla webhook data source.

API Method​

  1. To manually configure this destination, 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. Common Paddle API methods for destination operations include:

    • POST: For creating new resources (transactions, customers, products, prices, etc.)
    • PATCH: For partially updating existing resources (subscriptions, customers, products, prices, etc.)
    • DELETE: For removing resources (payment methods)

Data Format​

  1. Select the format in which the Nexset data will be sent to the Paddle API from the Content Format pulldown menu. Nexla will automatically convert the data to the selected format for each API call. The Paddle API requires JSON format for all request bodies.

API Endpoint URL​

  1. Enter the URL of the Paddle API endpoint to which you want to send the Nexset data in the 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 update or patch operations, include the resource ID at the end of the URL (for example, https://api.paddle.com/subscriptions/{subscription_id} for subscription updates).

Ensure the API endpoint URL matches the environment configured in your Paddle credential. For a complete list of Paddle API endpoints, see the Paddle API Reference.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this destination, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (for example, header1:value1,header2:value2).

    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 requires a Content-Type: application/json header for requests with a body, which Nexla sets automatically when using JSON data format.

Exclude Attributes from the Call​

Optional

  • If any record attributes in the Nexset should be omitted when sending data to this Paddle destination, select the attributes from the Exclude Attributes pulldown menu. This is particularly useful when your Nexset contains internal metadata or tracking fields that should not be sent to the Paddle API.

  • Any number of attributes can be selected for exclusion, and all excluded attributes will be shown in the field. To remove an attribute from the list, click the X icon next to the attribute name.

Record Batching​

Optional

  1. If records should be sent to this destination in batched API calls, check the box next to Would you like to batch your records together? to enable record batching.

  2. Enter the maximum number of records that should be batched together in a single API call in the Batch Size field. By default, this value is set to 100.

  3. Select the algorithm that will be used to group records into batches from the Grouping Algorithm pulldown menu. The sample request shown in the panel on the right will be updated to reflect the current batching settings. Some algorithms require additional settings—click on an algorithm listed below to view instructions for configuring these settings.

Property Inside JSON Object

  1. Enter the name of the JSON property that should contain the batched records in the Property Name field.
  2. If any additional properties should be included in the request, enter the properties in the Other Props field in JSON format.

Code

  1. Enter the code that will be used to create the batched request in the code editor below the Grouping Algorithm field.

Response Webhook​

Optional

Nexla can automatically send the response received from the Paddle API after each call to a new Nexla webhook data source. This option allows you to keep track of the status of each API call and any additional information returned after each call—for example, the ID of a newly created transaction or customer, or any validation errors returned by the Paddle API.

  • To enable this option, check the box next to Would you like to process the API response as a Nexla Webhook source?.

Sample Request Payload​

Sample request payloads containing a portion of the Nexset data that will be sent to the Paddle API endpoint based on the current settings are shown in the Sample Payload panel on the right. These samples can be referenced to ensure that the destination and request settings are correctly configured.

  • Click on a sample request payload to expand it and view the complete payload content.

  • Sample payloads are automatically updated with each setting change, making it easy to verify that changes achieve the desired effect.

Endpoint Testing (Manual Configuration)​

After all endpoint settings have been configured, Nexla can send a test payload to the Paddle API to ensure that the destination is configured correctly.

  1. To send a test payload, select the Test button at the top of the Sample Payload panel, and click on a listed sample payload to expand it.

  2. If any modifications to the sample payload are needed, make the necessary changes directly within the sample window.

  3. Click the Send Test Data button at the top of a sample payload to send the test payload to the Paddle API using the current settings.

Important

When testing Paddle destination endpoints that create or modify data (such as creating transactions or customers), use your Paddle Sandbox environment to avoid affecting live production data. Ensure your Paddle credential is configured with the Sandbox base URL before sending test payloads.

Save & Activate the Destination​

  • Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To begin sending data to the configured Paddle endpoint, open the destination resource menu, and select Activate.

    The Nexset data will not be sent to the Paddle API until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.