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 supports operations on the following resources: Coupon, Payment, Plan, Product, Subscription, and User.

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.

Use cases:

Flash sales, referral programs, subscription promotions, product-specific discounts

Input Parameters:

• Description: Coupon description shown in Paddle dashboard. This is an internal note to help you identify the coupon. Example: 'Summer 2024 Promotion - 20% off all products'
• DiscountType: Discount type. Choose based on your pricing model:
• 'percentage': Percentage discount (e.g., 20% off). Works for all product types.
• 'flat': Fixed amount discount (e.g., $10 off total order). Requires Currency parameter.
• 'flat_per_seat': Fixed amount discount per seat (e.g., $5 off per user). Use this ONLY for per-seat SaaS products (where pricing is based on number of users/seats). For example, if a customer buys 10 seats at $20/seat and you offer a $5/seat discount, they pay $150 instead of $200. Requires Currency parameter. Do NOT use this for non-seat-based products (use 'flat' instead).

Example: 'percentage'

• DiscountAmount: Discount amount value. For 'percentage' type: enter a number between 0.01 and 100 (e.g., '20' for 20% off). For 'flat' or 'flat_per_seat' types: enter the amount in the specified currency (e.g., '10.00' for $10 off).

Options:

• CouponCode: Custom coupon code (optional, up to 32 characters). If not provided, Paddle will auto-generate a unique code (format: 8 uppercase alphanumeric characters, e.g., 'A1B2C3D4'). Custom codes must be unique across your account. Example: 'SUMMER2024'
• Currency: Three-letter ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP'). Required when DiscountType is 'flat' or 'flat_per_seat'. Leave empty for percentage discounts. Example: 'USD'
• EnabledForCheckout: Whether coupon can be redeemed at checkout (optional). Default: true. If set to false, customers will NOT be able to apply this coupon during checkout, but it can still be applied via API or admin panel. Use this to create internal-only coupons for manual application.
• Recur: Whether coupon applies to recurring payments (optional). Default: false. If true, the discount will apply to all future billing cycles (or until maximum_recurring_intervals is reached). If false, discount only applies to the first payment. Example: Set to true for 'First 3 months 50% off' promotions.
• AdditionalFields: Additional coupon configuration fields as a JSON object (optional). Use for advanced options like usage limits, expiration, and product restrictions.

⚠️ IMPORTANT - Environment Control:

• use_sandbox (bool): Switch between production and sandbox environments. Default: false (production).
  • Production (false): Creates real coupons that affect actual customer transactions and billing. Use this for live business operations.
  • Sandbox (true): Creates test coupons in an isolated testing environment. Use this ONLY for development and testing. Sandbox coupons cannot be used by real customers.
  • WARNING: Misuse will cause coupons to be created in the wrong environment! Double-check before creating coupons.

Common fields:

Common configuration examples:

1. Limited-time flash sale (expires in 24 hours, max 100 uses): {"expires_at": "2024-12-31T23:59:59Z", "maximum_redemptions": 100}
2. Product-specific promotion: {"product_ids": ["pro_01h8abc123", "pro_01h9def456"]}
3. Recurring discount (50% off for first 3 months): {"maximum_recurring_intervals": 3}
4. Sandbox testing: {"use_sandbox": true}

Refer to Paddle API documentation for complete field list.

Output:

• Coupon (object): The created coupon object containing all stored field values. Note: This is a flat object with no nested structures. All array fields (product_ids, price_ids) contain simple string values, not objects.

Core Fields (always present):

Optional Fields (may be null):

Example:

{"id": "ctm_01h8...", "code": "SUMMER2024", "description": "Summer sale", "type": "percentage", "amount": "20", "currency": null, "enabled_for_checkout": true, "status": "active", "times_used": 0, "created_at": "2024-01-15T10:30:00Z"}

• OriginalStatusCode (number): The original HTTP status code returned by the upstream Paddle API.
• 0: Request did not reach upstream (network error, timeout)
• 200/201: Upstream success
• 400: Bad Request (invalid parameters)
• 401: Unauthorized (invalid API key)
• 403: Forbidden (permission denied)
• 404: Not Found (resource does not exist)
• 429: Rate limited
• 5xx: Server error from upstream
• StatusCode (number): Operation status code:
• 200: Success or business error (check ErrorMessage for details)
• -1: Parameter validation error (invalid or missing input parameters)
• 500: System error (network timeout, connection failure, or response parsing error)

