Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to Paddle

Scalekit connector
Open markdown

The Paddle connector lets your AI agent act in each user's Paddle account. Each user connects their own Paddle access token once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 30 tools.

Tools
30
What they doRead · write · destructive
14 · 16 · 014 read16 write0 destructive
Users sign in with

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv
  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>
  3. Create the Paddle connection

    In AgentKit > Connections, create a Paddle connection. The name you give it is the connection_name your code passes. See Configure connections.

  4. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    const scalekit = new ScalekitClient(
    process.env.SCALEKIT_ENVIRONMENT_URL,
    process.env.SCALEKIT_CLIENT_ID,
    process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    const connector = 'paddle'
    const identifier = 'user_123'
    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Paddle:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    // Make your first call
    const result = await actions.executeTool({
    connector,
    identifier,
    toolName: 'paddle_adjustments_list',
    toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user opens the link once and enters their Paddle credentials there. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • paddle_addresses_listList the addresses saved for one customer, optionally searching their fields.Read-only

    List Customer Addresses

    List the addresses saved for one customer, optionally searching their fields. Returns a page of addresses (id, customer_id, description, first_line, second_line, city, postal_code, region, country_code, status) plus meta.pagination. Use this to find an address ID for a transaction or subscription. Requires a customer ID from paddle_customers_list.

    Inputs

    customer_idstringrequired
    Paddle ID of the customer whose addresses to list (starts with ctm_). Get it from paddle_customers_list. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
    afterstring
    Pagination cursor. Pass the Paddle ID of the last entity on the previous page (also found in the after= parameter of meta.pagination.next) to get the next page. Leave empty for the first page. Example: add_01hv8gwdfkw5z6d1yy6pa3xyrz
    idstring
    Comma-separated Paddle IDs to return only those addresses. Example: add_01hv8gwdfkw5z6d1yy6pa3xyrz
    order_bystring
    Field and direction to sort by, written as field[ASC] or field[DESC]. Paddle defaults to id[DESC]. Example: id[DESC]one of id[ASC]id[DESC]
    per_pageinteger
    Number of entities to return per page, up to 200. Paddle defaults to 50. Example: 25
    searchstring
    Text to search for in the address fields (all except status and timestamps). Example: London
    statusstring
    Comma-separated statuses to filter by. Allowed values: active, archived. Paddle returns only active records by default. Example: active
  • paddle_adjustments_listList adjustments (refunds, credits and chargebacks), filtered by transaction, subscription, customer, action or status.Read-only

    List Adjustments

    List adjustments (refunds, credits and chargebacks), filtered by transaction, subscription, customer, action or status. Returns a page of adjustments (id, action, type, transaction_id, subscription_id, customer_id, reason, status, items, totals) plus meta.pagination. Use this to check refund status or a customer's refund history; use paddle_adjustment_create to issue a refund or credit.

    Inputs

    actionstring
    Comma-separated actions to filter by. Allowed values: credit, refund, chargeback, chargeback_reverse, chargeback_warning, chargeback_warning_reverse, credit_reverse. Example: refund
    afterstring
    Pagination cursor. Pass the Paddle ID of the last entity on the previous page (also found in the after= parameter of meta.pagination.next) to get the next page. Leave empty for the first page. Example: adj_01hvgf2s84dr6reszzg29zbvcm
    customer_idstring
    Comma-separated customer IDs; returns only their adjustments. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
    idstring
    Comma-separated Paddle IDs to return only those adjustments. Example: adj_01hvgf2s84dr6reszzg29zbvcm
    order_bystring
    Field and direction to sort by, written as field[ASC] or field[DESC]. Paddle defaults to id[DESC]. Example: id[DESC]one of id[ASC]id[DESC]
    per_pageinteger
    Number of entities to return per page, up to 50. Paddle defaults to 10. Example: 25
    statusstring
    Comma-separated statuses to filter by. Allowed values: pending_approval, approved, rejected, reversed. Example: pending_approval
    subscription_idstring
    Comma-separated subscription IDs; returns only their adjustments. Example: sub_01hv8y5ehszzq0yv20ttx3166y
    transaction_idstring
    Comma-separated transaction IDs; returns only their adjustments. Example: txn_01hv8wptq8987qeep44cyrewp9
  • paddle_customer_getGet one customer by their Paddle ID.Read-only

    Get Customer

    Get one customer by their Paddle ID. Returns the customer's name, email, locale, status, marketing_consent, custom_data and timestamps. Use this when you have a customer ID; use paddle_customers_list to search by name or email.

    Inputs

    customer_idstringrequired
    Paddle ID of the customer (starts with ctm_). Get it from paddle_customers_list. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
  • paddle_customers_listList customers, optionally searching by name, email or ID, or matching exact email addresses.Read-only

    List Customers

    List customers, optionally searching by name, email or ID, or matching exact email addresses. Returns a page of customers (id, name, email, locale, status, marketing_consent, custom_data) plus meta.pagination. Use this to find a customer; use paddle_customer_get when you already have a customer ID.

    Inputs

    afterstring
    Pagination cursor. Pass the Paddle ID of the last entity on the previous page (also found in the after= parameter of meta.pagination.next) to get the next page. Leave empty for the first page. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
    emailstring
    Comma-separated email addresses to match exactly (up to 100). Example: sam@example.com
    idstring
    Comma-separated Paddle IDs to return only those customers. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
    order_bystring
    Field and direction to sort by, written as field[ASC] or field[DESC]. Paddle defaults to id[DESC]. Example: id[DESC]one of id[ASC]id[DESC]
    per_pageinteger
    Number of entities to return per page, up to 200. Paddle defaults to 50. Example: 25
    searchstring
    Text to search for in customer IDs, names and emails (up to 100 characters). Use email for an exact email match. Example: sam
    statusstring
    Comma-separated statuses to filter by. Allowed values: active, archived. Paddle returns only active records by default. Example: active
  • paddle_discounts_listList discounts, filtered by code, status, mode or discount group.Read-only

    List Discounts

    List discounts, filtered by code, status, mode or discount group. Returns a page of discounts (id, code, description, type, amount, currency_code, recur, usage_limit, times_used, expires_at, status) plus meta.pagination. Use this to find a discount by code or ID before applying or updating it.

    Inputs

    afterstring
    Pagination cursor. Pass the Paddle ID of the last entity on the previous page (also found in the after= parameter of meta.pagination.next) to get the next page. Leave empty for the first page. Example: dsc_01hv6scyf7qdnzcdq01t2y8dx4
    codestring
    Comma-separated discount codes to match. Example: BF20OFF
    discount_group_idstring
    Comma-separated discount group IDs; returns only discounts in these groups. Example: dsg_01gtf15svsqzgp9325ss4ebmwt
    idstring
    Comma-separated Paddle IDs to return only those discounts. Example: dsc_01hv6scyf7qdnzcdq01t2y8dx4
    modestring
    Discount mode to filter by: standard (catalog discounts) or custom (non-catalog, e.g. checkout recovery). Example: standardone of standardcustom
    order_bystring
    Field and direction to sort by, written as field[ASC] or field[DESC]. Paddle defaults to id[DESC]. Example: created_at[DESC]one of created_at[ASC]created_at[DESC]id[ASC]id[DESC]
    per_pageinteger
    Number of entities to return per page, up to 200. Paddle defaults to 50. Example: 25
    statusstring
    Comma-separated statuses to filter by. Allowed values: active, archived. Paddle returns only active records by default. Example: active
  • paddle_price_getGet one price by its Paddle ID.Read-only

    Get Price

    Get one price by its Paddle ID. Returns the price's product_id, description, name, billing_cycle, trial_period, tax_mode, unit_price, unit_price_overrides, quantity limits and status, and the product if requested. Use this when you have a price ID; use paddle_prices_list to find one.

    Inputs

    price_idstringrequired
    Paddle ID of the price (starts with pri_). Get it from paddle_prices_list. Example: pri_01gsz8x8sawmvhz1pv30nge1ke
    includestring
    Set to product to include the related product in the response. Example: productone of product
  • paddle_prices_listList prices in the Paddle catalog, filtered by product, status, recurrence or billing interval.Read-only

    List Prices

    List prices in the Paddle catalog, filtered by product, status, recurrence or billing interval. Returns a page of prices (id, product_id, description, name, billing_cycle, trial_period, unit_price, unit_price_overrides, quantity, status) plus meta.pagination. Use this to find the price IDs to bill for; use paddle_price_get when you already have a price ID.

    Inputs

    afterstring
    Pagination cursor. Pass the Paddle ID of the last entity on the previous page (also found in the after= parameter of meta.pagination.next) to get the next page. Leave empty for the first page. Example: pri_01gsz8x8sawmvhz1pv30nge1ke
    billing_cycle_frequencyinteger
    Return only prices whose billing cycle frequency matches this number, e.g. 3 with interval month for quarterly prices. Example: 1
    billing_cycle_intervalstring
    Return only prices that bill on this interval: day, week, month or year. Example: monthone of dayweekmonthyear
    idstring
    Comma-separated Paddle IDs to return only those prices. Example: pri_01gsz8x8sawmvhz1pv30nge1ke
    includestring
    Set to product to include each price's related product in the response. Example: productone of product
    order_bystring
    Field and direction to sort by, written as field[ASC] or field[DESC]. Paddle defaults to id[DESC]. Example: billing_cycle.frequency[DESC]one of billing_cycle.frequency[ASC]billing_cycle.frequency[DESC]billing_cycle.interval[ASC]billing_cycle.interval[DESC]id[ASC]id[DESC]product_id[ASC]product_id[DESC]quantity.maximum[ASC]quantity.maximum[DESC]quantity.minimum[ASC]quantity.minimum[DESC]status[ASC]status[DESC]tax_mode[ASC]tax_mode[DESC]unit_price.amount[ASC]unit_price.amount[DESC]unit_price.currency_code[ASC]unit_price.currency_code[DESC]
    per_pageinteger
    Number of entities to return per page, up to 200. Paddle defaults to 50. Example: 25
    product_idstring
    Comma-separated product IDs; returns only prices for these products. Example: pro_01htz88xpr0mm7b3ta2pjkr7w2
    recurringboolean
    true returns only recurring (subscription) prices; false returns only one-time prices. Example: true
    statusstring
    Comma-separated statuses to filter by. Allowed values: active, archived. Paddle returns only active records by default. Example: active
    typestring
    Item type to filter by: standard (catalog) or custom (non-catalog). Example: standardone of standardcustom
  • paddle_product_getGet one product by its Paddle ID.Read-only

    Get Product

    Get one product by its Paddle ID. Returns the product's name, description, type, tax_category, image_url, status, custom_data and timestamps, and its prices if requested. Use this when you have a product ID; use paddle_products_list to find one.

    Inputs

    product_idstringrequired
    Paddle ID of the product (starts with pro_). Get it from paddle_products_list. Example: pro_01htz88xpr0mm7b3ta2pjkr7w2
    includestring
    Set to prices to include the product's related prices in the response. Example: pricesone of prices