@paddle/paddle-node-sdk/README.md

A Node.js SDK that you can use to integrate Paddle Billing with applications written in server-side JavaScript.

# Paddle Node.js SDK

[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/paddlehq/paddle-node-sdk/build-test.yml)](https://github.com/PaddleHQ/paddle-node-sdk/actions/workflows/build-test.yml?query=branch%3Amain)
[![NPM Version](https://img.shields.io/npm/v/%40paddle%2Fpaddle-node-sdk)](https://www.npmjs.com/package/@paddle/paddle-node-sdk?activeTab=versions)
[![NPM Downloads](https://img.shields.io/npm/dm/%40paddle%2Fpaddle-node-sdk)](https://www.npmjs.com/package/@paddle/paddle-node-sdk)
[![GitHub License](https://img.shields.io/github/license/paddlehq/paddle-node-sdk)](https://github.com/PaddleHQ/paddle-node-sdk/blob/main/LICENSE)


[Paddle Billing](https://www.paddle.com/billing?utm_source=dx&utm_medium=paddle-node-sdk) is a complete digital product sales and subscription management platform, designed for modern software businesses. It helps you increase your revenue, retain customers, and scale your operations.

This is a [Node.js](https://nodejs.org/) SDK that you can use to integrate Paddle Billing with applications written in server-side JavaScript.

For working with Paddle in your frontend, use [Paddle.js](https://developer.paddle.com/paddlejs/overview?utm_source=dx&utm_medium=paddle-node-sdk). You can open checkouts, securely collect payment information, build pricing pages, and integrate with Paddle Retain.  

> **Important:** This package works with Paddle Billing. It does not support Paddle Classic. To work with Paddle Classic, see: [Paddle Classic API reference](https://developer.paddle.com/classic/api-reference/1384a288aca7a-api-reference?utm_source=dx&utm_medium=paddle-node-sdk)

## Installation

Install using `npm`:

```sh
npm install @paddle/paddle-node-sdk
```

Install using `yarn`:

```sh
yarn add @paddle/paddle-node-sdk
```

Install using `pnpm`:

```sh
pnpm add @paddle/paddle-node-sdk
```

## Usage

To authenticate, you'll need an API key. You can create and manage API keys in **Paddle > Developer tools > Authentication**. 

Pass your API key while initializing a new Paddle client.

``` typescript
import { Environment, LogLevel, Paddle } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')
```

You can also pass an environment to work with the sandbox:

```typescript
const paddle = new Paddle('API_KEY', {
  environment: Environment.production, // or Environment.sandbox for accessing sandbox API
  logLevel: LogLevel.verbose, // or LogLevel.error for less verbose logging
  customHeaders: {
    'X-Custom-Header': 'value' // Optional custom headers
  }
})
```

Keep in mind that API keys are separate for your sandbox and live accounts, so you'll need to generate keys for each environment.

## Work with TypeScript

This SDK comes with TypeScript definitions for the Paddle API. We recommend that you update frequently to keep the TypeScript definitions up-to-date with the API. Use `// @ts-ignore` to prevent any type error if you don't want to update.

### Versioning

When we make [non-breaking changes](https://developer.paddle.com/api-reference/about/versioning?utm_source=dx&utm_medium=paddle-node-sdk#non-breaking-change) to the Paddle API, we'll only release a new major version of the Node.js SDK when it causes problems at runtime. We won't release a new version of the SDK when we weaken TypeScript types in a way that doesn't cause existing implementations to break or malfunction. For example, if we add a new field to a request or an allowed value for a field in a response, this weakens the Typescript type but does not cause existing usages to stop working.

This means when upgrading minor versions of the SDK, you may notice type errors. You can safely ignore these or fix by adding additional type guards.

## Naming conventions

Properties in the Paddle API use `snake_case`. To follow JavaScript conventions, properties in this SDK use `camelCase`. This means:

* Convert `snake_case` field names in the API docs to `camelCase` when creating or updating entities using the SDK.
* Responses match the API docs, but field names are `camelCase` rather than `snake_case`.

## Examples

### List entities

You can list supported entities with the `list` function in the resource.

When you call a list function, it returns an iterator object. This object doesn't fetch any data from the API right away.

**You must call the `next()` method** on this iterator to retrieve the first page of results (e.g., `await productCollection.next()`). Calling `next()` again will fetch the subsequent page.

<details open>
<summary style="font-size: 1.1rem;">Products (products.list())</summary>

```typescript
import { Paddle, Product, ProductCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedProducts() {
    try {
        // Returns an iterator instance
        const productCollection: ProductCollection = paddle.products.list()
    
        // Call `next()` to retrieve the first page of the dataset.
        const firstPage: Product[] = await productCollection.next()
        console.log("First page of products:", firstPage)
        
        if (productCollection.hasMore) {
            // Calling `next()` again will retrieve subsequent pages.
            const secondPage: Product[] = await productCollection.next()
            console.log("Second page of products:", secondPage)
        } else {
            console.log("No more pages of products available after the first page.")
        }
    } catch (e) {
        console.error("Error fetching paginated products:", e)
    }
}

getPaginatedProducts()
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllProducts(): Promise<Product[]> {
  const productCollection: ProductCollection = paddle.products.list()
  const allItems: Product[] = []

  try {
    for await (const product of productCollection) {
        allItems.push(product)
    }
    if (allItems.length === 0) {
        console.log('No products were found.')
    }
    return allItems
  } catch (e) {
    console.error('Error within getAllProducts:', e)
    throw e // If you want to propagate the error
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Subscriptions (subscriptions.list())</summary>

```typescript
import { Paddle, Subscription, SubscriptionCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedSubscriptions() {
    try {
        const subscriptionCollection: SubscriptionCollection = paddle.subscriptions.list()
        
        const firstPage: Subscription[] = await subscriptionCollection.next()
        console.log("First page of subscriptions:", firstPage)
        
        if (subscriptionCollection.hasMore) {
            const secondPage: Subscription[] = await subscriptionCollection.next()
            console.log("Second page of subscriptions:", secondPage)
        } else {
            console.log("No more pages of subscriptions available after the first page.")
        }
    } catch (e) {
        console.error("Error fetching paginated subscriptions:", e)
    }
}

getPaginatedSubscriptions()
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllSubscriptions(): Promise<Subscription[]> {
  const subscriptionCollection: SubscriptionCollection = paddle.subscriptions.list()
  const allItems: Subscription[] = []
  try {
    for await (const subscription of subscriptionCollection) {
        allItems.push(subscription)
    }
    if (allItems.length === 0) {
        console.log('No subscriptions were found.')
    }
    return allItems
  } catch (e) {
    console.error('Error within getAllSubscriptions:', e)
    throw e // If you want to propagate the error
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Customers (customers.list())</summary>

```typescript
import { Paddle, Customer, CustomerCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedCustomers() {
    try {
        const customerCollection: CustomerCollection = paddle.customers.list()
        
        const firstPage: Customer[] = await customerCollection.next()
        console.log("First page of customers:", firstPage)
        
        if (customerCollection.hasMore) {
            const secondPage: Customer[] = await customerCollection.next()
            console.log("Second page of customers:", secondPage)
        } else {
            console.log("No more pages of customers available after the first page.")
        }
    } catch (e) {
        console.error("Error fetching paginated customers:", e)
    }
}

getPaginatedCustomers()
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllCustomers(): Promise<Customer[]> {
  const customerCollection: CustomerCollection = paddle.customers.list()
  const allItems: Customer[] = []
  try {
    for await (const customer of customerCollection) {
        allItems.push(customer)
    }
    if (allItems.length === 0) {
        console.log('No customers were found.')
    }
    return allItems
  } catch (e) {
    console.error('Error within getAllCustomers:', e)
    throw e
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Addresses (addresses.list())</summary>

```typescript
import { Paddle, Address, AddressCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedAddresses(customerId: string) {
    try {
        // Note: addresses.list() requires a customerId
        const addressCollection: AddressCollection = paddle.addresses.list(customerId)
        
        const firstPage: Address[] = await addressCollection.next()
        console.log(`First page of addresses for customer ${customerId}:`, firstPage)
        
        if (addressCollection.hasMore) {
            const secondPage: Address[] = await addressCollection.next()
            console.log(`Second page of addresses for customer ${customerId}:`, secondPage)
        } else {
            console.log(`No more pages of addresses available for customer ${customerId} after the first page.`)
        }
    } catch (e) {
        console.error(`Error fetching paginated addresses for customer ${customerId}:`, e)
    }
}

getPaginatedAddresses('ctm_01grnn4zta5a1mf02jjze7y2ys')
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllAddresses(customerId: string): Promise<Address[]> {
  // Note: addresses.list() requires a customerId
  const addressCollection: AddressCollection = paddle.addresses.list(customerId)
  const allItems: Address[] = []
  try {
    for await (const address of addressCollection) {
        allItems.push(address)
    }
    if (allItems.length === 0) {
        console.log(`No addresses were found for customer ${customerId}.`)
    }
    return allItems
  } catch (e) {
    console.error(`Error within getAllAddresses for customer ${customerId}:`, e)
    throw e // If you want to propagate the error
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Adjustments (adjustments.list())</summary>

```typescript
import { Paddle, Adjustment, AdjustmentCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedAdjustments() {
    try {
        const adjustmentCollection: AdjustmentCollection = paddle.adjustments.list()
        
        const firstPage: Adjustment[] = await adjustmentCollection.next()
        console.log("First page of adjustments:", firstPage)
        
        if (adjustmentCollection.hasMore) {
            const secondPage: Adjustment[] = await adjustmentCollection.next()
            console.log("Second page of adjustments:", secondPage)
        } else {
            console.log("No more pages of adjustments available after the first page.")
        }
    } catch (e) {
        console.error("Error fetching paginated adjustments:", e)
    }
}
getPaginatedAdjustments()
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllAdjustments(): Promise<Adjustment[]> {
  const adjustmentCollection: AdjustmentCollection = paddle.adjustments.list()
  const allItems: Adjustment[] = []
  try {
    for await (const adjustment of adjustmentCollection) {
        allItems.push(adjustment)
    }
    if (allItems.length === 0) {
        console.log('No adjustments were found.')
    }
    return allItems
  } catch (e) {
    console.error('Error within getAllAdjustments:', e)
    throw e // If you want to propagate the error
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Businesses (businesses.list())</summary>

```typescript
import { Paddle, Business, BusinessCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedBusinesses(customerId: string) {
    try {
        // Note: businesses.list() requires a customerId
        const businessCollection: BusinessCollection = paddle.businesses.list(customerId)
        
        const firstPage: Business[] = await businessCollection.next()
        console.log(`First page of businesses for customer ${customerId}:`, firstPage)
        
        if (businessCollection.hasMore) {
            const secondPage: Business[] = await businessCollection.next()
            console.log(`Second page of businesses for customer ${customerId}:`, secondPage)
        } else {
            console.log(`No more pages of businesses available for customer ${customerId} after the first page.`)
        }
    } catch (e) {
        console.error(`Error fetching paginated businesses for customer ${customerId}:`, e)
    }
}
getPaginatedBusinesses('ctm_01grnn4zta5a1mf02jjze7y2ys')
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllBusinesses(customerId: string): Promise<Business[]> {
  // Note: businesses.list() requires a customerId
  const businessCollection: BusinessCollection = paddle.businesses.list(customerId)
  const allItems: Business[] = []
  try {
    for await (const business of businessCollection) {
        allItems.push(business)
    }
    if (allItems.length === 0) {
        console.log(`No businesses were found for customer ${customerId}.`)
    }
    return allItems
  } catch (e) {
    console.error(`Error within getAllBusinesses for customer ${customerId}:`, e)
    throw e 
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Discounts (discounts.list())</summary>

```typescript
import { Paddle, Discount, DiscountCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedDiscounts() {
    try {
        const discountCollection: DiscountCollection = paddle.discounts.list()
        
        const firstPage: Discount[] = await discountCollection.next()
        console.log("First page of discounts:", firstPage)
        
        if (discountCollection.hasMore) {
            const secondPage: Discount[] = await discountCollection.next()
            console.log("Second page of discounts:", secondPage)
        } else {
            console.log("No more pages of discounts available after the first page.")
        }
    } catch (e) {
        console.error("Error fetching paginated discounts:", e)
    }
}
getPaginatedDiscounts()
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllDiscounts(): Promise<Discount[]> {
  const discountCollection: DiscountCollection = paddle.discounts.list()
  const allItems: Discount[] = []
  try {
    for await (const discount of discountCollection) {
        allItems.push(discount)
    }
    if (allItems.length === 0) {
        console.log('No discounts were found.')
    }
    return allItems
  } catch (e) {
    console.error('Error within getAllDiscounts:', e)
    throw e
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Prices (prices.list())</summary>

```typescript
import { Paddle, Price, PriceCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedPrices() {
    try {
        const priceCollection: PriceCollection = paddle.prices.list()
        
        const firstPage: Price[] = await priceCollection.next()
        console.log("First page of prices:", firstPage)
        
        if (priceCollection.hasMore) {
            const secondPage: Price[] = await priceCollection.next()
            console.log("Second page of prices:", secondPage)
        } else {
            console.log("No more pages of prices available after the first page.")
        }
    } catch (e) {
        console.error("Error fetching paginated prices:", e)
    }
}
getPaginatedPrices()
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllPrices(): Promise<Price[]> {
  const priceCollection: PriceCollection = paddle.prices.list()
  const allItems: Price[] = []
  try {
    for await (const price of priceCollection) {
        allItems.push(price)
    }
    if (allItems.length === 0) {
        console.log('No prices were found.')
    }
    return allItems
  } catch (e) {
    console.error('Error within getAllPrices:', e)
    throw e
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Transactions (transactions.list())</summary>

```typescript
import { Paddle, Transaction, TransactionCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedTransactions() {
    try {
        const transactionCollection: TransactionCollection = paddle.transactions.list()
        
        const firstPage: Transaction[] = await transactionCollection.next()
        console.log("First page of transactions:", firstPage)
        
        if (transactionCollection.hasMore) {
            const secondPage: Transaction[] = await transactionCollection.next()
            console.log("Second page of transactions:", secondPage)
        } else {
            console.log("No more pages of transactions available after the first page.")
        }
    } catch (e) {
        console.error("Error fetching paginated transactions:", e)
    }
}
getPaginatedTransactions()
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllTransactions(): Promise<Transaction[]> {
  const transactionCollection: TransactionCollection = paddle.transactions.list()
  const allItems: Transaction[] = []
  try {
    for await (const transaction of transactionCollection) {
        allItems.push(transaction)
    }
    if (allItems.length === 0) {
        console.log('No transactions were found.')
    }
    return allItems
  } catch (e) {
    console.error('Error within getAllTransactions:', e)
    throw e // If you want to propagate the error
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Payment Methods (paymentMethods.list())</summary>

```typescript
import { Paddle, PaymentMethod, PaymentMethodCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedPaymentMethods(customerId: string) {
    try {
        // Note: paymentMethods.list() requires a customerId
        const paymentMethodCollection: PaymentMethodCollection = paddle.paymentMethods.list(customerId)
        
        const firstPage: PaymentMethod[] = await paymentMethodCollection.next()
        console.log(`First page of payment methods for customer ${customerId}:`, firstPage)
        
        if (paymentMethodCollection.hasMore) {
            const secondPage: PaymentMethod[] = await paymentMethodCollection.next()
            console.log(`Second page of payment methods for customer ${customerId}:`, secondPage)
        } else {
            console.log(`No more pages of payment methods available for customer ${customerId} after the first page.`)
        }
    } catch (e) {
        console.error(`Error fetching paginated payment methods for customer ${customerId}:`, e)
    }
}
getPaginatedPaymentMethods('ctm_01grnn4zta5a1mf02jjze7y2ys')
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllPaymentMethods(customerId: string): Promise<PaymentMethod[]> {
  // Note: paymentMethods.list() requires a customerId
  const paymentMethodCollection: PaymentMethodCollection = paddle.paymentMethods.list(customerId)
  const allItems: PaymentMethod[] = []
  try {
    for await (const paymentMethod of paymentMethodCollection) {
        allItems.push(paymentMethod)
    }
    if (allItems.length === 0) {
        console.log(`No payment methods were found for customer ${customerId}.`)
    }
    return allItems
  } catch (e) {
    console.error(`Error within getAllPaymentMethods for customer ${customerId}:`, e)
    throw e // If you want to propagate the error
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Notifications (notifications.list())</summary>

```typescript
import { Paddle, Notification, NotificationCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedNotifications() {
    try {
        const notificationCollection: NotificationCollection = paddle.notifications.list()
        
        const firstPage: Notification[] = await notificationCollection.next()
        console.log("First page of notifications:", firstPage)
        
        if (notificationCollection.hasMore) {
            const secondPage: Notification[] = await notificationCollection.next()
            console.log("Second page of notifications:", secondPage)
        } else {
            console.log("No more pages of notifications available after the first page.")
        }
    } catch (e) {
        console.error("Error fetching paginated notifications:", e)
    }
}
getPaginatedNotifications()
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllNotifications(): Promise<Notification[]> {
  const notificationCollection: NotificationCollection = paddle.notifications.list()
  const allItems: Notification[] = []
  try {
    for await (const notification of notificationCollection) {
        allItems.push(notification)
    }
    if (allItems.length === 0) {
        console.log('No notifications were found.')
    }
    return allItems
  } catch (e) {
    console.error('Error within getAllNotifications:', e)
    throw e // If you want to propagate the error
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Reports (reports.list())</summary>

```typescript
import { Paddle, Report, ReportCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedReports() {
    try {
        const reportCollection: ReportCollection = paddle.reports.list()
        
        const firstPage: Report[] = await reportCollection.next()
        console.log("First page of reports:", firstPage)
        
        if (reportCollection.hasMore) {
            const secondPage: Report[] = await reportCollection.next()
            console.log("Second page of reports:", secondPage)
        } else {
            console.log("No more pages of reports available after the first page.")
        }
    } catch (e) {
        console.error("Error fetching paginated reports:", e)
    }
}
getPaginatedReports()
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllReports(): Promise<Report[]> {
  const reportCollection: ReportCollection = paddle.reports.list()
  const allItems: Report[] = []
  try {
    for await (const report of reportCollection) {
        allItems.push(report)
    }
    if (allItems.length === 0) {
        console.log('No reports were found.')
    }
    return allItems
  } catch (e) {
    console.error('Error within getAllReports:', e)
    throw e // If you want to propagate the error
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Simulations (simulations.list())</summary>

```typescript
import { Paddle, Simulation, SimulationCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedSimulations() {
    try {
        const simulationCollection: SimulationCollection = paddle.simulations.list()
        
        const firstPage: Simulation[] = await simulationCollection.next()
        console.log("First page of simulations:", firstPage)
        
        if (simulationCollection.hasMore) {
            const secondPage: Simulation[] = await simulationCollection.next()
            console.log("Second page of simulations:", secondPage)
        } else {
            console.log("No more pages of simulations available after the first page.")
        }
    } catch (e) {
        console.error("Error fetching paginated simulations:", e)
    }
}
getPaginatedSimulations()
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllSimulations(): Promise<Simulation[]> {
  const simulationCollection: SimulationCollection = paddle.simulations.list()
  const allItems: Simulation[] = []
  try {
    for await (const simulation of simulationCollection) {
        allItems.push(simulation)
    }
    if (allItems.length === 0) {
        console.log('No simulations were found.')
    }
    return allItems
  } catch (e) {
    console.error('Error within getAllSimulations:', e)
    throw e // If you want to propagate the error
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Simulation Runs (simulationRuns.list())</summary>

```typescript
import { Paddle, SimulationRun, SimulationRunCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedSimulationRuns(simulationId: string) {
    console.log(`Attempting to fetch paginated simulation runs for simulation ${simulationId}...`)
    try {
        // Note: simulationRuns.list() requires a simulationId
        const simulationRunCollection: SimulationRunCollection = paddle.simulationRuns.list(simulationId)
        
        const firstPage: SimulationRun[] = await simulationRunCollection.next()
        console.log(`First page of simulation runs for simulation ${simulationId}:`, firstPage)
        
        if (simulationRunCollection.hasMore) {
            const secondPage: SimulationRun[] = await simulationRunCollection.next()
            console.log(`Second page of simulation runs for simulation ${simulationId}:`, secondPage)
        } else {
            console.log(`No more pages of simulation runs available for simulation ${simulationId} after the first page.`)
        }
    } catch (e) {
        console.error(`Error fetching paginated simulation runs for simulation ${simulationId}:`, e)
    }
}
getPaginatedSimulationRuns('ntfsim_01ghbkd0frb9k95cnhwd1bxpvk')
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllSimulationRuns(simulationId: string): Promise<SimulationRun[]> {
  const simulationRunCollection: SimulationRunCollection = paddle.simulationRuns.list(simulationId)
  const allItems: SimulationRun[] = []
  try {
    for await (const simulationRun of simulationRunCollection) {
        allItems.push(simulationRun)
    }
    if (allItems.length === 0) {
        console.log(`No simulation runs were found for simulation ${simulationId}.`)
    }
    return allItems
  } catch (e) {
    console.error(`Error within getAllSimulationRuns for simulation ${simulationId}:`, e)
    throw e // If you want to propagate the error
  }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Simulation Run Events (simulationRunEvents.list())</summary>

```typescript
import { Paddle, SimulationRunEvent, SimulationRunEventCollection } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function getPaginatedSimulationRunEvents(simulationId: string, simulationRunId: string) {
    try {
        // Note: simulationRunEvents.list() requires simulationId and simulationRunId
        const collection: SimulationRunEventCollection = paddle.simulationRunEvents.list(simulationId, simulationRunId)
        
        const firstPage: SimulationRunEvent[] = await collection.next()
        console.log(`First page of events for sim ${simulationId}, run ${simulationRunId}:`, firstPage)
        
        if (collection.hasMore) {
            const secondPage: SimulationRunEvent[] = await collection.next()
            console.log(`Second page of events for sim ${simulationId}, run ${simulationRunId}:`, secondPage)
        } else {
            console.log(`No more pages of events for sim ${simulationId}, run ${simulationRunId} after the first page.`)
        }
    } catch (e) {
        console.error(`Error fetching paginated events for sim ${simulationId}, run ${simulationRunId}:`, e)
    }
}
getPaginatedSimulationRunEvents('ntfsim_01ghbkd0frb9k95cnhwd1bxpvk', 'ntfsimrun_01ghbkd0frb9k95cnhwd1bxpvk')
```

You can optionally use these iterators with a `for await...of` loop to iterate over all items across all available pages.

```typescript
async function getAllSimulationRunEvents(simulationId: string, simulationRunId: string): Promise<SimulationRunEvent[]> {
  const collection: SimulationRunEventCollection = paddle.simulationRunEvents.list(simulationId, simulationRunId)
  const allItems: SimulationRunEvent[] = []
  try {
    for await (const event of collection) {
        allItems.push(event)
    }
    if (allItems.length === 0) {
        console.log(`No events found for sim ${simulationId}, run ${simulationRunId}.`)
    }
    return allItems
  } catch (e) {
    console.error(`Error within getAllSimulationRunEvents for sim ${simulationId}, run ${simulationRunId}:`, e)
    throw e // If you want to propagate the error
  }
}
```

</details>

### Create an entity

You can create a supported entity with the `create` function in the resource. It accepts the body to be created. The created entity is returned.


<details open>
<summary style="font-size: 1.1rem;">Products (products.create())</summary>

``` typescript
import { Paddle, CreateProductRequestBody } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function createProduct(requestBody: CreateProductRequestBody) {
    try {
        const product = await paddle.products.create(requestBody)
        // Returns a product entity
        return product
    } catch (e) {
        // Handle Network/API errors
    }
}

const product = await createProduct({ name: 'ChatApp Education', taxCategory: 'standard' })
console.log("Product", product)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Transactions (transactions.create())</summary>

``` typescript
import { Paddle, CreateTransactionRequestBody, Transaction } from '@paddle/paddle-node-sdk' // Assuming types

const paddle = new Paddle('API_KEY')

async function createTransaction(requestBody: CreateTransactionRequestBody): Promise<Transaction | undefined> { // Assuming types
    try {
        const transaction = await paddle.transactions.create(requestBody)
        // Returns a transaction entity
        return transaction
    } catch (e) {
        // Handle Network/API errors
    }
}

const newTransaction = await createTransaction({ 
    items: [{ priceId: 'pri_01gsz8z1q1n00f12qt82y31smh', quantity: 1 }],
    customerId: 'ctm_01grnn4zta5a1mf02jjze7y2ys'
})
console.log("Transaction", newTransaction)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Addresses (addresses.create())</summary>

```typescript
import { Paddle, CreateAddressRequestBody, Address } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function createAddress(customerId: string, requestBody: CreateAddressRequestBody): Promise<Address | undefined> {
    try {
        const address = await paddle.addresses.create(customerId, requestBody)
        return address
        // Returns an address entity
    } catch (e) {
        console.error('Error creating address:', e)
        // Handle Network/API errors
    }
}

const newAddress = await createAddress('ctm_01grnn4zta5a1mf02jjze7y2ys', { countryCode: 'US', description: 'Primary Address' })
console.log("New Address:", newAddress)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Adjustments (adjustments.create())</summary>

```typescript
import { Paddle, CreateAdjustmentRequestBody, Adjustment } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function createAdjustment(requestBody: CreateAdjustmentRequestBody): Promise<Adjustment | undefined> {
    try {
        const adjustment = await paddle.adjustments.create(requestBody)
        return adjustment
        // Returns an adjustment entity
    } catch (e) {
        console.error('Error creating adjustment:', e)
        // Handle Network/API errors
    }
}

const newAdjustment = await createAdjustment({ transactionId: 'txn_01h04vsbhqc62t8hmd4z3b578c', items: [{ itemId: 'txnitm_01hvcc94b7qgz60qmrqmbm19zw', amount: '1000', type: 'partial' }], action: 'credit', reason: 'Refund for customer support' })
console.log("New Adjustment:", newAdjustment)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Businesses (businesses.create())</summary>

```typescript
import { Paddle, CreateBusinessRequestBody, Business } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function createBusiness(customerId: string, requestBody: CreateBusinessRequestBody): Promise<Business | undefined> {
    try {
        const business = await paddle.businesses.create(customerId, requestBody)
        return business
        // Returns a business entity
    } catch (e) {
        console.error('Error creating business:', e)
        // Handle Network/API errors
    }
}

const newBusiness = await createBusiness('ctm_01grnn4zta5a1mf02jjze7y2ys', { name: 'Sample Inc.', companyNumber: '12345AB' })
console.log("New Business:", newBusiness)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Customers (customers.create())</summary>

```typescript
import { Paddle, CreateCustomerRequestBody, Customer } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function createCustomer(requestBody: CreateCustomerRequestBody): Promise<Customer | undefined> {
    try {
        const customer = await paddle.customers.create(requestBody)
        return customer
        // Returns a customer entity
    } catch (e) {
        console.error('Error creating customer:', e)
        // Handle Network/API errors
    }
}

const newCustomer = await createCustomer({ email: 'customer@example.com', name: 'John Doe' })
console.log("New Customer:", newCustomer)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Customer Portal Sessions (customerPortalSessions.create())</summary>

```typescript
import { Paddle, CustomerPortalSession } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function createCustomerPortalSession(customerId: string, subscriptionIds: string[]): Promise<CustomerPortalSession | undefined> {
    try {
        const session = await paddle.customerPortalSessions.create(customerId, subscriptionIds)
        return session
        // Returns a customer portal session entity
    } catch (e) {
        console.error('Error creating customer portal session:', e)
        // Handle Network/API errors
    }
}

const newSession = await createCustomerPortalSession('ctm_01grnn4zta5a1mf02jjze7y2ys', ['sub_01h04vsc0qhwtsbsxh3422wjs4'])
console.log("New Customer Portal Session:", newSession)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Discounts (discounts.create())</summary>

```typescript
import { Paddle, CreateDiscountRequestBody, Discount } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function createDiscount(requestBody: CreateDiscountRequestBody): Promise<Discount | undefined> {
    try {
        const discount = await paddle.discounts.create(requestBody)
        return discount
        // Returns a discount entity
    } catch (e) {
        console.error('Error creating discount:', e)
        // Handle Network/API errors
    }
}

const newDiscount = await createDiscount({ amount: '1000', type: 'flat', description: '10 USD Off Coupon', currencyCode: 'USD', enabledForCheckout: true, code: 'SAVE10NOW' })
console.log("New Discount:", newDiscount)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Prices (prices.create())</summary>

```typescript
import { Paddle, CreatePriceRequestBody, Price } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function createPrice(requestBody: CreatePriceRequestBody): Promise<Price | undefined> {
    try {
        const price = await paddle.prices.create(requestBody)
        return price
        // Returns a price entity
    } catch (e) {
        console.error('Error creating price:', e)
        // Handle Network/API errors
    }
}

const newPrice = await createPrice({ description: 'Premium Plan Monthly', productId: 'pro_01gsz97mq9pa4fkyy0wqenepkz', unitPrice: { amount: '2000', currencyCode: 'USD' }, billingCycle: { interval: 'month', frequency: 1 }, taxMode: 'account_setting' })
console.log("New Price:", newPrice)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Notification Settings (notificationSettings.create())</summary>

```typescript
import { Paddle, CreateNotificationSettingsRequestBody, NotificationSettings } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function createNotificationSetting(requestBody: CreateNotificationSettingsRequestBody): Promise<NotificationSettings | undefined> {
    try {
        const notificationSetting = await paddle.notificationSettings.create(requestBody)
        return notificationSetting
        // Returns a notification setting entity
    } catch (e) {
        console.error('Error creating notification setting:', e)
        // Handle Network/API errors
    }
}

const newNotificationSetting = await createNotificationSetting({ description: 'Subscription Updates Webhook', type: 'url', destination: 'https://example.com/webhook/subscription-updates', subscribedEvents: ['subscription.updated', 'subscription.activated'], includeSensitiveFields: false })
console.log("New Notification Setting:", newNotificationSetting)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Reports (reports.create())</summary>

```typescript
import { Paddle, CreateReportRequestBody, Report } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function createReport(requestBody: CreateReportRequestBody): Promise<Report | undefined> {
    try {
        const report = await paddle.reports.create(requestBody)
        return report
        // Returns a report entity
    } catch (e) {
        console.error('Error creating report:', e)
        // Handle Network/API errors
    }
}

const newReport = await createReport({ type: 'transaction_line_items' }) // See ReportType for other options
console.log("New Report:", newReport)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Simulations (simulations.create())</summary>

```typescript
import { Paddle, CreateSimulationRequestBody, Simulation } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

// Example 1: Creating a simulation for a single event (e.g., 'discount.created')
async function createDiscountEventSimulation() {
    try {
        // Base fields required for any simulation
        const name = 'Simulate Discount Creation Event'
        const notificationSettingId = 'ntfset_01gt21c5pdx9q1e4mh1xrsjjn6'

        const requestBody: CreateSimulationRequestBody = {
            name,
            notificationSettingId,
            type: 'discount.created', // See IEventName for all possible event types
            payload: {
                // These fields come from the DiscountNotification entity to provide partial data relevant to the 'discount.created' event
                description: 'End of Summer Sale - 10% Off',
                code: 'SUMMER10',
                type: 'percentage',
                amount: '10',
                enabledForCheckout: true,
                recur: false,
            },
        }

        const simulation = await paddle.simulations.create(requestBody)
        return simulation
        // Returns a simulation entity
    } catch (e) {
        console.error('Error creating discount.created simulation:', e)
        // Handle Network/API errors
    }
}

createDiscountEventSimulation()

// Example 2: Creating a simulation for a scenario (e.g., 'subscription_pause')
async function createSubscriptionPauseScenarioSimulation() {
    try {
        // Base fields required for any simulation
        const name = 'Simulate Subscription Pause Scenario'
        const notificationSettingId = 'ntfset_01gt21c5pdx9q1e4mh1xrsjjn6'

        const requestBody: CreateSimulationRequestBody = {
            name,
            notificationSettingId,
            type: 'subscription_pause', // See SimulationScenarioType for all possible scenario types
            config: {
                subscriptionPause: {
                    entities: {
                        subscriptionId: 'sub_01h04vsc0qhwtsbsxh3422wjs4'
                    },
                    options: {
                        effectiveFrom: 'next_billing_period', // See EffectiveFromType for all possible options
                        hasPastDueTransaction: false,
                    },
                },
            }
        }

        const simulation = await paddle.simulations.create(requestBody)
        return simulation
        // Returns a simulation entity
    } catch (e) {
        console.error('Error creating subscription_pause simulation:', e)
        // Handle Network/API errors
    }
}

createSubscriptionPauseScenarioSimulation()
```

</details>

<details>
<summary style="font-size: 1.1rem;">Simulation Runs (simulationRuns.create())</summary>

```typescript
import { Paddle, SimulationRun } from '@paddle/paddle-node-sdk' // No specific CreateRequestBody for this simple case

const paddle = new Paddle('API_KEY')

async function createSimulationRun(simulationId: string): Promise<SimulationRun | undefined> {
    try {
        const simulationRun = await paddle.simulationRuns.create(simulationId)
        return simulationRun
        // Returns a simulation run entity
    } catch (e) {
        console.error('Error creating simulation run:', e)
        // Handle Network/API errors
    }
}

const newSimulationRun = await createSimulationRun('ntfsim_01ghbkd0frb9k95cnhwd1bxpvk')
console.log("New Simulation Run:", newSimulationRun)
```

</details>

### Update an entity
You can update a supported entity with the `update` function in the resource. It accepts the `id` of the entity to update and an object with the attributes to be updated. The updated entity is returned.

Where operations require more than one `id`, like for addresses and businesses, the `update` function accepts multiple arguments. For example, to update an address for a customer, pass the `customerId` and the `addressId`.

<details open>
<summary style="font-size: 1.1rem;">Products (products.update())</summary>

``` typescript
import { Paddle, UpdateProductRequestBody } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function updateProduct(productId: string, requestBody: UpdateProductRequestBody) {
    try {
        // Pass the product id and request body with the attributes to update
        const product = await paddle.products.update(productId, requestBody)
        // Returns an updated product entity
        return product
    } catch (e) {
        // Handle Network/API errors
    }
}

const product = await updateProduct('pro_01gsz97mq9pa4fkyy0wqenepkz', { name: 'ChatApp for Schools' })
console.log('Updated product', product)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Subscriptions (subscriptions.update())</summary>

``` typescript
import { Paddle, UpdateSubscriptionRequestBody, Subscription } from '@paddle/paddle-node-sdk' // Assuming types

const paddle = new Paddle('API_KEY')

async function updateSubscription(subscriptionId: string, requestBody: UpdateSubscriptionRequestBody): Promise<Subscription | undefined> { // Assuming types
    try {
        // Pass the subscription id and request body with the attributes to update
        const subscription = await paddle.subscriptions.update(subscriptionId, requestBody)
        // Returns an updated subscription entity
        return subscription
    } catch (e) {
        // Handle Network/API errors
    }
}

const updatedSubscription = await updateSubscription('sub_01h04vsc0qhwtsbsxh3422wjs4', { collectionMode: 'manual' })
console.log('Updated subscription', updatedSubscription)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Transactions (transactions.update())</summary>

(Note: Transaction updates might be limited to specific fields like customData or specific actions not covered by a generic update).

``` typescript
import { Paddle, UpdateTransactionRequestBody, Transaction } from '@paddle/paddle-node-sdk' // Assuming types

const paddle = new Paddle('API_KEY')

async function updateTransaction(transactionId: string, requestBody: UpdateTransactionRequestBody): Promise<Transaction | undefined> { // Assuming types
    try {
        // Pass the transaction id and request body with the attributes to update
        const transaction = await paddle.transactions.update(transactionId, requestBody)
        // Returns an updated transaction entity
        return transaction
    } catch (e) {
        // Handle Network/API errors
    }
}

const updatedTransaction = await updateTransaction('txn_01h04vsbhqc62t8hmd4z3b578c', { customData: { internal_reference: 'ref_abc123' } })
console.log('Updated transaction', updatedTransaction)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Addresses (addresses.update())</summary>

```typescript
import { Paddle, UpdateAddressRequestBody, Address } from '@paddle/paddle-node-sdk' // Assuming types

const paddle = new Paddle('API_KEY')

async function updateAddress(customerId: string, addressId: string, requestBody: UpdateAddressRequestBody): Promise<Address | undefined> { // Assuming types
    try {
        // Pass the customer id, address id and request body with the attributes to update
        const address = await paddle.addresses.update(customerId, addressId, requestBody)
        // Returns an updated address entity
        return address
    } catch (e) {
        // Handle Network/API errors
    }
}
```

</details>

<details>
<summary style="font-size: 1.1rem;">Businesses (businesses.update())</summary>

```typescript
import { Paddle, UpdateBusinessRequestBody, Business } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function updateBusiness(customerId: string, businessId: string, requestBody: UpdateBusinessRequestBody): Promise<Business | undefined> {
    try {
        // Pass the customer id, business id and request body with the attributes to update
        const business = await paddle.businesses.update(customerId, businessId, requestBody)
        // Returns an updated business entity
        return business
    } catch (e) {
        console.error(`Error updating business ${businessId} for customer ${customerId}:`, e)
        // Handle Network/API errors
    }
}

const updatedBusiness = await updateBusiness('ctm_01grnn4zta5a1mf02jjze7y2ys', 'biz_01grrebrzaee2qj2fqqhmcyzaj', { name: 'Sample Corp Updated', contacts: [{name: 'Jane Doe', email: 'jane.doe@example.com'}] })
console.log('Updated Business:', updatedBusiness)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Customers (customers.update())</summary>

```typescript
import { Paddle, UpdateCustomerRequestBody, Customer } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function updateCustomer(customerId: string, requestBody: UpdateCustomerRequestBody): Promise<Customer | undefined> {
    try {
        // Pass the customer id and request body with the attributes to update
        const customer = await paddle.customers.update(customerId, requestBody)
        // Returns an updated customer entity
        return customer
    } catch (e) {
        console.error(`Error updating customer ${customerId}:`, e)
        // Handle Network/API errors
    }
}

const updatedCustomer = await updateCustomer('ctm_01grnn4zta5a1mf02jjze7y2ys', { email: 'john.doe.updated@example.com', name: 'Johnathan Doe' })
console.log('Updated Customer:', updatedCustomer)
```

</details>

<details>
<summary style="font-size: 1.1rem;">Discounts (discounts.update())</summary>

```typescript
import { Paddle, UpdateDiscountRequestBody, Discount } from '@paddle/paddle-node-sdk'

const paddle = new Paddle('API_KEY')

async function updateDiscount(discountId: string, requestBody: UpdateDiscountRequestBody): Promise<Discount | undefined> {
    try {
        // Pass the discount id and r