Paddle

1. Overview

Paddle is a comprehensive revenue delivery platform for SaaS companies, handling payments, tax, and subscription management. It simplifies global sales by acting as a merchant of record, offloading the complexities of compliance and international transactions.

With the GoInsight Paddle node, you can seamlessly integrate payment and subscription management into your automated workflows. This allows you to programmatically control key aspects of your revenue operations, including:

• Coupon Management: Create, update, and list promotional coupons to drive sales.
• Data Retrieval: Fetch detailed lists of payments, subscription plans, products, and customers (users).
• Subscription Adjustments: Modify subscription billing cycles by rescheduling upcoming payments.

2. Prerequisites

Before using this node, you will need to have a valid Paddle account. Depending on your organization's security settings, you may need administrator or developer permissions to generate and access API keys.

3. Credentials

For a detailed guide on how to obtain and configure your credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node provides operations centered around managing key e-commerce and subscription resources within your Paddle account, such as Coupons, Payments, Plans, Products, and Users.

Operation Details

Create a Coupon

Create a new coupon (discount) in Paddle using API key authentication. Supports percentage, flat, and flat_per_seat discount types with optional product/price restrictions, expiration dates, and usage limits.

Input Parameters:

• Description: Coupon description shown in Paddle dashboard
• DiscountType: Discount type: percentage, flat, or flat_per_seat
• DiscountAmount: Discount amount (percentage 0.01-100 or flat amount)

Options:

• CouponCode: Custom coupon code (optional, up to 32 characters)
• Currency: Currency code required for flat and flat_per_seat types
• EnabledForCheckout: Whether coupon can be redeemed at checkout
• Recur: Whether coupon applies to recurring payments
• MaximumRecurringIntervals: Number of recurring intervals coupon applies to (0 unlimited)
• MaximumRedemptions: Maximum redemptions allowed (0 unlimited)
• ProductIds: Comma-separated product IDs filter
• PriceIds: Comma-separated price IDs filter
• ExpiresAt: RFC3339 expiration datetime (optional)
• UseSandbox: Set true to call sandbox environment

Output:

• Coupon (object): Created coupon information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Coupons

Retrieve a list of coupons (discounts) from Paddle using API key authentication. Supports cursor-based pagination with per_page, after and order_by parameters. Returns a list of coupons with pagination metadata.

Options:

• After: Pagination cursor to get records after the specified ID
• PerPage: Number of records per page (default 50, max 200)
• OrderBy: Sort field and direction (e.g., -created_at for descending)
• UseSandbox: Set true to call sandbox environment

Output:

• Coupons (object-array): List of coupon information objects
• RecordCount (number): Total number of records returned in this page
• HasMore (bool): Whether there are more records available
• NextCursor (string): Cursor for the next page, empty if no more records
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Update a Coupon

Update an existing coupon (discount) in Paddle using API key authentication. Supports updating description, amount, checkout availability, recurrence, limits and expiration date.

Input Parameters:

• CouponId: Coupon (discount) ID to update, e.g. dsc_xxx

Options:

• Description: New description for the coupon (optional)
• DiscountAmount: New discount amount (percentage or flat amount, optional)
• EnabledForCheckout: Whether coupon can be redeemed at checkout
• Recur: Whether coupon applies to recurring payments
• MaximumRecurringIntervals: New number of recurring intervals coupon applies to (>0 to change, 0 to keep current)
• MaximumRedemptions: New maximum redemptions allowed (>0 to change, 0 to keep current)
• ExpiresAt: New RFC3339 expiration datetime (optional)
• UseSandbox: Set true to call sandbox environment

Output:

• Coupon (object): Updated coupon information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Payments

Retrieve a list of payments (transactions) from Paddle using API key authentication. Supports cursor-based pagination with per_page, after and order_by parameters, and basic filters such as status and customer_id.

Options:

• After: Pagination cursor to get records after the specified ID
• PerPage: Number of records per page (default 50, max 200)
• OrderBy: Sort field and direction (e.g., -created_at for descending)
• Status: Filter by transaction status (e.g., completed, refunded, failed)
• CustomerId: Filter by Paddle customer ID (e.g., ctm_123)
• UseSandbox: Set true to call sandbox environment

Output:

• Payments (object-array): List of payment (transaction) information objects
• RecordCount (number): Total number of records returned in this page
• HasMore (bool): Whether there are more records available
• NextCursor (string): Cursor for the next page, empty if no more records
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Reschedule a Payment

Reschedule the next billing date of a Paddle subscription using API key authentication. Supports updating next_billed_at and proration_billing_mode with sandbox toggle.

Input Parameters:

• SubscriptionId: Subscription ID to reschedule (e.g., sub_xxx)
• NextBilledAt: New next billing datetime in RFC3339 (e.g., 2024-12-31T23:59:59Z)

Options:

• ProrationBillingMode: Proration billing mode (e.g., immediate, next_payment)
• UseSandbox: Set true to call sandbox environment

Output:

• Subscription (object): Updated subscription information object
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get a Plan

Retrieve a specific Paddle subscription plan by ID using API key authentication via the prices endpoint. Supports sandbox toggle.

