> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Paddle

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.

**Authentication:** Bearer Token
**Categories:** Accounting & Finance
**Tools:** 30: 14 read, 16 write, 0 destructive
**Users sign in with:** Access token
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=PADDLE)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".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](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   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)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "paddle"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Paddle:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="paddle_adjustments_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Paddle credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'paddle_addresses_list',
  toolInput: {
    customer_id: '<customer_id>',
  },
  connector: 'paddle',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="paddle_addresses_list",
    tool_input={
        "customer_id": "<customer_id>",
    },
    connection_name="paddle",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `paddle_addresses_list`

List Customer Addresses · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`string`, required): Paddle ID of the customer whose addresses to list (starts with ctm_). Get it from paddle_customers_list. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
- `after` (`string`, optional): 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
- `id` (`string`, optional): Comma-separated Paddle IDs to return only those addresses. Example: add_01hv8gwdfkw5z6d1yy6pa3xyrz
- `order_by` (`string`, optional): 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_page` (`integer`, optional): Number of entities to return per page, up to 200. Paddle defaults to 50. Example: 25
- `search` (`string`, optional): Text to search for in the address fields (all except status and timestamps). Example: London
- `status` (`string`, optional): Comma-separated statuses to filter by. Allowed values: active, archived. Paddle returns only active records by default. Example: active

Example input: `{"customer_id":"<customer_id>"}`

### `paddle_adjustments_list`

List Adjustments · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `action` (`string`, optional): Comma-separated actions to filter by. Allowed values: credit, refund, chargeback, chargeback_reverse, chargeback_warning, chargeback_warning_reverse, credit_reverse. Example: refund
- `after` (`string`, optional): 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_id` (`string`, optional): Comma-separated customer IDs; returns only their adjustments. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
- `id` (`string`, optional): Comma-separated Paddle IDs to return only those adjustments. Example: adj_01hvgf2s84dr6reszzg29zbvcm
- `order_by` (`string`, optional): 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_page` (`integer`, optional): Number of entities to return per page, up to 50. Paddle defaults to 10. Example: 25
- `status` (`string`, optional): Comma-separated statuses to filter by. Allowed values: pending_approval, approved, rejected, reversed. Example: pending_approval
- `subscription_id` (`string`, optional): Comma-separated subscription IDs; returns only their adjustments. Example: sub_01hv8y5ehszzq0yv20ttx3166y
- `transaction_id` (`string`, optional): Comma-separated transaction IDs; returns only their adjustments. Example: txn_01hv8wptq8987qeep44cyrewp9

Example input: `{}`

### `paddle_customer_get`

Get Customer · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`string`, required): Paddle ID of the customer (starts with ctm_). Get it from paddle_customers_list. Example: ctm_01hrffh7gvp29kc7xahm8wddwa

Example input: `{"customer_id":"<customer_id>"}`

### `paddle_customers_list`

List Customers · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `after` (`string`, optional): 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
- `email` (`string`, optional): Comma-separated email addresses to match exactly (up to 100). Example: sam@example.com
- `id` (`string`, optional): Comma-separated Paddle IDs to return only those customers. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
- `order_by` (`string`, optional): 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_page` (`integer`, optional): Number of entities to return per page, up to 200. Paddle defaults to 50. Example: 25
- `search` (`string`, optional): Text to search for in customer IDs, names and emails (up to 100 characters). Use email for an exact email match. Example: sam
- `status` (`string`, optional): Comma-separated statuses to filter by. Allowed values: active, archived. Paddle returns only active records by default. Example: active

Example input: `{}`

### `paddle_discounts_list`

