# Paddle

> Manage your Paddle billing catalog end to end: build products and prices, create and update customers and their addresses, invoice them with transactions, and read, pause, resume or cancel the subscriptions billing them creates.

App · Payments & Billing · 20 actions. Web page: https://docs.lodol.com/docs/integrations/paddle

## Actions

### Cancel subscription

Cancel a subscription. This cannot be undone - Paddle does not allow reinstating a canceled subscription, only replacing it with a new one.

**Inputs**

- Subscription (`subscription_id`, text, required): The subscription's ID, from 'List subscriptions'.
- Effective from (`effective_from`, text): When the cancellation takes effect. Defaults to the end of the current billing period. One of: `next_billing_period` (At the end of the current billing period), `immediately`.

**Outputs**

- `address_id` (text)
- `billing_cycle` (object)
- `business_id` (text)
- `canceled_at` (text)
- `collection_mode` (text)
- `created_at` (text)
- `currency_code` (text)
- `current_billing_period` (object)
- `custom_data` (object)
- `customer_id` (text)
- `first_billed_at` (text)
- `id` (text)
- `items` (list)
- `next_billed_at` (text)
- `paused_at` (text)
- `scheduled_change` (object)
- `started_at` (text)
- `status` (text)
- `updated_at` (text)

**Example output**

```json
{
  "address_id": "add_01h8xd1n8v0j3g2n7bqf6q3z9y",
  "billing_cycle": {
    "frequency": 1,
    "interval": "month"
  },
  "business_id": null,
  "canceled_at": null,
  "collection_mode": "manual",
  "created_at": "2026-02-02T16:40:15.000Z",
  "currency_code": "USD",
  "current_billing_period": {
    "ends_at": "2026-03-02T16:40:15.000Z",
    "starts_at": "2026-02-02T16:40:15.000Z"
  },
  "custom_data": null,
  "customer_id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
  "first_billed_at": "2026-02-02T16:40:15.000Z",
  "id": "sub_01h8xd6t2b4x5y6z7a8b9c0d1e",
  "items": [
    {
      "next_billed_at": "2026-03-02T16:40:15.000Z",
      "price": {
        "billing_cycle": {
          "frequency": 1,
          "interval": "month"
        },
        "description": "Lodol QA monthly price",
        "id": "pri_01h8xcmy7v3ktcq4f7v5v9w3ke",
        "product_id": "pro_01h8xce4qyjr8ka1krs6knmjys",
        "unit_price": {
          "amount": "1000",
          "currency_code": "USD"
        }
      },
      "quantity": 1,
      "status": "active"
    }
  ],
  "next_billed_at": "2026-03-02T16:40:15.000Z",
  "paused_at": null,
  "scheduled_change": null,
  "started_at": "2026-02-02T16:40:15.000Z",
  "status": "canceled",
  "updated_at": "2026-02-02T16:40:15.000Z"
}
```

### Create customer

Create a customer. Fill in 'Name' now if you plan to invoice them later with 'Create transaction' - Paddle requires it before a manually-collected transaction can be created.

**Inputs**

- Email (`email`, text, required): The customer's email.
- Name (`name`, text): The customer's name.
- Locale (`locale`, text): An IETF locale tag such as 'en' or 'fr'. Defaults to 'en'.
- Custom data (`custom_data`, object): Arbitrary JSON to attach, such as {"internal_id": "123"}. Leave empty for none.

**Outputs**

- `created_at` (text)
- `custom_data` (object)
- `email` (text)
- `id` (text)
- `locale` (text)
- `marketing_consent` (true/false)
- `name` (text)
- `status` (text)
- `updated_at` (text)

**Example output**

```json
{
  "created_at": "2026-02-02T16:40:13.000Z",
  "custom_data": null,
  "email": "ada+lodolqa@example.com",
  "id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
  "locale": "en",
  "marketing_consent": false,
  "name": "Ada Lovelace",
  "status": "active",
  "updated_at": "2026-02-02T16:40:13.000Z"
}
```

### Create customer address

Add an address to a customer. This is what Paddle uses to work out tax, and is needed before a transaction can be billed to them.

**Inputs**

- Customer (`customer_id`, text, required): The customer's ID, from 'List customers' or 'Create customer'.
- Country (`country_code`, text, required): A two-letter country code, such as US, GB or DE.
- Description (`description`, text): What this address is for, such as 'HQ' or 'Billing'.
- Address line 1 (`first_line`, text): Street address. Optional here, but required (along with city, region and postal code) before this address can be billed on a manual-collection transaction - Paddle invoicing the customer.
- Address line 2 (`second_line`, text): Apartment, suite, etc.
- City (`city`, text): City or town. Optional here, but required (along with address line 1, region and postal code) before this address can be billed on a manual-collection transaction - Paddle invoicing the customer.
- Postal code (`postal_code`, text): Required for some countries before a transaction can be billed, and always required (along with address line 1, city and region) before this address can be billed on a manual-collection transaction - Paddle invoicing the customer.
- Region (`region`, text): State or province. Optional here, but required (along with address line 1, city and postal code) before this address can be billed on a manual-collection transaction - Paddle invoicing the customer.
- Custom data (`custom_data`, object): Arbitrary JSON to attach, such as {"internal_id": "123"}. Leave empty for none.