Note: Business-level errors from upstream Paddle API are returned with StatusCode 200 and details in ErrorMessage.

• ErrorMessage (string): Detailed error description. Empty string when successful.

Common error scenarios:

• Parameter validation: "Invalid discount_type. Must be one of: percentage, flat, flat_per_seat"
• Authentication: "Unauthorized: Invalid API key or authentication failed"
• Business error: "Bad Request: Currency is required for 'flat' discount type"
• Network error: "Request timeout occurred. Please try again later"

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.

Typical use cases:

• Export all active coupons for reporting
• Find expired coupons for cleanup
• Monitor coupon usage statistics
• Sync coupons to external CRM systems

Pagination best practices:

• Use PerPage: 50 (default) for balanced performance
• Use PerPage: 200 (max) for bulk exports
• Always check HasMore to determine if more pages exist
• Use NextCursor from response to fetch next page

Options:

• After: Pagination cursor to get records after the specified coupon ID. Use the NextCursor value from the previous response to fetch the next page.

How to use:

1. First request: Leave empty to get the first page
2. Subsequent requests: Use the NextCursor from previous response

Example: ctm_01j9zmxp9v000000000000000

• PerPage: Number of records per page (default 50, max 200)
• OrderBy: Sort field and direction. Prefix with '-' for descending order.

Supported fields:

• created_at: Sort by creation time
• updated_at: Sort by last update time
• code: Sort by coupon code

Examples:

• -created_at: Newest first (descending)
• created_at: Oldest first (ascending)
• -updated_at: Recently updated first

Default: -created_at (newest first)

• UseSandbox: Whether to use Paddle's sandbox (test) environment instead of production.

When to use:

• Set true for testing and development
• Set false (default) for production operations

Note: Sandbox and production environments have separate data. Coupons created in sandbox will not appear in production.

Output:

• Coupons (object): Coupon list with pagination metadata. This object contains:
• data (array): List of coupon objects, each with:
  • id (string): Unique coupon identifier
  • code (string): Coupon code for customers to use
  • status (string): active | archived | expired | used
  • type (string): percentage | flat | flat_per_seat
  • amount (string): Discount amount (e.g., "20" for 20% or "10.00" for $10)
  • currency_code (string): Currency code (e.g., USD, EUR)
  • usage_limit (number): Maximum number of times this coupon can be used
  • times_used (number): Number of times this coupon has been used
  • expires_at (string): Expiration date in ISO 8601 format
  • created_at (string): Creation timestamp
  • updated_at (string): Last update timestamp
• record_count (number): Total number of records in this page
• has_more (bool): Whether there are more records available
• next_cursor (string): Cursor for the next page, empty if no more records
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• 0: Request did not reach upstream (network error, timeout)
• 200: Upstream success
• 4xx: Client error from upstream (400 Bad Request, 401 Unauthorized, 404 Not Found)
• 5xx: Server error from upstream
• StatusCode (number): Operation status code:
• 200: Success. The upstream API request completed successfully. Check ErrorMessage for business-level errors.
• -1: Parameter validation error. One or more input parameters are invalid or missing.
• 500: System error. Network timeout, connection failure, or response parsing error. The operation may be retried.
• ErrorMessage (string): Detailed error description. Empty string when successful.

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 ID to update, format: dsc_ prefix + 26 characters (e.g., dsc_01h8xce4x9s9c2y8w7n5k3j2m1).

How to get this ID:

• Call Get Many Coupons action to list all coupons
• Call Get a Coupon action to query specific coupon
• View in Paddle Dashboard → Coupons → Coupon Details

Example: dsc_01h8xce4x9s9c2y8w7n5k3j2m1

Options:

• DiscountAmount: New discount amount (optional). Format and unit depend on the coupon's discount type (set at creation, cannot be changed).

Percentage type (percentage):

• Enter a number string between 0-100, representing discount percentage
• Example: "20" means 20% off

Fixed amount type (flat / flat_per_seat):

• Enter the smallest currency unit (e.g., cents for USD, yen for JPY)
• Example: "1000" means $10.00 in USD

Note: Leave empty to keep current amount. Value must match the coupon's original discount type.

Example: "20" (for percentage) or "1000" (for flat amount in cents)