List Discounts · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `after` (`string`, optional): 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
- `code` (`string`, optional): Comma-separated discount codes to match. Example: BF20OFF
- `discount_group_id` (`string`, optional): Comma-separated discount group IDs; returns only discounts in these groups. Example: dsg_01gtf15svsqzgp9325ss4ebmwt
- `id` (`string`, optional): Comma-separated Paddle IDs to return only those discounts. Example: dsc_01hv6scyf7qdnzcdq01t2y8dx4
- `mode` (`string`, optional): Discount mode to filter by: standard (catalog discounts) or custom (non-catalog, e.g. checkout recovery). Example: standard. One of: `standard`, `custom`.
- `order_by` (`string`, optional): 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_page` (`integer`, optional): Number of entities to return per page, up to 200. Paddle defaults to 50. Example: 25
- `status` (`string`, optional): Comma-separated statuses to filter by. Allowed values: active, archived. Paddle returns only active records by default. Example: active

Example input: `{}`

### `paddle_price_get`

Get Price · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `price_id` (`string`, required): Paddle ID of the price (starts with pri_). Get it from paddle_prices_list. Example: pri_01gsz8x8sawmvhz1pv30nge1ke
- `include` (`string`, optional): Set to product to include the related product in the response. Example: product. One of: `product`.

Example input: `{"price_id":"<price_id>"}`

### `paddle_prices_list`

List Prices · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `after` (`string`, optional): 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_frequency` (`integer`, optional): Return only prices whose billing cycle frequency matches this number, e.g. 3 with interval month for quarterly prices. Example: 1
- `billing_cycle_interval` (`string`, optional): Return only prices that bill on this interval: day, week, month or year. Example: month. One of: `day`, `week`, `month`, `year`.
- `id` (`string`, optional): Comma-separated Paddle IDs to return only those prices. Example: pri_01gsz8x8sawmvhz1pv30nge1ke
- `include` (`string`, optional): Set to product to include each price's related product in the response. Example: product. One of: `product`.
- `order_by` (`string`, optional): 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_page` (`integer`, optional): Number of entities to return per page, up to 200. Paddle defaults to 50. Example: 25
- `product_id` (`string`, optional): Comma-separated product IDs; returns only prices for these products. Example: pro_01htz88xpr0mm7b3ta2pjkr7w2
- `recurring` (`boolean`, optional): true returns only recurring (subscription) prices; false returns only one-time prices. Example: true
- `status` (`string`, optional): Comma-separated statuses to filter by. Allowed values: active, archived. Paddle returns only active records by default. Example: active
- `type` (`string`, optional): Item type to filter by: standard (catalog) or custom (non-catalog). Example: standard. One of: `standard`, `custom`.

Example input: `{}`

### `paddle_product_get`

Get Product · Read-only

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.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `product_id` (`string`, required): Paddle ID of the product (starts with pro_). Get it from paddle_products_list. Example: pro_01htz88xpr0mm7b3ta2pjkr7w2
- `include` (`string`, optional): Set to prices to include the product's related prices in the response. Example: prices. One of: `prices`.

Example input: `{"product_id":"<product_id>"}`

### `paddle_products_list`

List Products · Read-only

List products in the Paddle catalog, filtered by status, tax category or type.
Returns a page of products (id, name, description, tax_category, status, custom_data, optionally their prices) plus meta.pagination.
Use this to browse or find products; use paddle_product_get when you already have a product ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `after` (`string`, optional): 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: pro_01htz88xpr0mm7b3ta2pjkr7w2
- `id` (`string`, optional): Comma-separated Paddle IDs to return only those products. Example: pro_01htz88xpr0mm7b3ta2pjkr7w2,pro_01gsz97mq9pa4fkyy0wqenepkz
- `include` (`string`, optional): Set to prices to include each product's related prices in the response. Example: prices. One of: `prices`.
- `order_by` (`string`, optional): 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]`, `custom_data[ASC]`, `custom_data[DESC]`, `description[ASC]`, `description[DESC]`, `id[ASC]`, `id[DESC]`, `image_url[ASC]`, `image_url[DESC]`, `name[ASC]`, `name[DESC]`, `status[ASC]`, `status[DESC]`, `tax_category[ASC]`, `tax_category[DESC]`, `updated_at[ASC]`, `updated_at[DESC]`.
- `per_page` (`integer`, optional): Number of entities to return per page, up to 200. Paddle defaults to 50. Example: 25
- `status` (`string`, optional): Comma-separated statuses to filter by. Allowed values: active, archived. Paddle returns only active records by default. Example: active
- `tax_category` (`string`, optional): Comma-separated tax categories to filter by. Allowed values: digital-goods, ebooks, implementation-services, professional-services, saas, software-programming-services, standard, training-services, website-hosting. Example: saas
- `type` (`string`, optional): Item type to filter by: standard (catalog items) or custom (non-catalog items created for one transaction or subscription). Example: standard. One of: `standard`, `custom`.

Example input: `{}`

### `paddle_subscription_get`

Get Subscription · Read-only

Get one subscription by its Paddle ID.
Returns the subscription's status, customer, address, items with prices, billing cycle, current_billing_period, next_billed_at, discount, scheduled_change and management URLs; optionally a preview of the next transaction.
Use this when you have a subscription ID; use paddle_subscriptions_list to find one.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `subscription_id` (`string`, required): Paddle ID of the subscription (starts with sub_). Get it from paddle_subscriptions_list. Example: sub_01hv8y5ehszzq0yv20ttx3166y
- `include` (`string`, optional): Comma-separated related data to include: next_transaction (preview of the next bill, with prorated and one-time charges) and/or recurring_transaction_details (preview of the regular recurring bill). Example: next_transaction

Example input: `{"subscription_id":"<subscription_id>"}`

### `paddle_subscriptions_list`

List Subscriptions · Read-only