**Outputs**

- `city` (text)
- `country_code` (text)
- `created_at` (text)
- `custom_data` (object)
- `customer_id` (text)
- `description` (text)
- `first_line` (text)
- `id` (text)
- `postal_code` (text)
- `region` (text)
- `second_line` (text)
- `status` (text)
- `updated_at` (text)

**Example output**

```json
{
  "city": "Astoria",
  "country_code": "US",
  "created_at": "2026-02-02T16:40:14.000Z",
  "custom_data": null,
  "customer_id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
  "description": "HQ",
  "first_line": "3811 Ditmars Blvd",
  "id": "add_01h8xd1n8v0j3g2n7bqf6q3z9y",
  "postal_code": "11105",
  "region": "NY",
  "second_line": null,
  "status": "active",
  "updated_at": "2026-02-02T16:40:14.000Z"
}
```

### Create price

Create a price for a product. Leave the billing interval and frequency empty for a one-time price; set both for a recurring one - monthly is interval 'Month', frequency 1.

**Inputs**

- Product (`product_id`, text, required): The product's ID, from 'List products' or 'Create product'.
- Description (`description`, text, required): An internal label for this price. Never shown to a customer.
- Amount (`amount`, number, required): The price, as whole minor units of the currency (cents for a two-decimal one) - 1000 is ten dollars in USD. At least 0.
- Currency (`currency_code`, text, required): The currency this price is denominated in. One of: `USD` (US Dollar), `EUR` (Euro), `GBP` (British Pound), `JPY` (Japanese Yen), `AUD` (Australian Dollar), `CAD` (Canadian Dollar), `CHF` (Swiss Franc), `HKD` (Hong Kong Dollar), `SGD` (Singapore Dollar), `SEK` (Swedish Krona), and 23 more.
- Name (`name`, text): Shown to the customer at checkout. Leave empty to show nothing extra.
- Billing interval (`billing_interval`, text): Leave empty for a one-time price. One of: `day`, `week`, `month`, `year`.
- Billing frequency (`billing_frequency`, number): How many intervals between charges. 1 with 'Month' is monthly. At least 1.
- Minimum quantity (`quantity_minimum`, number): The fewest a customer can buy at once. Defaults to 1. At least 1.
- Maximum quantity (`quantity_maximum`, number): The most a customer can buy at once. Defaults to 100. At least 1.
- Custom data (`custom_data`, object): Arbitrary JSON to attach, such as {"internal_id": "123"}. Leave empty for none.

**Outputs**

- `billing_cycle` (object)
- `created_at` (text)
- `custom_data` (object)
- `description` (text)
- `id` (text)
- `name` (text)
- `product_id` (text)
- `quantity` (object)
- `status` (text)
- `tax_mode` (text)
- `trial_period` (object)
- `type` (text)
- `unit_price` (object)
- `updated_at` (text)

**Example output**

```json
{
  "billing_cycle": {
    "frequency": 1,
    "interval": "month"
  },
  "created_at": "2026-02-02T16:40:12.000Z",
  "custom_data": null,
  "description": "Lodol QA monthly price",
  "id": "pri_01h8xcmy7v3ktcq4f7v5v9w3ke",
  "name": "Monthly",
  "product_id": "pro_01h8xce4qyjr8ka1krs6knmjys",
  "quantity": {
    "maximum": 100,
    "minimum": 1
  },
  "status": "active",
  "tax_mode": "account_setting",
  "trial_period": null,
  "type": "standard",
  "unit_price": {
    "amount": "1000",
    "currency_code": "USD"
  },
  "updated_at": "2026-02-02T16:40:12.000Z"
}
```

### Create product

Create a product in the catalog. A product has no price on its own - create a price for it next with 'Create price' before billing anyone for it.

**Inputs**

- Name (`name`, text, required): The product's name.
- Tax category (`tax_category`, text, required): What kind of thing this is, for tax purposes. 'Standard' and 'SaaS' work on every account; every other category needs approval from Paddle > Catalog > Taxable Categories first. One of: `standard` (Standard (available by default)), `saas` (SaaS (available by default)), `digital-goods` (Digital goods (needs approval)), `ebooks` (E-books (needs approval)), `implementation-services` (Implementation services (needs approval)), `professional-services` (Professional services (needs approval)), `software-programming-services` (Software programming services (needs approval)), `training-services` (Training services (needs approval)), `website-hosting` (Website hosting (needs approval)).
- Description (`description`, text): An internal description. Never shown to a customer.
- Type (`product_type`, text): Leave as 'Standard' unless this is a one-off, workflow-generated product. One of: `standard` (Standard - shown in the Paddle catalog), `custom` (Custom - a one-off, not shown in the catalog). Default: `standard`.
- Image URL (`image_url`, text): An HTTPS image shown for this product at checkout.
- Custom data (`custom_data`, object): Arbitrary JSON to attach, such as {"internal_id": "123"}. Leave empty for none.

**Outputs**

- `created_at` (text)
- `custom_data` (object)
- `description` (text)
- `id` (text)
- `image_url` (text)
- `name` (text)
- `status` (text)
- `tax_category` (text)
- `type` (text)
- `updated_at` (text)