• EnabledForCheckout: Whether coupon can be redeemed at checkout. Set to true to allow customers to use this coupon code during checkout.
• Recur: Whether coupon applies to recurring subscription payments. Set to true to apply discount to renewal payments, false for one-time discount only.
• MaximumRecurringIntervals: Maximum number of billing cycles the coupon applies to (optional).

Fill rules:

• 0 (default): Keep current value unchanged, do not modify this field
• > 0: Update to specified number of cycles (e.g., 12 means apply to first 12 billing cycles)

Note: Paddle API does not support setting this field to null (unlimited) via update. To set unlimited, leave this field empty when creating the coupon, or contact Paddle support.

Example: 12 (apply to first 12 billing cycles)

• MaximumRedemptions: Maximum number of times the coupon can be redeemed (optional).

Fill rules:

• 0 (default): Keep current value unchanged, do not modify this field
• > 0: Update to specified redemption limit (e.g., 100 means maximum 100 uses)

Note: Paddle API does not support setting this field to null (unlimited) via update. To set unlimited, leave this field empty when creating the coupon, or contact Paddle support.

Example: 100 (maximum 100 redemptions)

• ExpiresAt: New expiration datetime for the coupon (optional). Format must be ISO 8601 / RFC 3339 standard with timezone information.

Format requirement: YYYY-MM-DDTHH:MM:SSZ

Examples:

• UTC timezone: 2024-12-31T23:59:59Z
• With timezone offset: 2024-12-31T23:59:59+08:00

Note: Leave empty to keep current expiration. Setting to a past time will cause the coupon to expire immediately.

Example: 2024-12-31T23:59:59Z

• UseSandbox: Set to true to use Paddle's sandbox (test) environment. What is sandbox: A testing environment where you can simulate transactions without real money. Use this for development and testing. Default: false (production environment).
• AdditionalFields: Additional fields to update (optional). Use this for less frequently updated fields.

Supported fields:

• description (string): Coupon description

Example: {"description": "Summer Sale 2024 - 20% off all annual plans"}

Output:

• Coupon (object): Updated coupon information object with core fields:
• id (string): Coupon unique identifier, format: dsc_xxx
• code (string): Coupon code entered by users at checkout
• description (string): Coupon description
• type (string): Discount type, enum: percentage (percentage) / flat (fixed amount) / flat_per_seat (fixed amount per seat)
• amount (string): Discount amount, percentage type is "0-100" number string, fixed amount is smallest currency unit (e.g., cents for USD)
• currency (string): Currency code (fixed amount type only), e.g., USD, EUR
• enabled_for_checkout (bool): Whether can be used at checkout
• recur (bool): Whether applies to subscription renewals
• maximum_recurring_intervals (int): Maximum applicable renewal cycles, null means unlimited
• maximum_redemptions (int): Maximum usage count, null means unlimited
• times_used (int): Times used
• product_ids (array): Applicable product ID list
• price_ids (array): Applicable price ID list
• expires_at (string): Expiration time, ISO 8601 format
• status (string): Status, enum: active (active) / expired (expired) / used (used up) / archived (archived)
• created_at (string): Creation time
• updated_at (string): Last update time
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• 0: Request did not reach upstream (network error, timeout)
• 200: Upstream success
• 4xx: Client error from upstream (400 Bad Request, 401 Unauthorized, 404 Not Found)
• 5xx: Server error from upstream
• StatusCode (number): Operation status code:
• 200: Success or business error (check ErrorMessage for details)
• -1: Parameter validation error (invalid or missing input parameters)
• 500: System error (network timeout, connection failure, or response parsing error)

Note: Business-level errors from upstream API are returned with StatusCode 200 and details in ErrorMessage.

• ErrorMessage (string): Detailed error description. Empty string when successful.

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 retrieve records after the specified transaction ID. Use the NextCursor value from the previous response to fetch the next page. Leave empty for the first page.

Example: txn_01h8xce4x8mjkbpz5mjkbpz6n

• PerPage: Number of records per page (default 50, max 200)
• OrderBy: Sort field and direction. Format: field_name (ascending) or -field_name (descending).

Supported fields:

• created_at: Creation time (default)
• updated_at: Last update time
• billed_at: Billing time

Example: -created_at (newest first), billed_at (oldest first)

• Status: Filter by transaction status. Supported values:
• completed: Payment successfully processed
• refunded: Full or partial refund issued
• failed: Payment failed (card declined, etc.)
• pending: Payment initiated but not yet completed
• canceled: Payment canceled before completion