List subscriptions, filtered by customer, price, address, status, collection mode or scheduled change.
Returns a page of subscriptions (id, status, customer_id, address_id, currency_code, items, current_billing_period, next_billed_at, scheduled_change, collection_mode) plus meta.pagination.
Use this to find a customer's subscriptions; use paddle_subscription_get when you already have a subscription ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `address_id` (`string`, optional): Comma-separated address IDs; returns only subscriptions for these addresses. Example: add_01hv8gwdfkw5z6d1yy6pa3xyrz
- `after` (`string`, optional): 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: sub_01hv8y5ehszzq0yv20ttx3166y
- `collection_mode` (`string`, optional): Return only subscriptions with this collection mode: automatic (card or saved payment method) or manual (invoiced). Example: automatic. One of: `automatic`, `manual`.
- `customer_id` (`string`, optional): Comma-separated customer IDs; returns only their subscriptions. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
- `id` (`string`, optional): Comma-separated Paddle IDs to return only those subscriptions. Example: sub_01hv8y5ehszzq0yv20ttx3166y
- `order_by` (`string`, optional): 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_page` (`integer`, optional): Number of entities to return per page, up to 200. Paddle defaults to 50. Example: 25
- `price_id` (`string`, optional): Comma-separated price IDs; returns only subscriptions that include these prices. Example: pri_01gsz8x8sawmvhz1pv30nge1ke
- `scheduled_change_action` (`string`, optional): Comma-separated scheduled change actions to filter by. Allowed values: cancel, pause, resume, none. Example: cancel
- `status` (`string`, optional): Comma-separated subscription statuses to filter by. Allowed values: active, canceled, past_due, paused, trialing. Example: active,trialing

Example input: `{}`

### `paddle_transaction_get`

Get Transaction · Read-only

Get one transaction by its Paddle ID.
Returns the transaction's status, customer, address, subscription, items, line-item totals (details.line_items[].id are needed for partial refunds), payments, invoice number and checkout URL; optionally related entities.
Use this when you have a transaction ID; use paddle_transactions_list to find one and paddle_transaction_invoice_get for its PDF.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `transaction_id` (`string`, required): Paddle ID of the transaction (starts with txn_). Get it from paddle_transactions_list. Example: txn_01hv8wptq8987qeep44cyrewp9
- `include` (`string`, optional): Comma-separated related entities to include: address, adjustments, adjustments_totals, available_payment_methods, business, customer, discount. Example: customer,address

Example input: `{"transaction_id":"<transaction_id>"}`

### `paddle_transaction_invoice_get`

Get Transaction Invoice PDF · Read-only

Get a temporary link to the PDF invoice for a transaction. The link expires after one hour.
Returns data.url, the PDF download URL.
Use this for billed or completed manual invoices and completed automatic transactions; zero-value transactions have no PDF. Use paddle_transaction_get for the transaction's data.
Requires a transaction ID from paddle_transactions_list.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `transaction_id` (`string`, required): Paddle ID of the transaction (starts with txn_). Get it from paddle_transactions_list. Example: txn_01hv8wptq8987qeep44cyrewp9
- `disposition` (`string`, optional): attachment (Paddle's default) makes the URL download the PDF; inline makes it open in the browser. Example: inline. One of: `attachment`, `inline`.

Example input: `{"transaction_id":"<transaction_id>"}`

### `paddle_transactions_list`

List Transactions · Read-only

List transactions (checkouts, invoices, renewals and one-time charges), filtered by customer, subscription, status, origin, invoice number or date.
Returns up to 30 transactions per page (id, status, customer_id, subscription_id, origin, invoice_number, currency_code, items, details.totals, billed_at, created_at) plus meta.pagination.
Use this to review billing history; use paddle_transaction_get when you already have a transaction ID.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `after` (`string`, optional): 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: txn_01hv8wptq8987qeep44cyrewp9
- `billed_after` (`string`, optional): Return transactions billed at or after this RFC 3339 date-time. Example: 2025-01-01T00:00:00Z
- `billed_before` (`string`, optional): Return transactions billed before this RFC 3339 date-time. Example: 2025-02-01T00:00:00Z
- `collection_mode` (`string`, optional): Return only transactions with this collection mode: automatic or manual (invoices). Example: manual. One of: `automatic`, `manual`.
- `created_after` (`string`, optional): Return transactions created at or after this RFC 3339 date-time. Example: 2025-01-01T00:00:00Z
- `created_before` (`string`, optional): Return transactions created before this RFC 3339 date-time. Example: 2025-02-01T00:00:00Z
- `customer_id` (`string`, optional): Comma-separated customer IDs; returns only their transactions. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
- `id` (`string`, optional): Comma-separated Paddle IDs to return only those transactions. Example: txn_01hv8wptq8987qeep44cyrewp9
- `include` (`string`, optional): Comma-separated related entities to include: address, adjustments, adjustments_totals, available_payment_methods, business, customer, discount. Example: customer,address
- `invoice_number` (`string`, optional): Comma-separated invoice numbers to match. Example: 123-45678
- `order_by` (`string`, optional): Field and direction to sort by, written as field[ASC] or field[DESC]. Paddle defaults to id[DESC]. Example: billed_at[DESC]. One of: `billed_at[ASC]`, `billed_at[DESC]`, `created_at[ASC]`, `created_at[DESC]`, `id[ASC]`, `id[DESC]`, `updated_at[ASC]`, `updated_at[DESC]`.
- `origin` (`string`, optional): Comma-separated origins to filter by. Allowed values: api, subscription_charge, subscription_payment_method_change, subscription_recurring, subscription_update, subscription_import, web. Example: subscription_recurring
- `per_page` (`integer`, optional): Number of entities to return per page, up to 30. Paddle defaults to 30. Example: 25
- `status` (`string`, optional): Comma-separated statuses to filter by. Allowed values: draft, ready, billed, paid, completed, canceled, past_due. Example: completed
- `subscription_id` (`string`, optional): Comma-separated subscription IDs; returns only their transactions. Example: sub_01hv8y5ehszzq0yv20ttx3166y

Example input: `{}`

### `paddle_address_create`

Create Customer Address · Write

Add an address to a customer. Paddle uses addresses to calculate tax.
Returns the new address with its add_ ID.
Use this before creating a transaction that needs an address_id; use paddle_address_update to change an existing address.
Requires a customer ID from paddle_customers_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `country_code` (`string`, required): Two-letter ISO 3166-1 alpha-2 country code of the address. Example: US
- `customer_id` (`string`, required): Paddle ID of the customer to add the address to (starts with ctm_). Get it from paddle_customers_list. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
- `city` (`string`, optional): City of the address. Example: Astoria
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `description` (`string`, optional): Memorable label for the address, for your reference. Example: Head Office
- `first_line` (`string`, optional): First line of the street address. Example: 3811 Ditmars Blvd
- `postal_code` (`string`, optional): ZIP or postal code. Paddle requires it for some countries, such as the US (ZIP code) and the UK (postcode). Example: 10021
- `region` (`string`, optional): State, county or region of the address. Example: NY
- `second_line` (`string`, optional): Second line of the street address, such as an apartment or suite. Example: Suite 200

Example input: `{"country_code":"<country_code>","customer_id":"<customer_id>"}`

### `paddle_address_update`

Update Customer Address · Write

Update a customer's address fields, custom data or status. Only the fields you send change.
Returns the updated address.
Use status archived to retire an address (addresses can't be deleted). Use paddle_address_create to add a new one.
Requires the customer ID and address ID from paddle_addresses_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `address_id` (`string`, required): Paddle ID of the address to update (starts with add_). Get it from paddle_addresses_list. Example: add_01hv8gwdfkw5z6d1yy6pa3xyrz
- `customer_id` (`string`, required): Paddle ID of the customer the address belongs to (starts with ctm_). Get it from paddle_customers_list. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
- `city` (`string`, optional): City of the address. Example: Astoria
- `country_code` (`string`, optional): Two-letter ISO 3166-1 alpha-2 country code of the address. Example: US
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `description` (`string`, optional): Memorable label for the address, for your reference. Example: Head Office
- `first_line` (`string`, optional): First line of the street address. Example: 3811 Ditmars Blvd
- `postal_code` (`string`, optional): ZIP or postal code. Paddle requires it for some countries, such as the US (ZIP code) and the UK (postcode). Example: 10021
- `region` (`string`, optional): State, county or region of the address. Example: NY
- `second_line` (`string`, optional): Second line of the street address, such as an apartment or suite. Example: Suite 200
- `status` (`string`, optional): Set to archived to retire the address, or active to restore it. Example: archived. One of: `active`, `archived`.

Example input: `{"address_id":"<address_id>","customer_id":"<customer_id>"}`

### `paddle_adjustment_create`

Create Adjustment · Write

Refund or credit all or part of a transaction. Refunds go back to the customer's payment method for completed transactions; credits reduce the amount due on billed or past-due manual invoices.
Returns the new adjustment with its adj_ ID and status; most live refunds start as pending_approval until Paddle reviews them.
Use paddle_adjustments_list to check an adjustment's status later.
Requires a transaction ID, and for partial adjustments the line item IDs (details.line_items[].id) from paddle_transaction_get.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `action` (`string`, required): refund returns money to the customer's payment method (completed transactions); credit reduces the amount due on a billed or past-due manually-collected transaction. Example: refund. One of: `refund`, `credit`.
- `reason` (`string`, required): Why the adjustment is being made. Shown in the Paddle dashboard and kept for records. Example: Customer requested refund for duplicate purchase
- `transaction_id` (`string`, required): Paddle ID of the transaction to refund or credit. Get it from paddle_transactions_list. Example: txn_01hv8wptq8987qeep44cyrewp9
- `items` (`array`, optional): Line items to adjust, required for a partial adjustment. Each has item_id (txnitm_ ID from details.line_items[].id in paddle_transaction_get), type (full or partial) and, for partial, amount as a string in the lowest currency unit. Example: [{"item_id": "txnitm_01hv8wt98jahpbm1t1tzr06z6n", "type": "partial", "amount": "500"}]
- `tax_mode` (`string`, optional): Whether the amounts you give include tax (internal) or exclude it, so Paddle adds tax on top (external). Example: internal. One of: `external`, `internal`.
- `type` (`string`, optional): full adjusts the transaction's whole grand total; partial (Paddle's default) adjusts only the line items you list in items. Example: full. One of: `full`, `partial`.

Example input: `{"action":"refund","reason":"<reason>","transaction_id":"<transaction_id>"}`

### `paddle_customer_create`

Create Customer · Write

Create a customer from an email address, with optional name, locale and custom data.
Returns the new customer with its ctm_ ID.
Use this before adding addresses or creating transactions for a new buyer. Paddle rejects an email that already belongs to a customer; find that one with paddle_customers_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `email` (`string`, required): Email address of the customer (unique per customer). Example: sam@example.com
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `locale` (`string`, optional): IETF BCP 47 short locale tag used for emails and documents sent to the customer. Paddle defaults to en. Example: en
- `name` (`string`, optional): Full name of the customer. Required later if you invoice them with a manually-collected transaction. Example: Sam Miller

Example input: `{"email":"<email>"}`

### `paddle_customer_update`

Update Customer · Write

Update a customer's name, email, locale, custom data or status. Only the fields you send change.
Returns the updated customer.
Use status archived to retire a customer (customers can't be deleted). Use paddle_customer_create for a new customer.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `customer_id` (`string`, required): Paddle ID of the customer to update (starts with ctm_). Get it from paddle_customers_list. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `email` (`string`, optional): Email address of the customer (unique per customer). Example: sam@example.com
- `locale` (`string`, optional): IETF BCP 47 short locale tag used for emails and documents sent to the customer. Paddle defaults to en. Example: en
- `name` (`string`, optional): Full name of the customer. Required later if you invoice them with a manually-collected transaction. Example: Sam Miller
- `status` (`string`, optional): Set to archived to retire the customer, or active to restore it. Example: archived. One of: `active`, `archived`.

Example input: `{"customer_id":"<customer_id>"}`

### `paddle_discount_create`

Create Discount · Write

Create a percentage, flat or per-seat discount, optionally with a checkout code, usage limit, expiry and product restrictions.
Returns the new discount with its dsc_ ID.
Use this to set up a promotion; apply it with paddle_transaction_create (discount_id) or paddle_subscription_update (discount). Use paddle_discount_update to change one.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `amount` (`string`, required): Amount to discount, as a string. For percentage, a value from 0.01 to 100; for flat and flat_per_seat, the amount in the lowest currency unit (e.g. "500" for 5.00 USD). Example: 20
- `description` (`string`, required): Short description of the discount for your reference, not shown to customers (1-500 characters). Example: Black Friday 2025
- `type` (`string`, required): Discount type: percentage (e.g. 20%), flat (a fixed amount off the total) or flat_per_seat (a fixed amount off per unit). flat and flat_per_seat need currency_code. Example: percentage. One of: `flat`, `flat_per_seat`, `percentage`.
- `code` (`string`, optional): Code customers enter at checkout to redeem the discount: letters and numbers only, up to 32 characters, not case-sensitive. Leave empty for a discount you only apply through the API. Example: BF20OFF
- `currency_code` (`string`, optional): Three-letter ISO 4217 currency code. Required for flat and flat_per_seat discounts. Example: USD
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `enabled_for_checkout` (`boolean`, optional): Whether customers can redeem the discount at checkout. Paddle defaults to true. Example: true
- `expires_at` (`string`, optional): RFC 3339 date-time after which the discount can no longer be redeemed. Leave empty for no expiry. Example: 2025-12-01T00:00:00Z
- `maximum_recurring_intervals` (`integer`, optional): Number of billing periods the discount recurs for when recur is true. Leave empty to recur forever. Example: 3
- `recur` (`boolean`, optional): Whether the discount applies to more than one subscription billing period. Paddle defaults to false. Example: true
- `restrict_to` (`array`, optional): Product (pro_) or price (pri_) IDs the discount is limited to. A product ID covers all its prices. Leave empty to apply to everything. Example: ["pro_01htz88xpr0mm7b3ta2pjkr7w2"]
- `usage_limit` (`integer`, optional): Total number of times the discount can be redeemed across all customers. Leave empty for unlimited. Example: 1000

Example input: `{"amount":"500","description":"<description>","type":"flat"}`

### `paddle_discount_update`

Update Discount · Write

Update a discount's amount, code, limits, expiry, restrictions, custom data or status. Only the fields you send change.
Returns the updated discount.
Use status archived to retire a discount (discounts can't be deleted). Use paddle_discount_create for a new discount.
Requires a discount ID from paddle_discounts_list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `discount_id` (`string`, required): Paddle ID of the discount to update (starts with dsc_). Get it from paddle_discounts_list. Example: dsc_01hv6scyf7qdnzcdq01t2y8dx4
- `amount` (`string`, optional): Amount to discount, as a string. For percentage, a value from 0.01 to 100; for flat and flat_per_seat, the amount in the lowest currency unit (e.g. "500" for 5.00 USD). Example: 20
- `code` (`string`, optional): Code customers enter at checkout to redeem the discount: letters and numbers only, up to 32 characters, not case-sensitive. Leave empty for a discount you only apply through the API. Example: BF20OFF
- `currency_code` (`string`, optional): Three-letter ISO 4217 currency code. Required for flat and flat_per_seat discounts. Example: USD
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `description` (`string`, optional): Short description of the discount for your reference, not shown to customers (1-500 characters). Example: Black Friday 2025
- `enabled_for_checkout` (`boolean`, optional): Whether customers can redeem the discount at checkout. Paddle defaults to true. Example: true
- `expires_at` (`string`, optional): RFC 3339 date-time after which the discount can no longer be redeemed. Leave empty for no expiry. Example: 2025-12-01T00:00:00Z
- `maximum_recurring_intervals` (`integer`, optional): Number of billing periods the discount recurs for when recur is true. Leave empty to recur forever. Example: 3
- `recur` (`boolean`, optional): Whether the discount applies to more than one subscription billing period. Paddle defaults to false. Example: true
- `restrict_to` (`array`, optional): Product (pro_) or price (pri_) IDs the discount is limited to. A product ID covers all its prices. Leave empty to apply to everything. Example: ["pro_01htz88xpr0mm7b3ta2pjkr7w2"]
- `status` (`string`, optional): Set to archived to retire the discount, or active to restore it. Example: archived. One of: `active`, `archived`.
- `type` (`string`, optional): Discount type: percentage (e.g. 20%), flat (a fixed amount off the total) or flat_per_seat (a fixed amount off per unit). flat and flat_per_seat need currency_code. Example: percentage. One of: `flat`, `flat_per_seat`, `percentage`.
- `usage_limit` (`integer`, optional): Total number of times the discount can be redeemed across all customers. Leave empty for unlimited. Example: 1000

Example input: `{"discount_id":"<discount_id>"}`

### `paddle_price_create`

Create Price · Write

Create a price for an existing product, either one-time or recurring.
Returns the new price with its pri_ ID.
Use this after paddle_product_create to define how a product is charged; use paddle_price_update to change an existing price.
Requires a product ID from paddle_products_list or paddle_product_create.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `description` (`string`, required): Internal description of the price for your team, not shown to customers (2-500 characters). Example: Monthly (per seat)
- `product_id` (`string`, required): Paddle ID of the product this price is for. Get it from paddle_products_list. Example: pro_01htz88xpr0mm7b3ta2pjkr7w2
- `unit_price` (`object`, required): Base price as an object with amount (a string in the lowest currency unit, e.g. "1000" for 10.00 USD) and a three-letter currency_code. Example: {"amount": "1000", "currency_code": "USD"}
- `billing_cycle` (`object`, optional): How often a recurring price charges, as an object with interval (day, week, month or year) and frequency (a whole number). Leave empty for a one-time price. Example: {"interval": "month", "frequency": 1}
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `name` (`string`, optional): Name of the price shown to customers at checkout and on invoices, typically how often it bills (1-150 characters). Example: Monthly
- `quantity` (`object`, optional): Minimum and maximum quantity a customer can buy at this price. Paddle defaults to 1-100. Example: {"minimum": 1, "maximum": 999}
- `tax_mode` (`string`, optional): How tax is calculated: account_setting (use your account default), external (prices exclude tax), internal (prices include tax) or location (depends on the customer's country). Paddle defaults to account_setting. Example: account_setting. One of: `account_setting`, `external`, `internal`, `location`.
- `trial_period` (`object`, optional): Free or discounted trial before billing starts, as an object with interval and frequency (and optionally requires_payment_method). Needs a billing_cycle. Example: {"interval": "day", "frequency": 14}
- `type` (`string`, optional): Item type: standard for a catalog price (the default) or custom for a non-catalog price. Example: standard. One of: `standard`, `custom`.
- `unit_price_overrides` (`array`, optional): Country-specific prices that replace the base price for customers in those countries. Each override has country_codes (two-letter codes) and a unit_price object. Example: [{"country_codes": ["GB"], "unit_price": {"amount": "900", "currency_code": "GBP"}}]

Example input: `{"description":"<description>","product_id":"<product_id>","unit_price":{"amount":"1000","currency_code":"USD"}}`

### `paddle_price_update`

Update Price · Write

Update a price's amount, name, billing cycle, trial, tax mode, overrides, quantity limits, custom data or status. Only the fields you send change.
Returns the updated price.
Use status archived to retire a price (prices can't be deleted). Use paddle_price_create for a new price.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `price_id` (`string`, required): Paddle ID of the price to update (starts with pri_). Get it from paddle_prices_list. Example: pri_01gsz8x8sawmvhz1pv30nge1ke
- `billing_cycle` (`object`, optional): How often a recurring price charges, as an object with interval (day, week, month or year) and frequency (a whole number). Leave empty for a one-time price. Example: {"interval": "month", "frequency": 1}
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `description` (`string`, optional): Internal description of the price for your team, not shown to customers (2-500 characters). Example: Monthly (per seat)
- `name` (`string`, optional): Name of the price shown to customers at checkout and on invoices, typically how often it bills (1-150 characters). Example: Monthly
- `quantity` (`object`, optional): Minimum and maximum quantity a customer can buy at this price. Paddle defaults to 1-100. Example: {"minimum": 1, "maximum": 999}
- `status` (`string`, optional): Set to archived to retire the price, or active to restore it. Example: archived. One of: `active`, `archived`.
- `tax_mode` (`string`, optional): How tax is calculated: account_setting (use your account default), external (prices exclude tax), internal (prices include tax) or location (depends on the customer's country). Paddle defaults to account_setting. Example: account_setting. One of: `account_setting`, `external`, `internal`, `location`.
- `trial_period` (`object`, optional): Free or discounted trial before billing starts, as an object with interval and frequency (and optionally requires_payment_method). Needs a billing_cycle. Example: {"interval": "day", "frequency": 14}
- `type` (`string`, optional): Item type: standard for a catalog price (the default) or custom for a non-catalog price. Example: standard. One of: `standard`, `custom`.
- `unit_price` (`object`, optional): Base price as an object with amount (a string in the lowest currency unit, e.g. "1000" for 10.00 USD) and a three-letter currency_code. Example: {"amount": "1000", "currency_code": "USD"}
- `unit_price_overrides` (`array`, optional): Country-specific prices that replace the base price for customers in those countries. Each override has country_codes (two-letter codes) and a unit_price object. Example: [{"country_codes": ["GB"], "unit_price": {"amount": "900", "currency_code": "GBP"}}]

Example input: `{"price_id":"<price_id>"}`

### `paddle_product_create`

Create Product · Write

Create a product in the Paddle catalog.
Returns the new product with its pro_ ID.
Use this to add something you sell; then create its prices with paddle_price_create. Use paddle_product_update to change an existing product.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Name of the product, shown to customers at checkout and on invoices (1-200 characters). Example: AeroEdit Pro
- `tax_category` (`string`, required): Tax category Paddle uses to charge the right tax rate. It must be enabled on your Paddle account; saas and standard are enabled by default. Example: saas. One of: `digital-goods`, `ebooks`, `implementation-services`, `professional-services`, `saas`, `software-programming-services`, `standard`, `training-services`, `website-hosting`.
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `description` (`string`, optional): Short description of the product (up to 2048 characters). Example: Advanced flight planning tools for professional pilots.
- `image_url` (`string`, optional): Public HTTPS URL of a square image for the product, shown at checkout and on some customer documents. Paddle does not host the image. Example: https://example.com/images/aeroedit-pro.png
- `type` (`string`, optional): Item type: standard for a reusable catalog product (the default) or custom for a non-catalog product that is not listed or shown in the dashboard. Example: standard. One of: `standard`, `custom`.

Example input: `{"name":"<name>","tax_category":"digital-goods"}`

### `paddle_product_update`

Update Product · Write

Update a product's name, description, tax category, image, custom data or status. Only the fields you send change.
Returns the updated product.
Use status archived to retire a product (Paddle products can't be deleted). Use paddle_product_create for a new product.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `product_id` (`string`, required): Paddle ID of the product to update (starts with pro_). Get it from paddle_products_list. Example: pro_01htz88xpr0mm7b3ta2pjkr7w2
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `description` (`string`, optional): Short description of the product (up to 2048 characters). Example: Advanced flight planning tools for professional pilots.
- `image_url` (`string`, optional): Public HTTPS URL of a square image for the product, shown at checkout and on some customer documents. Paddle does not host the image. Example: https://example.com/images/aeroedit-pro.png
- `name` (`string`, optional): Name of the product, shown to customers at checkout and on invoices (1-200 characters). Example: AeroEdit Pro
- `status` (`string`, optional): Set to archived to retire the product, or active to restore it. Example: archived. One of: `active`, `archived`.
- `tax_category` (`string`, optional): Tax category Paddle uses to charge the right tax rate. It must be enabled on your Paddle account; saas and standard are enabled by default. Example: saas. One of: `digital-goods`, `ebooks`, `implementation-services`, `professional-services`, `saas`, `software-programming-services`, `standard`, `training-services`, `website-hosting`.
- `type` (`string`, optional): Item type: standard for a reusable catalog product (the default) or custom for a non-catalog product that is not listed or shown in the dashboard. Example: standard. One of: `standard`, `custom`.

Example input: `{"product_id":"<product_id>"}`

### `paddle_subscription_cancel`

Cancel Subscription · Write

Cancel a subscription, either at the end of the current billing period (the default) or immediately.
Returns the subscription with its scheduled_change (or status canceled if immediate).
Use paddle_subscription_pause to stop billing temporarily instead. A scheduled cancellation can be undone with paddle_subscription_update and remove_scheduled_change; an immediate one can't.
Requires a subscription ID from paddle_subscriptions_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `subscription_id` (`string`, required): Paddle ID of the subscription to cancel (starts with sub_). Get it from paddle_subscriptions_list. Example: sub_01hv8y5ehszzq0yv20ttx3166y
- `effective_from` (`string`, optional): When to cancel: next_billing_period (Paddle's default, schedules the change for the end of the current period) or immediately. Example: next_billing_period. One of: `next_billing_period`, `immediately`.

Example input: `{"subscription_id":"<subscription_id>"}`

### `paddle_subscription_pause`

Pause Subscription · Write

Pause a subscription at the end of the current billing period (the default) or immediately, optionally with a date to resume automatically.
Returns the subscription with its scheduled_change (or status paused if immediate).
Use paddle_subscription_resume to restart a paused subscription; use paddle_subscription_cancel to end it.
Requires a subscription ID from paddle_subscriptions_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `subscription_id` (`string`, required): Paddle ID of the subscription to pause (starts with sub_). Get it from paddle_subscriptions_list. Example: sub_01hv8y5ehszzq0yv20ttx3166y
- `effective_from` (`string`, optional): When to pause: next_billing_period (Paddle's default, schedules the change for the end of the current period) or immediately. Example: next_billing_period. One of: `next_billing_period`, `immediately`.
- `on_resume` (`string`, optional): How the billing period is set when the subscription resumes: start_new_billing_period (Paddle's default, charges for a new period from the resume date) or continue_existing_billing_period. Example: start_new_billing_period. One of: `start_new_billing_period`, `continue_existing_billing_period`.
- `resume_at` (`string`, optional): RFC 3339 date-time when the subscription should resume automatically. Leave empty to pause until resumed. Example: 2025-09-01T00:00:00Z

Example input: `{"subscription_id":"<subscription_id>"}`

### `paddle_subscription_resume`

Resume Subscription · Write

Resume a paused subscription immediately or on a set date, or change the resume date of a scheduled resume.
Returns the updated subscription.
Use this only for paused subscriptions; use paddle_subscription_pause to pause one.
Requires a subscription ID from paddle_subscriptions_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `effective_from` (`string`, required): When to resume: immediately, or an RFC 3339 date-time to resume on. Example: immediately
- `subscription_id` (`string`, required): Paddle ID of the paused subscription to resume (starts with sub_). Get it from paddle_subscriptions_list. Example: sub_01hv8y5ehszzq0yv20ttx3166y
- `on_resume` (`string`, optional): How the billing period is set when the subscription resumes: start_new_billing_period (Paddle's default, charges for a new period from the resume date) or continue_existing_billing_period. Example: start_new_billing_period. One of: `start_new_billing_period`, `continue_existing_billing_period`.

Example input: `{"effective_from":"<effective_from>","subscription_id":"<subscription_id>"}`

### `paddle_subscription_update`

Update Subscription · Write

Update a subscription: change its items, quantities, customer, address, currency, next billing date, discount, collection mode, billing details or custom data. Only the fields you send change.
Returns the updated subscription.
Use paddle_subscription_cancel, paddle_subscription_pause or paddle_subscription_resume to cancel, pause or resume instead. Changes to items, quantities or the next billing date need proration_billing_mode.
Requires a subscription ID from paddle_subscriptions_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `subscription_id` (`string`, required): Paddle ID of the subscription to update (starts with sub_). Get it from paddle_subscriptions_list. Example: sub_01hv8y5ehszzq0yv20ttx3166y
- `address_id` (`string`, optional): Paddle ID of a different address for the subscription; it must belong to the subscription's customer. Example: add_01hv8gwdfkw5z6d1yy6pa3xyrz
- `billing_details` (`object`, optional): Invoicing details, required when collection_mode is manual: payment_terms (interval and frequency), and optionally enable_checkout, purchase_order_number and additional_information. Example: {"payment_terms": {"interval": "day", "frequency": 30}, "enable_checkout": false}
- `collection_mode` (`string`, optional): How payment is collected: automatic (saved payment method) or manual (invoices; needs billing_details). Example: manual. One of: `automatic`, `manual`.
- `currency_code` (`string`, optional): Three-letter ISO 4217 currency code to bill in. Manually-collected subscriptions must use USD, EUR or GBP. Example: USD
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `customer_id` (`string`, optional): Paddle ID of a different customer to move the subscription to. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
- `discount` (`object`, optional): Discount to apply, as an object with the discount id and effective_from (immediately or next_billing_period). Example: {"id": "dsc_01hv6scyf7qdnzcdq01t2y8dx4", "effective_from": "next_billing_period"}
- `items` (`array`, optional): The complete list of recurring items the subscription should have after the update, each with price_id and quantity. Items you leave out are removed. Example: [{"price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 20}]
- `next_billed_at` (`string`, optional): New RFC 3339 date-time for the next bill. Example: 2025-06-01T00:00:00Z
- `on_payment_failure` (`string`, optional): What to do if the payment for the change fails: prevent_change (Paddle's default) or apply_change. Example: prevent_change. One of: `prevent_change`, `apply_change`.
- `proration_billing_mode` (`string`, optional): How Paddle bills for the change. prorated_immediately and full_immediately charge now; prorated_next_billing_period and full_next_billing_period add the charge to the next bill; do_not_bill makes no charge. Required when the change affects billing. Example: prorated_immediately. One of: `prorated_immediately`, `prorated_next_billing_period`, `full_immediately`, `full_next_billing_period`, `do_not_bill`.
- `remove_discount` (`boolean`, optional): Set to true to remove the subscription's current discount. Leave empty to keep it. Example: true
- `remove_scheduled_change` (`boolean`, optional): Set to true to remove a scheduled cancel, pause or resume, for example to undo a cancellation at the end of the billing period. Example: true

Example input: `{"subscription_id":"<subscription_id>"}`

### `paddle_transaction_create`

Create Transaction · Write

Create a transaction to bill a customer, for a checkout (automatic collection) or an invoice (manual collection).
Returns the new transaction with its txn_ ID, status (draft or ready, or billed if requested), totals and checkout.url payment link.
Use this to charge for catalog prices or send an invoice. To charge an existing subscription, use paddle_subscription_update instead.
Requires price IDs from paddle_prices_list; customer and address IDs come from paddle_customers_list and paddle_addresses_list.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `items` (`array`, required): Items to charge for, each with a price_id and a quantity. Example: [{"price_id": "pri_01gsz8x8sawmvhz1pv30nge1ke", "quantity": 1}]
- `address_id` (`string`, optional): Paddle ID of the customer's address, used for tax. Needs customer_id. Without it the transaction stays draft. Example: add_01hv8gwdfkw5z6d1yy6pa3xyrz
- `billing_details` (`object`, optional): Invoicing details, required when collection_mode is manual: payment_terms (interval and frequency), and optionally enable_checkout, purchase_order_number and additional_information. Example: {"payment_terms": {"interval": "day", "frequency": 14}, "enable_checkout": true}
- `collection_mode` (`string`, optional): How payment is collected: automatic (Paddle Checkout, the default) or manual (an invoice; needs billing_details). Example: automatic. One of: `automatic`, `manual`.
- `currency_code` (`string`, optional): Three-letter ISO 4217 currency code. Must be USD, EUR or GBP when collection_mode is manual. Example: USD
- `custom_data` (`object`, optional): Your own key-value data to store on the entity. Example: {"crm_id": "12345"}
- `customer_id` (`string`, optional): Paddle ID of the customer to bill. Without it the transaction stays draft. Example: ctm_01hrffh7gvp29kc7xahm8wddwa
- `discount_id` (`string`, optional): Paddle ID of a discount to apply. Example: dsc_01hv6scyf7qdnzcdq01t2y8dx4
- `include` (`string`, optional): Comma-separated related entities to include: address, adjustments, adjustments_totals, available_payment_methods, business, customer, discount. Example: customer,address
- `status` (`string`, optional): Set to billed to issue the transaction right away (for manual invoices it becomes a legal record and can't be edited). Leave empty to let Paddle set draft or ready. Example: billed. One of: `billed`.

Example input: `{"items":[{"price_id":"pri_01gsz8x8sawmvhz1pv30nge1ke","quantity":1}]}`

## Related

Other Accounting & Finance connectors ([all 82](/agentkit/connectors/?category=accounting-finance)):

- [QuickBooks](/agentkit/connectors/quickbooks/): Scalekit connector, OAuth, 117 tools
- [Xero](/agentkit/connectors/xero/): Scalekit connector, OAuth, 94 tools
- [Stripe](/agentkit/connectors/stripe/): Scalekit connector, Access token, 178 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