**Example output**

```json
{
  "created_at": "2026-02-02T16:40:11.123Z",
  "custom_data": null,
  "description": "A scratch product created by the Lodol QA workflow.",
  "id": "pro_01h8xce4qyjr8ka1krs6knmjys",
  "image_url": null,
  "name": "Lodol QA plan",
  "status": "active",
  "tax_category": "saas",
  "type": "standard",
  "updated_at": "2026-02-02T16:40:11.123Z"
}
```

### Create transaction

Bill one price to a customer. With a customer, address and 'Manual' collection given, set Status to 'Billed' to invoice it immediately - Paddle emails the customer and, if the price recurs, creates a subscription for them right away, with no checkout involved. Leave Customer empty to create a draft with no one billed yet.

**Inputs**

- Price (`price_id`, text, required): The price's ID, from 'List prices' or 'Create price'.
- Customer (`customer_id`, text): Only records for this customer. Leave empty for everyone.
- Address (`address_id`, text): The customer's address ID, from 'List customer addresses'. Needed before a transaction can be billed (Paddle uses it to work out tax).
- Quantity (`quantity`, number): How many of the price to bill. Defaults to 1. At least 1. Default: `1`.
- Collection mode (`collection_mode`, text): How Paddle gets paid. 'Manual' (Paddle invoices the customer) requires the address to have address line 1, city, region and postal code all set - 'Automatic' only needs the address's country. One of: `automatic` (Automatic - Paddle charges the customer's saved payment method), `manual` (Manual - Paddle issues an invoice for the customer to pay). Default: `automatic`.
- Payment term interval (`payment_term_interval`, text): Required for 'Manual' collection: how long the customer has to pay. One of: `day`, `week`, `month`, `year`.
- Payment term frequency (`payment_term_frequency`, number): Required for 'Manual' collection, alongside the interval - 14 with 'Day' is net-14. At least 1.
- Status (`status`, text): Leave empty to let Paddle decide. Set to 'billed' to invoice immediately. One of: `draft` (Draft - missing items, a customer or an address), `ready` (Ready - complete, but not yet billed), `billed` (Billed - invoiced or charged), `canceled`.
- Currency (`currency_code`, text): Overrides the price's own currency. Leave empty to use it. One of: `USD` (US Dollar), `EUR` (Euro), `GBP` (British Pound), `JPY` (Japanese Yen), `AUD` (Australian Dollar), `CAD` (Canadian Dollar), `CHF` (Swiss Franc), `HKD` (Hong Kong Dollar), `SGD` (Singapore Dollar), `SEK` (Swedish Krona), and 23 more.
- Custom data (`custom_data`, object): Arbitrary JSON to attach, such as {"internal_id": "123"}. Leave empty for none.

**Outputs**

- `address_id` (text)
- `billed_at` (text)
- `billing_details` (object)
- `business_id` (text)
- `checkout` (object)
- `collection_mode` (text)
- `created_at` (text)
- `currency_code` (text)
- `custom_data` (object)
- `customer_id` (text)
- `discount_id` (text)
- `id` (text)
- `invoice_id` (text)
- `invoice_number` (text)
- `items` (list)
- `origin` (text)
- `payments` (list)
- `status` (text)
- `subscription_id` (text)
- `updated_at` (text)

**Example output**

```json
{
  "address_id": "add_01h8xd1n8v0j3g2n7bqf6q3z9y",
  "billed_at": "2026-02-02T16:40:15.000Z",
  "billing_details": {
    "additional_information": null,
    "enable_checkout": false,
    "payment_terms": {
      "frequency": 14,
      "interval": "day"
    },
    "purchase_order_number": null
  },
  "business_id": null,
  "checkout": null,
  "collection_mode": "manual",
  "created_at": "2026-02-02T16:40:15.000Z",
  "currency_code": "USD",
  "custom_data": null,
  "customer_id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
  "discount_id": null,
  "id": "txn_01h8xd4rq9z3f7c8h9k1m2n3p4",
  "invoice_id": "inv_01h8xd6t2b4x5y6z7a8b9c0d1f",
  "invoice_number": "INV-0001",
  "items": [
    {
      "price": {
        "billing_cycle": {
          "frequency": 1,
          "interval": "month"
        },
        "description": "Lodol QA monthly price",
        "id": "pri_01h8xcmy7v3ktcq4f7v5v9w3ke",
        "product_id": "pro_01h8xce4qyjr8ka1krs6knmjys",
        "unit_price": {
          "amount": "1000",
          "currency_code": "USD"
        }
      },
      "quantity": 1
    }
  ],
  "origin": "api",
  "payments": [],
  "status": "billed",
  "subscription_id": "sub_01h8xd6t2b4x5y6z7a8b9c0d1e",
  "updated_at": "2026-02-02T16:40:15.000Z"
}
```

### Get customer

Read one customer: their name, email, locale and status.

**Inputs**

- Customer (`customer_id`, text, required): The customer's ID, from 'List customers' or 'Create customer'.

**Outputs**

- `created_at` (text)
- `custom_data` (object)
- `email` (text)
- `id` (text)
- `locale` (text)
- `marketing_consent` (true/false)
- `name` (text)
- `status` (text)
- `updated_at` (text)