Leave empty to retrieve all statuses. Multiple values not supported.

• CustomerId: Filter by Paddle customer ID (e.g., ctm_01h8xce4x8mjkbpz5m). You can obtain customer IDs from the Get Many Customers action or from webhook events. Leave empty to retrieve payments for all customers.
• UseSandbox: Set true to call sandbox environment

Output:

• Payments (object): Payment list response object containing payments and pagination metadata.

Structure:

• payments (array): List of Paddle payment (transaction) objects. Each payment contains:
  • id (string): Unique transaction identifier (e.g., txn_01h8xce4x8mjkbpz5m)
  • status (string): Payment status (completed, refunded, failed, pending, canceled)
  • customer_id (string): Paddle customer ID
  • amount (string): Payment amount in minor units (e.g., "2999" = $29.99)
  • currency_code (string): Three-letter currency code (USD, EUR, etc.)
  • created_at (string): Creation timestamp in ISO 8601 format
  • updated_at (string): Last update timestamp
  • billed_at (string): Billing timestamp
  • items (array): List of transaction items
• record_count (number): Total number of records returned in this page
• has_more (boolean): Whether there are more records available
• next_cursor (string): Cursor for the next page (empty if no more records)

Example:

{"payments": [{"id": "txn_01h8xce4x8mjkbpz5m", "status": "completed", "customer_id": "ctm_01h8xce4x8mjkbpz5m", "amount": "2999", "currency_code": "USD", "created_at": "2024-01-15T10:30:00Z"}], "record_count": 1, "has_more": true, "next_cursor": "txn_01h8xce4x8mjkbpz6n"}

Full field list: https://developer.paddle.com/api-reference/transactions/get-transaction

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• 0: Request did not reach upstream (network error, timeout)
• 200: Upstream success
• 4xx: Client error from upstream (400 Bad Request, 401 Unauthorized, 404 Not Found)
• 5xx: Server error from upstream
• StatusCode (number): Operation status code:
• 200: Success or business error (check ErrorMessage for details)
• -1: Parameter validation error (invalid or missing input parameters)
• 500: System error (network timeout, connection failure, or response parsing error)

Note: Business-level errors from upstream API are returned with StatusCode 200 and details in ErrorMessage.

• ErrorMessage (string): Detailed error description. Empty string when successful.

Get Many Plans

Retrieve paginated list of Paddle subscription plans (prices) with filtering by status and product. Returns plan objects with billing cycles, pricing, and metadata. Supports cursor-based pagination using after/next_cursor. Use PerPage (max 200) to control page size and OrderBy for sorting (e.g., -created_at for newest first).

Options:

• After: Pagination cursor to fetch records after a specific plan ID. Format: pri_ followed by alphanumeric characters.

Usage:

• First request: Leave empty to start from the beginning
• Subsequent requests: Use the NextCursor value from the previous response

Example workflow:

1. First call: After = "" (empty)
2. Check response: HasMore = true, NextCursor = "pri_01h1vjes..."
3. Second call: After = "pri_01h1vjes..."

Example: pri_01h1vjes1y163xfj1rh1tkfb65

• PerPage: Number of records per page (default 50, max 200)
• OrderBy: Sort field and direction. Format: [field] (ascending) or -[field] (descending).

Supported fields:

• created_at: Creation time
• updated_at: Last update time
• name: Plan name (alphabetical)

Examples:

• Newest first: -created_at
• Oldest first: created_at
• Alphabetical: name

Leave empty for default sorting (newest first).

• Status: Filter by plan status. Supported values:
• active: Currently active plans (default if not specified)
• archived: Archived/inactive plans

Leave empty to return all statuses. Example: active

• ProductId: Filter plans belonging to a specific product. Product ID format: pro_ followed by alphanumeric characters (e.g., pro_01h1vjeh4araneyfk1swqgqg0k).

How to get Product ID:

• Call Get Many Products action to list all products
• Check product details in Paddle dashboard

Leave empty to return plans from all products. Example: pro_01h1vjeh4araneyfk1swqgqg0k

• UseSandbox: Set true to call sandbox environment

Output:

• Plans (object): Plan list response object containing plans and pagination metadata.

Structure:

• plans (array): List of Paddle plan/price objects. Each plan contains:
  • id (string): Unique plan identifier (e.g., pri_01h1vjes1y163xfj1rh1tkfb65)
  • product_id (string): Associated product ID
  • name (string): Plan display name
  • description (string): Plan description
  • billing_cycle (object): Billing interval and frequency
  • interval (string): month/year
  • frequency (number): Billing frequency
  • unit_price (object): Price information
  • amount (string): Price amount in cents (e.g., "2900" = $29.00)
  • currency_code (string): ISO currency code (e.g., USD)
  • status (string): Plan status (active/archived)
  • created_at (string): Creation timestamp (ISO 8601)
  • updated_at (string): Last update timestamp (ISO 8601)
• record_count (number): Total number of records returned in this page
• has_more (boolean): Whether there are more records available
• next_cursor (string): Cursor for the next page (empty if no more records)

Example:

{"plans": [{"id": "pri_01h1vjes1y163xfj1rh1tkfb65", "product_id": "pro_01h1vjeh4araneyfk1swqgqg0k", "name": "Monthly Pro Plan", "status": "active"}], "record_count": 1, "has_more": true, "next_cursor": "pri_01h1vjes1y163xfj1rh1tkfb66"}

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• 0: Request did not reach upstream (network error, timeout)
• 200: Upstream success
• 4xx: Client error from upstream (400 Bad Request, 401 Unauthorized, 404 Not Found)
• 5xx: Server error from upstream
• StatusCode (number): Operation status code:
• 200: Success or business error (check ErrorMessage for details)
• -1: Parameter validation error (invalid or missing input parameters)
• 500: System error (network timeout, connection failure, or response parsing error)

Note: Business-level errors from upstream API are returned with StatusCode 200 and details in ErrorMessage.

• ErrorMessage (string): Detailed error description. Empty string when successful.

Get a Plan

Retrieve a specific Paddle subscription plan by ID.

Note:

In Paddle Billing API v2, plans are represented as Price resources. This action queries the /prices endpoint. Supports optional product inclusion and sandbox environment toggle.

Input Parameters:

• PlanId: Plan ID to retrieve (e.g., pri_01h8xce4xgx9s7ztfxwm3k2y6p). Note: In Paddle Billing API v2, plans are represented as Price resources with IDs starting with 'pri_'.

How to get this ID:

• Use Get Many Plans action to list all available plans
• Copy from Paddle Dashboard → Catalog → Prices

Example: pri_01h8xce4xgx9s7ztfxwm3k2y6p

Options:

• UseSandbox: Set to true to use Paddle's sandbox (test) environment. What is sandbox: A testing environment where you can simulate transactions without real money. Use this for development and testing. Default: false (production environment).
• IncludeProduct: Set to true to include related product details in the response. This avoids a separate API call to get product information. When enabled, the Plan object will contain a nested 'product' field with full product details. Default: false.

Output:

• Plan (object): Plan (Price) detail object returned from Paddle. Core fields:
• id (string): Price ID (e.g., pri_01h8xce4xgx9s7ztfxwm3k2y6p)
• product_id (string): Associated product ID
• name (string): Display name
• description (string): Plan description
• type (string): Price type (standard/custom)
• billing_cycle (object): Billing interval and frequency
  • interval (string): month/year/week/day
  • frequency (number): How many intervals per cycle
• unit_price (object): Price amount and currency
  • amount (string): Price in smallest currency unit (e.g., '2900' = $29.00)
  • currency_code (string): ISO 4217 code (USD/EUR/GBP)
• status (string): active/archived
• created_at (string): ISO 8601 timestamp
• updated_at (string): ISO 8601 timestamp
• product (object, optional): Included when IncludeProduct is true

Full schema: https://developer.paddle.com/api-reference/prices/get-price

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• 0: Request did not reach upstream (network error, timeout)
• 200: Upstream success
• 4xx: Client error from upstream (400 Bad Request, 401 Unauthorized, 404 Not Found)
• 5xx: Server error from upstream
• StatusCode (number): Operation status code:
• 200: Success or business error (check ErrorMessage for details)
• -1: Parameter validation error (invalid or missing input parameters)
• 500: System error (network timeout, connection failure, or response parsing error)

Note: Business-level errors from upstream API are returned with StatusCode 200 and details in ErrorMessage.

• ErrorMessage (string): Detailed error description. Empty string when successful.

Get Many Products