Input Parameters:

• PlanId: Plan (price) ID to retrieve (e.g., pri_123...)

Options:

• UseSandbox: Set true to call sandbox environment

Output:

• Plan (object): Plan detail object returned from Paddle
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Plans

Retrieve a paginated list of Paddle subscription plans using the prices endpoint with optional status/product filters via API key authentication.

Options:

• After: Pagination cursor to get records after the specified plan ID
• PerPage: Number of records per page (default 50, max 200)
• OrderBy: Sort field and direction (e.g., -created_at for descending)
• Status: Filter by plan status, e.g., active or archived
• ProductId: Filter plans by Paddle product ID (e.g., pro_123)
• UseSandbox: Set true to call sandbox environment

Output:

• Plans (object-array): List of plan information objects
• RecordCount (number): Total number of records returned in this page
• HasMore (bool): Whether there are more records available
• NextCursor (string): Cursor for the next page, empty if no more records
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Products

Retrieve a paginated list of Paddle products with optional status filter and prices include flag using API key authentication.

Options:

• After: Pagination cursor to get records after the specified product ID
• PerPage: Number of records per page (default 50, max 200)
• OrderBy: Sort field and direction (e.g., -created_at for descending)
• Status: Filter by product status, e.g., active or archived
• IncludePrices: Set true to include related prices via include=prices
• UseSandbox: Set true to call sandbox environment

Output:

• Products (object-array): List of product information objects
• RecordCount (number): Total number of records returned in this page
• HasMore (bool): Whether there are more records available
• NextCursor (string): Cursor for the next page, empty if no more records
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

Get Many Users

Retrieve a paginated list of Paddle customers (users) with optional email/status filters using API key authentication.

Options:

• After: Pagination cursor to get records after the specified user ID
• PerPage: Number of records per page (default 50, max 200)
• OrderBy: Sort field and direction (e.g., -created_at for descending)
• Email: Filter users by email (exact match)
• Status: Filter users by status (e.g., active, archived)
• UseSandbox: Set true to call sandbox environment

Output:

• Users (object-array): List of user information objects
• RecordCount (number): Total number of records returned in this page
• HasMore (bool): Whether there are more records available
• NextCursor (string): Cursor for the next page, empty if no more records
• StatusCode (number): HTTP status code
• ErrorMessage (string): Error message when exception occurs

5. Example Usage

This section will guide you through creating a simple workflow to generate a new promotional coupon in your Paddle account.

The workflow will consist of a Start node, a Paddle: Create a Coupon node, and an Answer node.

Step-by-Step Guide

1. Add the Paddle Node:
   • In your workflow canvas, click the "+" button to add a new node.
   • Select the "Tools" tab in the pop-up panel.
   • Find and select "Paddle" from the list of tools.
   • From the list of supported operations for Paddle, click on "Create a Coupon" to add the node to your canvas.
2. Configure the Node:
   • Click on the newly added "Create a Coupon" node to open its configuration panel on the right.
   • Credentials: Find the credentials field at the top of the panel. Click the dropdown menu and select your pre-configured Paddle credential.
   • Parameters: Fill in the required input parameters to define your new coupon.
   • Description: Enter a clear description for internal use, such as 25% Off Summer Sale.
   • DiscountType: Select percentage from the dropdown list.
   • DiscountAmount: Enter the value of the discount. For a 25% discount, you would enter 25.
   • (Optional) CouponCode: You can specify a custom code like SUMMER25. If left blank, Paddle will generate a random one.
   • (Optional) MaximumRedemptions: To limit the usage, you could enter 100 to allow only the first 100 customers to use it.
3. Run and Validate:
   • Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
   • Click the "Test Run" button in the top-right corner of the canvas to execute the workflow.
   • After a successful run, you can click the logs icon (also in the top-right) to view the detailed inputs and outputs of the node, confirming that the coupon was created successfully.

After completing these steps, your workflow is fully configured. When executed, it will create a new 25% off coupon in your Paddle account, ready to be used by your customers.

6. FAQs

Q: Why am I getting a 401 Unauthorized error?

A: This error typically indicates that your API Key is incorrect, has been revoked, or lacks the necessary permissions. Please verify your API key in the Paddle dashboard and ensure it is entered correctly in the GoInsight credentials configuration.

Q: What is the difference between the sandbox and production environments?

A: The sandbox environment (activated by setting UseSandbox to true) is a dedicated testing environment that does not process real payments. It's ideal for developing and testing your workflows without financial implications. The production environment (UseSandbox: false) processes real transactions with real money. Always double-check which environment you are targeting.

Q: How does pagination work for the "Get Many..." operations?

A: These operations use cursor-based pagination to retrieve large sets of data in chunks or "pages". Here's how to use it:

• The first time you run a "Get Many..." node, its output will include a NextCursor field if there are more results available.
• To fetch the next page, add another identical node to your workflow and pass the NextCursor value from the first node into the After input parameter of the second node.

7. Official Documentation

For more in-depth information about the Paddle API and its capabilities, please refer to the Paddle Official API Documentation.