**Example output**

```json
{
  "created_at": "2026-02-02T16:40:13.000Z",
  "custom_data": null,
  "email": "ada+lodolqa@example.com",
  "id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
  "locale": "en",
  "marketing_consent": false,
  "name": "Ada Lovelace",
  "status": "active",
  "updated_at": "2026-02-02T16:40:13.000Z"
}
```

### Get product

Read one product: its name, description, tax category, type and status.

**Inputs**

- Product (`product_id`, text, required): The product's ID, from 'List products' or 'Create product'.

**Outputs**

- `created_at` (text)
- `custom_data` (object)
- `description` (text)
- `id` (text)
- `image_url` (text)
- `name` (text)
- `status` (text)
- `tax_category` (text)
- `type` (text)
- `updated_at` (text)

**Example output**

```json
{
  "created_at": "2026-02-02T16:40:11.123Z",
  "custom_data": null,
  "description": "A scratch product created by the Lodol QA workflow.",
  "id": "pro_01h8xce4qyjr8ka1krs6knmjys",
  "image_url": null,
  "name": "Lodol QA plan",
  "status": "active",
  "tax_category": "saas",
  "type": "standard",
  "updated_at": "2026-02-02T16:40:11.123Z"
}
```

### Get subscription

Read one subscription: its status, billing period, next charge date and items.

**Inputs**

- Subscription (`subscription_id`, text, required): The subscription's ID, from 'List subscriptions'.

**Outputs**

- `address_id` (text)
- `billing_cycle` (object)
- `business_id` (text)
- `canceled_at` (text)
- `collection_mode` (text)
- `created_at` (text)
- `currency_code` (text)
- `current_billing_period` (object)
- `custom_data` (object)
- `customer_id` (text)
- `first_billed_at` (text)
- `id` (text)
- `items` (list)
- `next_billed_at` (text)
- `paused_at` (text)
- `scheduled_change` (object)
- `started_at` (text)
- `status` (text)
- `updated_at` (text)

**Example output**

```json
{
  "address_id": "add_01h8xd1n8v0j3g2n7bqf6q3z9y",
  "billing_cycle": {
    "frequency": 1,
    "interval": "month"
  },
  "business_id": null,
  "canceled_at": null,
  "collection_mode": "manual",
  "created_at": "2026-02-02T16:40:15.000Z",
  "currency_code": "USD",
  "current_billing_period": {
    "ends_at": "2026-03-02T16:40:15.000Z",
    "starts_at": "2026-02-02T16:40:15.000Z"
  },
  "custom_data": null,
  "customer_id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
  "first_billed_at": "2026-02-02T16:40:15.000Z",
  "id": "sub_01h8xd6t2b4x5y6z7a8b9c0d1e",
  "items": [
    {
      "next_billed_at": "2026-03-02T16:40:15.000Z",
      "price": {
        "billing_cycle": {
          "frequency": 1,
          "interval": "month"
        },
        "description": "Lodol QA monthly price",
        "id": "pri_01h8xcmy7v3ktcq4f7v5v9w3ke",
        "product_id": "pro_01h8xce4qyjr8ka1krs6knmjys",
        "unit_price": {
          "amount": "1000",
          "currency_code": "USD"
        }
      },
      "quantity": 1,
      "status": "active"
    }
  ],
  "next_billed_at": "2026-03-02T16:40:15.000Z",
  "paused_at": null,
  "scheduled_change": null,
  "started_at": "2026-02-02T16:40:15.000Z",
  "status": "active",
  "updated_at": "2026-02-02T16:40:15.000Z"
}
```

### Get transaction

Read one transaction: its status, items, billing details, invoice number once billed, and the subscription it created if its price recurs.

**Inputs**

- Transaction (`transaction_id`, text, required): The transaction's ID, from 'List transactions' or 'Create transaction'.

**Outputs**

- `address_id` (text)
- `billed_at` (text)
- `billing_details` (object)
- `business_id` (text)
- `checkout` (object)
- `collection_mode` (text)
- `created_at` (text)
- `currency_code` (text)
- `custom_data` (object)
- `customer_id` (text)
- `discount_id` (text)
- `id` (text)
- `invoice_id` (text)
- `invoice_number` (text)
- `items` (list)
- `origin` (text)
- `payments` (list)
- `status` (text)
- `subscription_id` (text)
- `updated_at` (text)

**Example output**

```json
{
  "address_id": "add_01h8xd1n8v0j3g2n7bqf6q3z9y",
  "billed_at": "2026-02-02T16:40:15.000Z",
  "billing_details": {
    "additional_information": null,
    "enable_checkout": false,
    "payment_terms": {
      "frequency": 14,
      "interval": "day"
    },
    "purchase_order_number": null
  },
  "business_id": null,
  "checkout": null,
  "collection_mode": "manual",
  "created_at": "2026-02-02T16:40:15.000Z",
  "currency_code": "USD",
  "custom_data": null,
  "customer_id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
  "discount_id": null,
  "id": "txn_01h8xd4rq9z3f7c8h9k1m2n3p4",
  "invoice_id": "inv_01h8xd6t2b4x5y6z7a8b9c0d1f",
  "invoice_number": "INV-0001",
  "items": [
    {
      "price": {
        "billing_cycle": {
          "frequency": 1,
          "interval": "month"
        },
        "description": "Lodol QA monthly price",
        "id": "pri_01h8xcmy7v3ktcq4f7v5v9w3ke",
        "product_id": "pro_01h8xce4qyjr8ka1krs6knmjys",
        "unit_price": {
          "amount": "1000",
          "currency_code": "USD"
        }
      },
      "quantity": 1
    }
  ],
  "origin": "api",
  "payments": [],
  "status": "billed",
  "subscription_id": "sub_01h8xd6t2b4x5y6z7a8b9c0d1e",
  "updated_at": "2026-02-02T16:40:15.000Z"
}
```