Retrieve paginated Paddle products with optional status filter and price inclusion using API key authentication.

Use cases: catalog export, active product filtering, pricing analysis, inventory sync.

Pagination: Use PerPage (50 default, 200 max), check HasMore for more pages, use NextCursor to fetch next page.

Options:

• After: Pagination cursor to get records after the specified product ID. Use the NextCursor value from the previous response to fetch the next page.

How to use:

1. First request: Leave empty to get the first page
2. Subsequent requests: Use the NextCursor from previous response

Example: pro_01j9zmxp9v000000000000000

• PerPage: Number of records per page (default 50, max 200)
• OrderBy: Sort field and direction. Prefix with '-' for descending order.

Supported fields:

• created_at: Sort by creation time
• updated_at: Sort by last update time
• name: Sort by product name

Examples:

• -created_at: Newest first (descending)
• created_at: Oldest first (ascending)
• name: Alphabetical order

Default: -created_at (newest first)

• Status: Filter products by status.

Supported values:

• active: Only active products
• archived: Only archived products
• Leave empty: All products (no filter)

Example: active

• IncludePrices: Whether to include related price information in the response.

When to use:

• Set true to get product prices in one request (reduces API calls)
• Set false (default) for faster response when prices are not needed

Note: When enabled, each product will include a prices array with pricing details.

• UseSandbox: Whether to use Paddle's sandbox (test) environment instead of production.

When to use:

• Set true for testing and development
• Set false (default) for production operations

Note: Sandbox and production environments have separate data. Products created in sandbox will not appear in production.

Output:

• Products (object): Product list with pagination metadata. This object contains:
• data (array): List of product objects, each with:
  • id (string): Unique product identifier
  • name (string): Product name
  • description (string): Product description
  • status (string): active | archived
  • type (string): standard | custom
  • tax_category (string): Tax category code
  • image_url (string): Product image URL
  • custom_data (object): Custom metadata
  • created_at (string): Creation timestamp
  • updated_at (string): Last update timestamp
  • prices (array): Price list (only if IncludePrices=true)
• record_count (number): Total number of records in this page
• has_more (bool): Whether there are more records available
• next_cursor (string): Cursor for the next page, empty if no more records
• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• 0: Request did not reach upstream (network error, timeout)
• 200: Upstream success
• 4xx: Client error from upstream (400 Bad Request, 401 Unauthorized, 404 Not Found)
• 5xx: Server error from upstream
• StatusCode (number): Operation status code:
• 200: Success. The upstream API request completed successfully. Check ErrorMessage for business-level errors.
• -1: Parameter validation error. One or more input parameters are invalid or missing.
• 500: System error. Network timeout, connection failure, or response parsing error. The operation may be retried.
• ErrorMessage (string): Detailed error description. Empty string when successful.

Reschedule a Payment

Reschedule the next billing date of a Paddle subscription. Allows you to change when the customer will be billed next, with options to control how proration (proportional billing) is handled. Useful for extending payment deadlines, aligning billing cycles, or accommodating customer requests. Supports immediate or deferred proration billing modes.

Input Parameters:

• SubscriptionId: Paddle subscription unique identifier (format: sub_xxxxxxxxxxxxxxxxxxxxxxxx). How to get this ID:
• Call Get Many Subscriptions action to list customer subscriptions
• Extract from Paddle Webhook events (subscription.id field)
• Copy from Paddle Dashboard → Subscriptions → Subscription Details

Example: sub_01h8441jn5pcwrfhwh78jqt8hk

• NextBilledAt: New next billing datetime in RFC3339 format (UTC timezone).

Format requirements:

• Must include date and time: YYYY-MM-DDTHH:MM:SSZ
• Timezone must use Z (UTC) or ±HH:MM offset
• Cannot be earlier than current time
• Recommended to set to future round time (e.g., 23:59:59)

Examples:

• UTC timezone: 2024-12-31T23:59:59Z
• GMT+8 timezone: 2024-12-31T23:59:59+08:00
• EST timezone: 2024-12-31T23:59:59-05:00

Options:

• ProrationBillingMode: Proration billing mode, controls how to handle fee differences after adjusting billing cycle.

Available values:

• immediate (Immediate billing): Generate invoice immediately and charge/refund fee difference proportionally. Suitable for upgrading plans or shortening billing cycles.
• next_payment (Next billing): Accumulate fee difference to next bill. Suitable for extending billing cycles or downgrading plans.

Default: immediate

Business scenarios:

• Customer requests payment extension (e.g., from Jan 15 to Feb 1) → Choose next_payment to avoid immediate charge
• Customer upgrades plan and wants immediate effect → Choose immediate to charge price difference proportionally

Example: immediate

• UseSandbox: Set to true to use Paddle's sandbox (test) environment. What is sandbox: A testing environment where you can simulate transactions without real money. Use this for development and testing. Default: false (production environment).

Output:

• Subscription (object): Updated subscription information object with core fields:
• id (string): Subscription unique identifier
• status (string): Subscription status (active, paused, canceled, etc.)
• next_billed_at (string): Next billing datetime (RFC3339 format)
• current_billing_period (object): Current billing period with starts_at and ends_at
• billing_cycle (object): Billing cycle configuration with interval and frequency
• items (array): Subscription items list with price_id and quantity
• customer_id (string): Customer ID
• currency_code (string): Currency code (e.g., USD, EUR)
• created_at (string): Creation timestamp
• updated_at (string): Last update timestamp

Full field list: https://developer.paddle.com/api-reference/subscriptions/get-subscription

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• 0: Request did not reach upstream (network error, timeout)
• 200: Upstream success
• 4xx: Client error from upstream (400 Bad Request, 401 Unauthorized, 404 Not Found)
• 5xx: Server error from upstream
• StatusCode (number): Operation status code:
• 200: Success or business error (check ErrorMessage for details)
• -1: Parameter validation error (invalid or missing input parameters)
• 500: System error (network timeout, connection failure, or response parsing error)

Note: Business-level errors from upstream API are returned with StatusCode 200 and details in ErrorMessage.

• ErrorMessage (string): Detailed error description. Empty string when successful.

Get Many Users

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

Options:

• After: Cursor for pagination. Use the next_cursor value from previous response to get the next page of results. Leave empty for the first page.

Example: "ctm_01h8441jn5pcwrfhwh78jqt8hk"

• PerPage: Number of records per page (default 50, max 200)
• OrderBy: Sort field and direction.

Supported fields:

• created_at: Creation timestamp
• updated_at: Last update timestamp
• email: Email address

Direction:

• Prefix with - for descending (e.g., -created_at)
• No prefix for ascending (e.g., email)

Example: "-created_at"

• Email: Filter users by email (exact match)
• Status: Filter users by status. Supported values:
• active: Currently active customers
• archived: Archived/inactive customers

Example: "active"

• UseSandbox: Set true to use sandbox (test) environment. Sandbox is a safe testing environment that does not affect real customer data. Use for development and debugging.

Example: false (use production by default)

Output:

• Customers (object): Customer list response object containing users and pagination metadata.

Structure:

• users (array): List of Paddle customer objects. Each customer contains:
  • id (string): Unique customer identifier
  • email (string): Customer email address
  • name (string): Customer name
  • status (string): Customer status (active, archived)
  • created_at (string): Creation timestamp in ISO 8601 format
  • updated_at (string): Last update timestamp
  • custom_data (object, optional): Custom metadata associated with the customer
• record_count (number): Total number of records returned in this page
• has_more (boolean): Whether there are more records available
• next_cursor (string): Cursor for the next page (empty if no more records)

Example:

{"users": [{"id": "ctm_01h8441jn5pcwrfhwh78jqt8hk", "email": "john@example.com", "name": "John Doe", "status": "active", "created_at": "2024-01-15T10:30:00Z"}], "record_count": 1, "has_more": true, "next_cursor": "ctm_01h8441jn5pcwrfhwh78jqt8hk"}

• OriginalStatusCode (number): The original HTTP status code returned by the upstream API.
• 0: Request did not reach upstream (network error, timeout)
• 200: Upstream success
• 4xx: Client error from upstream (400 Bad Request, 401 Unauthorized, 404 Not Found)
• 5xx: Server error from upstream
• StatusCode (number): Operation status code:
• 200: Success or business error (check ErrorMessage for details)
• -1: Parameter validation error (invalid or missing input parameters)
• 500: System error (network timeout, connection failure, or response parsing error)

Note: Business-level errors from upstream API are returned with StatusCode 200 and details in ErrorMessage.

• ErrorMessage (string): Detailed error description. Empty string when successful.

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.