### List customer addresses

List the addresses saved on a customer.

**Inputs**

- Customer (`customer_id`, text, required): The customer's ID, from 'List customers' or 'Create customer'.
- Status (`status`, text): Only addresses with this status. Leave empty for both. One of: `active`, `archived`.
- After (`after`, text): Read the page after this ID. Leave empty for the first page; use the 'next_after' this action returned to read the next one.
- Results per page (`per_page`, number): How many to return. Defaults to 50, up to 200. From 1 to 200. Default: `50`.

**Outputs**: The customer's addresses

- `count` (number): Records on this page
- `estimated_total` (number): Paddle's estimate of the total matching records
- `has_more` (true/false): Whether Paddle has another page
- `items` (list)
- `next_after` (text): The 'after' value to pass to read the next page
- `per_page` (number): The page size used

**Example output**

```json
{
  "count": 1,
  "estimated_total": 1,
  "has_more": false,
  "items": [
    {
      "city": "Astoria",
      "country_code": "US",
      "created_at": "2026-02-02T16:40:14.000Z",
      "custom_data": null,
      "customer_id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
      "description": "HQ",
      "first_line": "3811 Ditmars Blvd",
      "id": "add_01h8xd1n8v0j3g2n7bqf6q3z9y",
      "postal_code": "11105",
      "region": "NY",
      "second_line": null,
      "status": "active",
      "updated_at": "2026-02-02T16:40:14.000Z"
    }
  ],
  "next_after": null,
  "per_page": 50
}
```

### List customers

List customers. Search matches a customer's ID, name or email; leave every filter empty to list everyone.

**Inputs**

- Email (`email`, text): Only the customer(s) with this exact email.
- Search (`search`, text): Match against a customer's ID, name or email.
- Status (`status`, text): Only customers with this status. Leave empty for both. One of: `active`, `archived`.
- After (`after`, text): Read the page after this ID. Leave empty for the first page; use the 'next_after' this action returned to read the next one.
- Results per page (`per_page`, number): How many to return. Defaults to 50, up to 200. From 1 to 200. Default: `50`.

**Outputs**: The customers, newest first

- `count` (number): Records on this page
- `estimated_total` (number): Paddle's estimate of the total matching records
- `has_more` (true/false): Whether Paddle has another page
- `items` (list)
- `next_after` (text): The 'after' value to pass to read the next page
- `per_page` (number): The page size used

**Example output**

```json
{
  "count": 1,
  "estimated_total": 1,
  "has_more": false,
  "items": [
    {
      "created_at": "2026-02-02T16:40:13.000Z",
      "custom_data": null,
      "email": "ada+lodolqa@example.com",
      "id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
      "locale": "en",
      "marketing_consent": false,
      "name": "Ada Lovelace",
      "status": "active",
      "updated_at": "2026-02-02T16:40:13.000Z"
    }
  ],
  "next_after": null,
  "per_page": 50
}
```

### List prices

List prices, or one product's prices when you give a product.

**Inputs**

- Product (`product_id`, text): Only prices for this product. Leave empty for every price.
- Status (`status`, text): Only prices with this status. Leave empty for both. One of: `active`, `archived`.
- After (`after`, text): Read the page after this ID. Leave empty for the first page; use the 'next_after' this action returned to read the next one.
- Results per page (`per_page`, number): How many to return. Defaults to 50, up to 200. From 1 to 200. Default: `50`.

**Outputs**: The prices, newest first

- `count` (number): Records on this page
- `estimated_total` (number): Paddle's estimate of the total matching records
- `has_more` (true/false): Whether Paddle has another page
- `items` (list)
- `next_after` (text): The 'after' value to pass to read the next page
- `per_page` (number): The page size used

**Example output**

```json
{
  "count": 1,
  "estimated_total": 1,
  "has_more": false,
  "items": [
    {
      "billing_cycle": {
        "frequency": 1,
        "interval": "month"
      },
      "created_at": "2026-02-02T16:40:12.000Z",
      "custom_data": null,
      "description": "Lodol QA monthly price",
      "id": "pri_01h8xcmy7v3ktcq4f7v5v9w3ke",
      "name": "Monthly",
      "product_id": "pro_01h8xce4qyjr8ka1krs6knmjys",
      "quantity": {
        "maximum": 100,
        "minimum": 1
      },
      "status": "active",
      "tax_mode": "account_setting",
      "trial_period": null,
      "type": "standard",
      "unit_price": {
        "amount": "1000",
        "currency_code": "USD"
      },
      "updated_at": "2026-02-02T16:40:12.000Z"
    }
  ],
  "next_after": null,
  "per_page": 50
}
```

### List products

List the products in the catalog. Each one reports its name, description, tax category, type and status. Narrow by status or tax category.

**Inputs**

- Status (`status`, text): Only products with this status. Leave empty for both. One of: `active`, `archived`.
- Tax category (`tax_category`, text): Only products in this tax category. One of: `standard` (Standard (available by default)), `saas` (SaaS (available by default)), `digital-goods` (Digital goods (needs approval)), `ebooks` (E-books (needs approval)), `implementation-services` (Implementation services (needs approval)), `professional-services` (Professional services (needs approval)), `software-programming-services` (Software programming services (needs approval)), `training-services` (Training services (needs approval)), `website-hosting` (Website hosting (needs approval)).
- After (`after`, text): Read the page after this ID. Leave empty for the first page; use the 'next_after' this action returned to read the next one.
- Results per page (`per_page`, number): How many to return. Defaults to 50, up to 200. From 1 to 200. Default: `50`.

**Outputs**: The products, newest first

- `count` (number): Records on this page
- `estimated_total` (number): Paddle's estimate of the total matching records
- `has_more` (true/false): Whether Paddle has another page
- `items` (list)
- `next_after` (text): The 'after' value to pass to read the next page
- `per_page` (number): The page size used

**Example output**

```json
{
  "count": 1,
  "estimated_total": 1,
  "has_more": false,
  "items": [
    {
      "created_at": "2026-02-02T16:40:11.123Z",
      "custom_data": null,
      "description": "A scratch product created by the Lodol QA workflow.",
      "id": "pro_01h8xce4qyjr8ka1krs6knmjys",
      "image_url": null,
      "name": "Lodol QA plan",
      "status": "active",
      "tax_category": "saas",
      "type": "standard",
      "updated_at": "2026-02-02T16:40:11.123Z"
    }
  ],
  "next_after": null,
  "per_page": 50
}
```

### List subscriptions

List subscriptions. Paddle has no action to create one directly - billing a manually-collected transaction whose price recurs (or a completed checkout) creates one automatically.

**Inputs**

- Customer (`customer_id`, text): Only records for this customer. Leave empty for everyone.
- Status (`status`, text): Only subscriptions with this status. One of: `active`, `canceled`, `past_due` (Past due), `paused`, `trialing`.
- After (`after`, text): Read the page after this ID. Leave empty for the first page; use the 'next_after' this action returned to read the next one.
- Results per page (`per_page`, number): How many to return. Defaults to 50, up to 200. From 1 to 200. Default: `50`.

**Outputs**: The subscriptions, newest first

- `count` (number): Records on this page
- `estimated_total` (number): Paddle's estimate of the total matching records
- `has_more` (true/false): Whether Paddle has another page
- `items` (list)
- `next_after` (text): The 'after' value to pass to read the next page
- `per_page` (number): The page size used

**Example output**

```json
{
  "count": 1,
  "estimated_total": 1,
  "has_more": false,
  "items": [
    {
      "address_id": "add_01h8xd1n8v0j3g2n7bqf6q3z9y",
      "billing_cycle": {
        "frequency": 1,
        "interval": "month"
      },
      "business_id": null,
      "canceled_at": null,
      "collection_mode": "manual",
      "created_at": "2026-02-02T16:40:15.000Z",
      "currency_code": "USD",
      "current_billing_period": {
        "ends_at": "2026-03-02T16:40:15.000Z",
        "starts_at": "2026-02-02T16:40:15.000Z"
      },
      "custom_data": null,
      "customer_id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
      "first_billed_at": "2026-02-02T16:40:15.000Z",
      "id": "sub_01h8xd6t2b4x5y6z7a8b9c0d1e",
      "items": [
        {
          "next_billed_at": "2026-03-02T16:40:15.000Z",
          "price": {
            "billing_cycle": {
              "frequency": 1,
              "interval": "month"
            },
            "description": "Lodol QA monthly price",
            "id": "pri_01h8xcmy7v3ktcq4f7v5v9w3ke",
            "product_id": "pro_01h8xce4qyjr8ka1krs6knmjys",
            "unit_price": {
              "amount": "1000",
              "currency_code": "USD"
            }
          },
          "quantity": 1,
          "status": "active"
        }
      ],
      "next_billed_at": "2026-03-02T16:40:15.000Z",
      "paused_at": null,
      "scheduled_change": null,
      "started_at": "2026-02-02T16:40:15.000Z",
      "status": "active",
      "updated_at": "2026-02-02T16:40:15.000Z"
    }
  ],
  "next_after": null,
  "per_page": 50
}
```

### List transactions

List transactions (invoices and charges), newest first.

**Inputs**

- Customer (`customer_id`, text): Only records for this customer. Leave empty for everyone.
- Subscription (`subscription_id`, text): Only transactions billed by this subscription.
- Status (`status`, text): Only transactions with this status. One of: `draft` (Draft - missing items, a customer or an address), `ready` (Ready - complete, but not yet billed), `billed` (Billed - invoiced or charged), `canceled`.
- After (`after`, text): Read the page after this ID. Leave empty for the first page; use the 'next_after' this action returned to read the next one.
- Results per page (`per_page`, number): How many to return, up to 30 (Paddle's own ceiling for transactions). From 1 to 30. Default: `30`.

**Outputs**: The transactions, newest first

- `count` (number): Records on this page
- `estimated_total` (number): Paddle's estimate of the total matching records
- `has_more` (true/false): Whether Paddle has another page
- `items` (list)
- `next_after` (text): The 'after' value to pass to read the next page
- `per_page` (number): The page size used

**Example output**

```json
{
  "count": 1,
  "estimated_total": 1,
  "has_more": false,
  "items": [
    {
      "address_id": "add_01h8xd1n8v0j3g2n7bqf6q3z9y",
      "billed_at": "2026-02-02T16:40:15.000Z",
      "billing_details": {
        "additional_information": null,
        "enable_checkout": false,
        "payment_terms": {
          "frequency": 14,
          "interval": "day"
        },
        "purchase_order_number": null
      },
      "business_id": null,
      "checkout": null,
      "collection_mode": "manual",
      "created_at": "2026-02-02T16:40:15.000Z",
      "currency_code": "USD",
      "custom_data": null,
      "customer_id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
      "discount_id": null,
      "id": "txn_01h8xd4rq9z3f7c8h9k1m2n3p4",
      "invoice_id": "inv_01h8xd6t2b4x5y6z7a8b9c0d1f",
      "invoice_number": "INV-0001",
      "items": [
        {
          "price": {
            "billing_cycle": {
              "frequency": 1,
              "interval": "month"
            },
            "description": "Lodol QA monthly price",
            "id": "pri_01h8xcmy7v3ktcq4f7v5v9w3ke",
            "product_id": "pro_01h8xce4qyjr8ka1krs6knmjys",
            "unit_price": {
              "amount": "1000",
              "currency_code": "USD"
            }
          },
          "quantity": 1
        }
      ],
      "origin": "api",
      "payments": [],
      "status": "billed",
      "subscription_id": "sub_01h8xd6t2b4x5y6z7a8b9c0d1e",
      "updated_at": "2026-02-02T16:40:15.000Z"
    }
  ],
  "next_after": null,
  "per_page": 50
}
```

### Pause subscription

Pause a subscription. Billing stops; resume it later with 'Resume subscription'.

**Inputs**

- Subscription (`subscription_id`, text, required): The subscription's ID, from 'List subscriptions'.
- Effective from (`effective_from`, text): When the pause takes effect. Defaults to the end of the current billing period. One of: `next_billing_period` (At the end of the current billing period), `immediately`.

**Outputs**

- `address_id` (text)
- `billing_cycle` (object)
- `business_id` (text)
- `canceled_at` (text)
- `collection_mode` (text)
- `created_at` (text)
- `currency_code` (text)
- `current_billing_period` (object)
- `custom_data` (object)
- `customer_id` (text)
- `first_billed_at` (text)
- `id` (text)
- `items` (list)
- `next_billed_at` (text)
- `paused_at` (text)
- `scheduled_change` (object)
- `started_at` (text)
- `status` (text)
- `updated_at` (text)

**Example output**

```json
{
  "address_id": "add_01h8xd1n8v0j3g2n7bqf6q3z9y",
  "billing_cycle": {
    "frequency": 1,
    "interval": "month"
  },
  "business_id": null,
  "canceled_at": null,
  "collection_mode": "manual",
  "created_at": "2026-02-02T16:40:15.000Z",
  "currency_code": "USD",
  "current_billing_period": {
    "ends_at": "2026-03-02T16:40:15.000Z",
    "starts_at": "2026-02-02T16:40:15.000Z"
  },
  "custom_data": null,
  "customer_id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
  "first_billed_at": "2026-02-02T16:40:15.000Z",
  "id": "sub_01h8xd6t2b4x5y6z7a8b9c0d1e",
  "items": [
    {
      "next_billed_at": "2026-03-02T16:40:15.000Z",
      "price": {
        "billing_cycle": {
          "frequency": 1,
          "interval": "month"
        },
        "description": "Lodol QA monthly price",
        "id": "pri_01h8xcmy7v3ktcq4f7v5v9w3ke",
        "product_id": "pro_01h8xce4qyjr8ka1krs6knmjys",
        "unit_price": {
          "amount": "1000",
          "currency_code": "USD"
        }
      },
      "quantity": 1,
      "status": "active"
    }
  ],
  "next_billed_at": "2026-03-02T16:40:15.000Z",
  "paused_at": null,
  "scheduled_change": null,
  "started_at": "2026-02-02T16:40:15.000Z",
  "status": "paused",
  "updated_at": "2026-02-02T16:40:15.000Z"
}
```

### Resume subscription

Resume a paused subscription immediately.

**Inputs**

- Subscription (`subscription_id`, text, required): The subscription's ID, from 'List subscriptions'.

**Outputs**

- `address_id` (text)
- `billing_cycle` (object)
- `business_id` (text)
- `canceled_at` (text)
- `collection_mode` (text)
- `created_at` (text)
- `currency_code` (text)
- `current_billing_period` (object)
- `custom_data` (object)
- `customer_id` (text)
- `first_billed_at` (text)
- `id` (text)
- `items` (list)
- `next_billed_at` (text)
- `paused_at` (text)
- `scheduled_change` (object)
- `started_at` (text)
- `status` (text)
- `updated_at` (text)

**Example output**

```json
{
  "address_id": "add_01h8xd1n8v0j3g2n7bqf6q3z9y",
  "billing_cycle": {
    "frequency": 1,
    "interval": "month"
  },
  "business_id": null,
  "canceled_at": null,
  "collection_mode": "manual",
  "created_at": "2026-02-02T16:40:15.000Z",
  "currency_code": "USD",
  "current_billing_period": {
    "ends_at": "2026-03-02T16:40:15.000Z",
    "starts_at": "2026-02-02T16:40:15.000Z"
  },
  "custom_data": null,
  "customer_id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
  "first_billed_at": "2026-02-02T16:40:15.000Z",
  "id": "sub_01h8xd6t2b4x5y6z7a8b9c0d1e",
  "items": [
    {
      "next_billed_at": "2026-03-02T16:40:15.000Z",
      "price": {
        "billing_cycle": {
          "frequency": 1,
          "interval": "month"
        },
        "description": "Lodol QA monthly price",
        "id": "pri_01h8xcmy7v3ktcq4f7v5v9w3ke",
        "product_id": "pro_01h8xce4qyjr8ka1krs6knmjys",
        "unit_price": {
          "amount": "1000",
          "currency_code": "USD"
        }
      },
      "quantity": 1,
      "status": "active"
    }
  ],
  "next_billed_at": "2026-03-02T16:40:15.000Z",
  "paused_at": null,
  "scheduled_change": null,
  "started_at": "2026-02-02T16:40:15.000Z",
  "status": "active",
  "updated_at": "2026-02-02T16:40:15.000Z"
}
```

### Update customer

Change a customer's name, email, locale or status. Only the fields you fill in are sent. Setting status to 'Archived' is Paddle's only way to remove a customer - their past transactions and subscriptions are kept.

**Inputs**

- Customer (`customer_id`, text, required): The customer's ID, from 'List customers' or 'Create customer'.
- Name (`name`, text): A new name.
- Email (`email`, text): A new email.
- Locale (`locale`, text): A new locale tag.
- Status (`status`, text): Archive or reactivate this customer. One of: `active`, `archived`.
- Custom data (`custom_data`, object): Arbitrary JSON to attach, such as {"internal_id": "123"}. Leave empty for none.

**Outputs**

- `created_at` (text)
- `custom_data` (object)
- `email` (text)
- `id` (text)
- `locale` (text)
- `marketing_consent` (true/false)
- `name` (text)
- `status` (text)
- `updated_at` (text)

**Example output**

```json
{
  "created_at": "2026-02-02T16:40:13.000Z",
  "custom_data": null,
  "email": "ada+lodolqa@example.com",
  "id": "ctm_01h8xcyq5y3z1e3x9y4nq6z0dw",
  "locale": "en",
  "marketing_consent": false,
  "name": "Ada Lovelace",
  "status": "active",
  "updated_at": "2026-02-02T16:40:13.000Z"
}
```

### Update product

Change a product's name, description, tax category, type, image or status. Only the fields you fill in are sent. Setting status to 'Archived' is Paddle's only way to remove a product - there is no delete operation.

**Inputs**

- Product (`product_id`, text, required): The product's ID, from 'List products' or 'Create product'.
- Name (`name`, text): A new name.
- Description (`description`, text): A new internal description.
- Tax category (`tax_category`, text): A new tax category. One of: `standard` (Standard (available by default)), `saas` (SaaS (available by default)), `digital-goods` (Digital goods (needs approval)), `ebooks` (E-books (needs approval)), `implementation-services` (Implementation services (needs approval)), `professional-services` (Professional services (needs approval)), `software-programming-services` (Software programming services (needs approval)), `training-services` (Training services (needs approval)), `website-hosting` (Website hosting (needs approval)).
- Type (`product_type`, text): A new type. One of: `standard` (Standard - shown in the Paddle catalog), `custom` (Custom - a one-off, not shown in the catalog).
- Image URL (`image_url`, text): A new HTTPS image URL.
- Status (`status`, text): Archive or reactivate this product. One of: `active`, `archived`.
- Custom data (`custom_data`, object): Arbitrary JSON to attach, such as {"internal_id": "123"}. Leave empty for none.

**Outputs**

- `created_at` (text)
- `custom_data` (object)
- `description` (text)
- `id` (text)
- `image_url` (text)
- `name` (text)
- `status` (text)
- `tax_category` (text)
- `type` (text)
- `updated_at` (text)

**Example output**

```json
{
  "created_at": "2026-02-02T16:40:11.123Z",
  "custom_data": null,
  "description": "A scratch product created by the Lodol QA workflow.",
  "id": "pro_01h8xce4qyjr8ka1krs6knmjys",
  "image_url": null,
  "name": "Lodol QA plan",
  "status": "active",
  "tax_category": "saas",
  "type": "standard",
  "updated_at": "2026-02-02T16:40:11.123Z"
}
```