### Run Test Environment Setup Script

Source: https://github.com/gettilled/tilled-node/blob/main/CONTRIBUTING.md

Execute this script to create the necessary .env files within the submodule for local testing.

```bash
node test/local-setup-env.js
```

--------------------------------

### Install Tilled Node NPM Package

Source: https://github.com/gettilled/tilled-node/blob/main/README.md

Run this command in your project's root directory to install the tilled-node package.

```bash
npm install tilled-node --save
```

--------------------------------

### Generate SDK using npm script

Source: https://github.com/gettilled/tilled-node/blob/main/CONTRIBUTING.md

Run this command from the root directory to generate the SDK. This is recommended for Mac users who have installed the generator using Homebrew.

```bash
npm run generate
```

--------------------------------

### Initialize SDK Configuration

Source: https://context7.com/gettilled/tilled-node/llms.txt

Configure the Tilled SDK with an API key or JWT, and optionally set the base path and Axios options. This setup automatically includes client name and version headers.

```typescript
import { Configuration } from 'tilled-node';

// Sandbox environment
const config = new Configuration({
  apiKey: process.env.TILLED_SECRET_KEY,       // sent as 'tilled-api-key' header
  basePath: 'https://sandbox-api.tilled.com',  // omit for production (https://api.tilled.com)
  baseOptions: { timeout: 5000 }               // any Axios config options
});

// JWT-based authentication (alternative to API key)
const jwtConfig = new Configuration({
  accessToken: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  basePath: 'https://sandbox-api.tilled.com'
});
```

--------------------------------

### Generate SDK with OpenAPI Generator CLI (Mac)

Source: https://github.com/gettilled/tilled-node/blob/main/CONTRIBUTING.md

Use this command for Mac users who have installed the OpenAPI Generator CLI. It specifies input, generator, configuration, and post-processing steps.

```bash
openapi-generator generate
    -i https://api.tilled.com/docs/spec3.json
    -g typescript-node
    -c ./codegen.conf.json
    --git-repo-id tilled-sdks
    --git-user-id gettilled
    --skip-validate-spec --enable-post-process-file
    && npx prettier --write '**/*.ts'
    && npm install
    && npm version patch --force
```

--------------------------------

### Generate SDK with OpenAPI Generator CLI (PC/Linux)

Source: https://github.com/gettilled/tilled-node/blob/main/CONTRIBUTING.md

Use this command for PC/Linux users who have installed the OpenAPI Generator CLI via NPM or Docker. It includes input, generator, configuration, and post-processing.

```bash
openapi-generator-cli generate
    -i https://api.tilled.com/docs/spec3.json
    -g typescript-node
    -c ./codegen.conf.json
    --git-repo-id tilled-sdks
    --git-user-id gettilled
    --skip-validate-spec --enable-post-process-file
    && npx prettier --write '**/*.ts'
    && npm install
    && npm version patch --force
```

--------------------------------

### Run Playwright Tests

Source: https://github.com/gettilled/tilled-node/blob/main/CONTRIBUTING.md

Execute the automated tests using Playwright. Ensure all previous setup steps, including environment configuration, are completed.

```bash
npx playwright test
```

--------------------------------

### Login User and Get JWT

Source: https://context7.com/gettilled/tilled-node/llms.txt

Authenticates a user and returns an access token (JWT) plus a refresh token for subsequent API calls.

```APIDOC
## UsersApi.loginUser

### Description
Authenticates a user and returns an access token (JWT) plus a refresh token for subsequent API calls as an alternative to API key authentication.

### Method
```typescript
loginUser
```

### Parameters
#### Request Body
- **LoginParams** (object) - Required - Parameters for user login.
  - **email** (string) - Required - The user's email address.
  - **password** (string) - Required - The user's password.

### Request Example
```json
{
  "LoginParams": {
    "email": "admin@example.com",
    "password": "securepassword123"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains authentication tokens.
  - **access_token** (string) - The JWT access token.
  - **refresh_token** (string) - The refresh token.
```

--------------------------------

### Get and List Balance Transactions

Source: https://context7.com/gettilled/tilled-node/llms.txt

Retrieves a single balance transaction or lists all balance movements with filtering.

```APIDOC
## BalanceTransactionsApi

### Description
Retrieves a single balance transaction using its ID, or lists all balance movements (charges, refunds, fees, payouts) with date and type filtering.

### Method
GET (inferred from SDK method names 'getBalanceTransaction' and 'listBalanceTransactions')

### Endpoint
(Inferred from SDK method context, typically related to balance transactions)

### Parameters
#### Path Parameters
- **id** (string) - Required (for `getBalanceTransaction`) - The unique identifier of the balance transaction.

#### Query Parameters
- **tilled_account** (string) - Required - The Tilled account ID to query.
- **created_at_gte** (string) - Optional - Filter transactions created on or after this date/time (ISO 8601 format).
- **limit** (integer) - Optional - The maximum number of transactions to return.

#### Request Body
None explicitly defined for these methods.

### Request Example (Get Single Transaction)
```json
{
  "tilled_account": "acct_XXXXXXXXXXXXXXXXXXXXXXXXX",
  "id": "txn_XXXXXXXXXXXXXXXXXXXXXXXXX"
}
```

### Request Example (List Transactions)
```json
{
  "tilled_account": "acct_XXXXXXXXXXXXXXXXXXXXXXXXX",
  "created_at_gte": "2024-01-01T00:00:00Z",
  "limit": 50
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the balance transaction(s).
  - **id** (string) - The unique identifier of the transaction.
  - **type** (string) - The type of balance movement (e.g., 'charge', 'refund', 'fee', 'payout').
  - **net** (integer) - The net amount of the transaction.
  - **amount** (integer) - The gross amount of the transaction.
  - **items** (array) - (For list response) An array of balance transaction objects.

#### Response Example (Single Transaction)
```json
{
  "data": {
    "id": "txn_XXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "charge",
    "net": 1000,
    "amount": 1000
    // ... other transaction details
  }
}
```

#### Response Example (List Transactions)
```json
{
  "data": {
    "items": [
      {
        "id": "txn_XXXXXXXXXXXXXXXXXXXXXXXXX",
        "type": "charge",
        "net": 1000,
        "amount": 1000
        // ... other transaction details
      },
      {
        "id": "txn_YYYYYYYYYYYYYYYYYYYYY",
        "type": "fee",
        "net": -30,
        "amount": -30
        // ... other transaction details
      }
    ],
    "has_more": false,
    "total_count": 2
  }
}
```
```

--------------------------------

### Get and List Balance Transactions with Tilled Node

Source: https://context7.com/gettilled/tilled-node/llms.txt

Retrieve a single balance transaction using `getBalanceTransaction` or list all balance movements with `listBalanceTransactions`. Filtering by date and type is supported for listing.

```typescript
import { Configuration, BalanceTransactionsApi } from 'tilled-node';

const balanceTxApi = new BalanceTransactionsApi(config);

async function getAccountBalance(tilledAccount: string) {
  try {
    // Get a single transaction
    const singleTx = await balanceTxApi.getBalanceTransaction({
      tilled_account: tilledAccount,
      id: 'txn_XXXXXXXXXXXXXXXXXXXXXXXXX'
    });
    console.log('Transaction type:', singleTx.data.type, 'net:', singleTx.data.net);

    // List recent transactions
    const list = await balanceTxApi.listBalanceTransactions({
      tilled_account: tilledAccount,
      created_at_gte: '2024-01-01T00:00:00Z',
      limit: 50
    });

    list.data.items.forEach(tx => {
      console.log(`${tx.id}: type=${tx.type}, amount=${tx.amount}, net=${tx.net}`);
    });

    return list.data;
  } catch (error) {
    console.error('Balance transaction fetch failed:', error);
    throw error;
  }
}
```

--------------------------------

### Serve Test Project

Source: https://github.com/gettilled/tilled-node/blob/main/CONTRIBUTING.md

Run this command to serve the test project locally, making it available for testing.

```bash
npm run start-test-project
```

--------------------------------

### Manually Publish SDK to NPM

Source: https://github.com/gettilled/tilled-node/blob/main/CONTRIBUTING.md

Run this command from the root directory to publish the SDK to NPM after making changes and updating the version.

```bash
npm publish
```

--------------------------------

### Configure Test Environment Variables

Source: https://github.com/gettilled/tilled-node/blob/main/CONTRIBUTING.md

Create a .env file in your root directory with these variables to configure the testing environment. Replace placeholders with your actual Tilled API keys and account IDs.

```dotenv
TILLED_SECRET_KEY=sk_XXXX
TILLED_PARTNER_ACCOUNT=acct_XXXX
VITE_TILLED_PUBLIC_KEY=pk_XXXX
VITE_TILLED_MERCHANT_ACCOUNT_ID=acct_YYYY
VITE_TILLED_CUSTOMER_ID=cus_XXXX
```

--------------------------------

### Update Git Submodule

Source: https://github.com/gettilled/tilled-node/blob/main/CONTRIBUTING.md

After generating the SDK, run this command to initialize and update the git submodule used for testing.

```bash
git submodule update --init --recursive
```

--------------------------------

### Configure Tilled Node SDK Request Settings

Source: https://github.com/gettilled/tilled-node/blob/main/README.md

Set up the SDK's request configuration, including API key, base path (sandbox or production), and Axios base options like timeouts.

```typescript
const config = new Configuration({
  apiKey: process.env.TILLED_SECRET_KEY,
  basePath: 'https://sandbox-api.tilled.com', // defaults to https://api.tilled.com
  baseOptions: { timeout: 2000 } // override default settings with an Axios config
});
```

--------------------------------

### Import Tilled Node SDK Modules

Source: https://github.com/gettilled/tilled-node/blob/main/README.md

Import necessary modules like Configuration, PaymentIntentsApi, and parameter types for making API calls.

```typescript
import {
  Configuration,
  PaymentIntentsApi,
  PaymentIntentCreateParams,
  PaymentIntentConfirmParams
} from 'tilled-node';
```

--------------------------------

### Create Customer

Source: https://context7.com/gettilled/tilled-node/llms.txt

Creates a new Customer object to store contact information and link payment methods for future charges or subscriptions.

```APIDOC
## Create Customer

### Description
Creates a new Customer object to store contact information and link payment methods for future charges or subscriptions.

### Method
`CustomersApi.createCustomer`

### Parameters
#### Request Body
- **tilled_account** (string) - Required - The Tilled account ID.
- **CustomerCreateParams** (object) - Required - The parameters for creating a customer.
  - **first_name** (string) - Optional - The customer's first name.
  - **last_name** (string) - Optional - The customer's last name.
  - **email** (string) - Optional - The customer's email address.
  - **phone** (string) - Optional - The customer's phone number.
  - **metadata** (object) - Optional - Key-value pairs to store additional information about the customer.

### Request Example
```typescript
const params = {
  first_name: 'Jane',
  last_name: 'Doe',
  email: 'jane.doe@example.com',
  phone: '+15125550100',
  metadata: { internal_id: 'usr_789' }
};

const response = await customersApi.createCustomer({
  tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
  CustomerCreateParams: params
});
```

### Response
#### Success Response (200)
- **data** (object) - The created Customer object.
  - **id** (string) - The unique identifier for the Customer.
  - **first_name** (string) - The customer's first name.
  - **last_name** (string) - The customer's last name.
  - **email** (string) - The customer's email address.
  - **phone** (string) - The customer's phone number.
  - **metadata** (object) - Key-value pairs stored for the customer.

#### Response Example
```json
{
  "data": {
    "id": "cust_XXXXXXXXXXXXXXXXXXXXXXXXX",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+15125550100",
    "metadata": {
      "internal_id": "usr_789"
    }
  }
}
```
```

--------------------------------

### Create a Checkout Session with Tilled Node

Source: https://context7.com/gettilled/tilled-node/llms.txt

Use `createCheckoutSession` to generate a redirect URL for payments without a custom frontend. Specify line items, payment methods, and URLs for success and cancellation.

```typescript
import { Configuration, CheckoutSessionsApi, CheckoutSessionCreateParams } from 'tilled-node';

const checkoutSessionsApi = new CheckoutSessionsApi(config);

async function createCheckoutSession() {
  try {
    const params: CheckoutSessionCreateParams = {
      line_items: [
        {
          price_data: {
            currency: 'usd',
            unit_amount: 4999,
            product_data: { name: 'Premium Plan' }
          },
          quantity: 1
        }
      ],
      payment_method_types: ['card'],
      mode: 'payment',
      success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: 'https://example.com/cancel'
    };

    const response = await checkoutSessionsApi.createCheckoutSession({
      tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
      CheckoutSessionCreateParams: params
    });

    console.log('Checkout URL:', response.data.url);
    return response.data;
  } catch (error) {
    console.error('Checkout session creation failed:', error);
    throw error;
  }
}
```

--------------------------------

### Create Customer

Source: https://context7.com/gettilled/tilled-node/llms.txt

Creates a new Customer object to store contact information and link payment methods for future use. Can also store metadata.

```typescript
import { Configuration, CustomersApi, CustomerCreateParams } from 'tilled-node';

const customersApi = new CustomersApi(config);

async function createCustomer() {
  try {
    const params: CustomerCreateParams = {
      first_name: 'Jane',
      last_name: 'Doe',
      email: 'jane.doe@example.com',
      phone: '+15125550100',
      metadata: { internal_id: 'usr_789' }
    };

    const response = await customersApi.createCustomer({
      tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
      CustomerCreateParams: params
    });

    console.log('Created customer:', response.data.id);
    return response.data;
  } catch (error) {
    console.error('Customer creation failed:', error);
    throw error;
  }
}
```

--------------------------------

### Create a Payment Intent Endpoint

Source: https://github.com/gettilled/tilled-node/blob/main/README.md

Set up a POST endpoint to create a payment intent. This endpoint expects the Tilled account ID in the headers and payment intent parameters in the request body.

```typescript
app.post(
  '/payment-intents',
  (
    req: Request & {
      headers: {
        tilled_account: string;
      };
      body: PaymentIntentCreateParams;
    },
    res: Response & {
      json: any;
      send: any;
      status: any;
    }
  ) => {
    const { tilled_account } = req.headers;

    paymentIntentsApi
      .createPaymentIntent({
        tilled_account,
        PaymentIntentCreateParams: req.body
      })
      .then((response) => {
        return response.data;
      })
      .then((data) => {
        res.json(data);
        console.log(data);
      })
      .catch((error) => {
        console.error(error);
        res.status(404).json(error);
      });
  }
);
```

--------------------------------

### Instantiate Payment Intents API Client

Source: https://github.com/gettilled/tilled-node/blob/main/README.md

Create a new instance of the PaymentIntentsApi using the configured request settings.

```typescript
const paymentIntentsApi = new PaymentIntentsApi(config);
```

--------------------------------

### Express.js Payment Flow

Source: https://context7.com/gettilled/tilled-node/llms.txt

Demonstrates a full backend payment flow integrating PaymentIntentsApi into an Express.js server.

```APIDOC
## PaymentIntentsApi Integration with Express.js

### Create Payment Intent Endpoint

#### Description
Creates a payment intent and returns a `client_secret` to the frontend for processing payments.

### Method
```http
POST /payment-intents
```

### Headers
- **tilled-account** (string) - Required - The Tilled account ID.

### Request Body
- **PaymentIntentCreateParams** (object) - Required - Parameters for creating a payment intent.
  (Refer to Tilled API documentation for specific fields)

### Response
#### Success Response (200)
- **data** (object) - Contains the created payment intent details, including `client_secret`.


### Confirm Payment Intent Endpoint

#### Description
Confirms a payment intent using payment method details provided by Tilled.js.

### Method
```http
POST /payment-intents/:id/confirm
```

### Headers
- **tilled-account** (string) - Required - The Tilled account ID.

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the payment intent to confirm.

### Request Body
- **PaymentIntentConfirmParams** (object) - Required - Parameters for confirming the payment intent.
  (Refer to Tilled API documentation for specific fields)

### Response
#### Success Response (200)
- **data** (object) - Contains the confirmed payment intent details.
```

--------------------------------

### Create a Subscription

Source: https://context7.com/gettilled/tilled-node/llms.txt

Creates a recurring billing subscription for a customer. Requires a customer ID, payment method ID, and a price ID from PricingTemplatesApi.

```typescript
import { Configuration, SubscriptionsApi, SubscriptionCreateParams } from 'tilled-node';

const subscriptionsApi = new SubscriptionsApi(config);

async function createSubscription(customerId: string, paymentMethodId: string) {
  try {
    const params: SubscriptionCreateParams = {
      customer_id: customerId,
      payment_method_id: paymentMethodId,
      price_id: 'price_XXXXXXXXXXXXXXXXXXXXXXXXX',   // from PricingTemplatesApi
      billing_cycle_anchor: Math.floor(Date.now() / 1000),
      metadata: { plan: 'monthly_basic' }
    };

    const response = await subscriptionsApi.createSubscription({
      tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
      SubscriptionCreateParams: params
    });

    console.log('Created subscription:', response.data.id, '→ status:', response.data.status);
    return response.data;
  } catch (error) {
    console.error('Subscription creation failed:', error);
    throw error;
  }
}
```

--------------------------------

### Create Webhook Endpoint

Source: https://context7.com/gettilled/tilled-node/llms.txt

Registers a URL to receive real-time event notifications for payment and account activity.

```APIDOC
## WebhookEndpointsApi.createWebhookEndpoint

### Description
Registers a URL to receive real-time event notifications for payment and account activity.

### Method
```typescript
createWebhookEndpoint
```

### Parameters
#### Path Parameters
- **tilled_account** (string) - Required - The Tilled account ID.

#### Request Body
- **WebhookEndpointCreateParams** (object) - Required - Parameters for creating a webhook endpoint.
  - **url** (string) - Required - The URL to send webhook notifications to.
  - **enabled_events** (array of strings) - Required - A list of events to receive notifications for.
  - **description** (string) - Optional - A description for the webhook.

### Request Example
```json
{
  "tilled_account": "acct_XXXXXXXXXXXXXXXXXXXXXXXXX",
  "WebhookEndpointCreateParams": {
    "url": "https://your-server.example.com/webhooks/tilled",
    "enabled_events": [
      "payment_intent.succeeded",
      "payment_intent.payment_failed",
      "charge.refunded",
      "customer.subscription.deleted"
    ],
    "description": "Production webhook for payment events"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the created webhook endpoint details.
  - **id** (string) - The unique identifier for the webhook endpoint.
  - **secret** (string) - The secret used for verifying webhook signatures.
```

--------------------------------

### Local SDK Testing Dependency

Source: https://github.com/gettilled/tilled-node/blob/main/CONTRIBUTING.md

Add this entry to your project's dependencies to test the locally developed 'tilled-node' SDK. Ensure the path points to the correct 'dist' directory.

```json
"dependencies": {
    "tilled-node": "file:../tilled-node/dist"
  }
```

--------------------------------

### List Customers with Search

Source: https://context7.com/gettilled/tilled-node/llms.txt

Retrieves a paginated list of customers, supporting full-text search and metadata filtering. Ensure the Tilled SDK is configured.

```typescript
import { Configuration, CustomersApi } from 'tilled-node';

const customersApi = new CustomersApi(config);

async function searchCustomers(searchQuery: string) {
  try {
    const response = await customersApi.listCustomers({
      tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
      q: searchQuery,     // partial match on name, email, phone
      limit: 25,
      offset: 0
    });

    const { items, total } = response.data;
    console.log(`Found ${total} customers matching "${searchQuery}"`);
    items.forEach(c => console.log(`${c.id}: ${c.first_name} ${c.last_name} (${c.email})`));
    return response.data;
  } catch (error) {
    console.error('Search failed:', error);
    throw error;
  }
}
```

--------------------------------

### List Customer's Payment Methods

Source: https://context7.com/gettilled/tilled-node/llms.txt

Returns all Payment Methods of a given type for a specific customer, sorted most recently created first.

```APIDOC
## List Customer's Payment Methods

### Description
Returns all Payment Methods of a given type for a specific customer, sorted most recently created first.

### Method
`PaymentMethodsApi.listPaymentMethods`

### Parameters
#### Query Parameters
- **tilled_account** (string) - Required - The Tilled account ID.
- **type** (string) - Required - The type of payment methods to list (e.g., 'card', 'bank_account').
- **customer_id** (string) - Required - The ID of the Customer whose payment methods to list.
- **limit** (integer) - Optional - The maximum number of payment methods to return (default: 10).
- **offset** (integer) - Optional - The number of payment methods to skip (default: 0).

### Request Example
```typescript
const response = await paymentMethodsApi.listPaymentMethods({
  tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
  type: 'card',
  customer_id: 'cust_XXXXXXXXXXXXXXXXXXXXXXXXX',
  limit: 10,
  offset: 0
});
```

### Response
#### Success Response (200)
- **data** (object) - Contains a list of PaymentMethod objects.
  - **items** (array) - An array of PaymentMethod objects.
    - **id** (string) - The unique identifier for the PaymentMethod.
    - **card** (object) - Card details if the type is 'card'.
      - **brand** (string) - The brand of the card (e.g., 'visa', 'mastercard').
      - **last4** (string) - The last 4 digits of the card number.
      - **exp_month** (integer) - The expiration month.
      - **exp_year** (integer) - The expiration year.

#### Response Example
```json
{
  "data": {
    "items": [
      {
        "id": "pm_XXXXXXXXXXXXXXXXXXXXXXXXX",
        "type": "card",
        "card": {
          "brand": "visa",
          "last4": "4242",
          "exp_month": 12,
          "exp_year": 2026
        },
        "customer_id": "cust_XXXXXXXXXXXXXXXXXXXXXXXXX"
      }
    ]
  }
}
```
```

--------------------------------

### List Customer's Payment Methods

Source: https://context7.com/gettilled/tilled-node/llms.txt

Retrieves all Payment Methods of a specific type for a customer, sorted by creation date. Useful for displaying a customer's saved payment options.

```typescript
import { Configuration, PaymentMethodsApi, ListPaymentMethodsType } from 'tilled-node';

const paymentMethodsApi = new PaymentMethodsApi(config);

async function listCustomerCards(customerId: string) {
  try {
    const response = await paymentMethodsApi.listPaymentMethods({
      tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
      type: ListPaymentMethodsType.CARD,
      customer_id: customerId,
      limit: 10,
      offset: 0
    });

    const { items } = response.data;
    items.forEach(pm => {
      console.log(`${pm.id} — ${pm.card?.brand} ending in ${pm.card?.last4} (exp ${pm.card?.exp_month}/${pm.card?.exp_year})`);
    });
    return response.data;
  } catch (error) {
    console.error('List failed:', error);
    throw error;
  }
}
```

--------------------------------

### Create a Checkout Session

Source: https://context7.com/gettilled/tilled-node/llms.txt

Creates a hosted checkout session that generates a redirect URL for collecting payment without a custom frontend form.

```APIDOC
## CheckoutSessionsApi.createCheckoutSession

### Description
Creates a hosted checkout session that generates a redirect URL for collecting payment without a custom frontend form.

### Method
POST (inferred from SDK method)

### Endpoint
(Inferred from SDK method context, typically related to checkout sessions)

### Parameters
#### Path Parameters
None explicitly defined in the example.

#### Query Parameters
None explicitly defined in the example.

#### Request Body
- **tilled_account** (string) - Required - The Tilled account ID for which to create the checkout session.
- **CheckoutSessionCreateParams** (object) - Required - The parameters for creating the checkout session.
  - **line_items** (array) - Required - A list of items to be included in the checkout session.
    - **price_data** (object) - Required - Details about the price of the item.
      - **currency** (string) - Required - The currency of the price (e.g., 'usd').
      - **unit_amount** (integer) - Required - The amount in the smallest currency unit (e.g., cents).
      - **product_data** (object) - Required - Information about the product.
        - **name** (string) - Required - The name of the product.
    - **quantity** (integer) - Required - The quantity of the item.
  - **payment_method_types** (array) - Required - An array of payment method types to accept (e.g., ['card']).
  - **mode** (string) - Required - The mode of the checkout session (e.g., 'payment', 'subscription').
  - **success_url** (string) - Required - The URL to redirect to after a successful payment.
  - **cancel_url** (string) - Required - The URL to redirect to if the user cancels the checkout.

### Request Example
```json
{
  "tilled_account": "acct_XXXXXXXXXXXXXXXXXXXXXXXXX",
  "CheckoutSessionCreateParams": {
    "line_items": [
      {
        "price_data": {
          "currency": "usd",
          "unit_amount": 4999,
          "product_data": {
            "name": "Premium Plan"
          }
        },
        "quantity": 1
      }
    ],
    "payment_method_types": ["card"],
    "mode": "payment",
    "success_url": "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://example.com/cancel"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the created checkout session details.
  - **url** (string) - The URL to redirect the user to for completing the checkout.

#### Response Example
```json
{
  "data": {
    "id": "csession_XXXXXXXXXXXXXXXXXXXXXXXXX",
    "url": "https://checkout.tilled.com/pay/csession_XXXXXXXXXXXXXXXXXXXXXXXXX",
    "status": "open"
    // ... other checkout session details
  }
}
```
```

--------------------------------

### Add an Account Capability

Source: https://context7.com/gettilled/tilled-node/llms.txt

Adds a processing capability (e.g., credit card processing, ACH debit) to an account before the onboarding application is submitted.

```APIDOC
## AccountsApi.addAccountCapability

### Description
Adds a processing capability (e.g., credit card processing, ACH debit) to an account before the onboarding application is submitted.

### Method
POST (inferred from SDK method)

### Endpoint
(Inferred from SDK method context, typically related to account capabilities)

### Parameters
#### Path Parameters
None explicitly defined in the example.

#### Query Parameters
None explicitly defined in the example.

#### Request Body
- **tilled_account** (string) - Required - The Tilled account ID to which the capability will be added.
- **AccountCapabilityCreateParams** (object) - Required - The details of the capability to add.
  - **type** (string) - Required - The type of capability to add (e.g., 'card_payments', 'ach_debits').
  - **pricing_template_id** (string) - Required - The ID of the pricing template to associate with the capability.

### Request Example
```json
{
  "tilled_account": "acct_XXXXXXXXXXXXXXXXXXXXXXXXX",
  "AccountCapabilityCreateParams": {
    "type": "card_payments",
    "pricing_template_id": "ptmpl_XXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the updated account capabilities.
  - **capabilities** (array) - A list of the account's current capabilities.

#### Response Example
```json
{
  "data": {
    "capabilities": [
      {
        "type": "card_payments",
        "status": "pending"
        // ... other capability details
      }
      // ... other capabilities
    ]
  }
}
```
```

--------------------------------

### CustomersApi.listCustomers

Source: https://context7.com/gettilled/tilled-node/llms.txt

Retrieves a paginated list of customers. Supports full-text search and metadata filtering.

```APIDOC
## List Customers

`CustomersApi.listCustomers` retrieves a paginated list of customers, supporting full-text search across name, email, and phone fields, as well as metadata key-value filtering.

### Method

```typescript
customersApi.listCustomers({
  tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
  q: searchQuery,     // partial match on name, email, phone
  limit: 25,
  offset: 0
});
```

### Parameters

- **tilled_account** (string) - Required - The Tilled account ID.
- **q** (string) - Optional - Full-text search query.
- **limit** (number) - Optional - Number of results to return per page.
- **offset** (number) - Optional - Number of results to skip.
```

--------------------------------

### Create Payment Method with Card Details

Source: https://context7.com/gettilled/tilled-node/llms.txt

Use this to create a Payment Method directly from card data. Requires PCI Attestation of Compliance (AOC) submission to Tilled.

```typescript
import { Configuration, PaymentMethodsApi, PaymentMethodCreateParams } from 'tilled-node';

const paymentMethodsApi = new PaymentMethodsApi(config);

async function createCardPaymentMethod() {
  try {
    const params: PaymentMethodCreateParams = {
      type: 'card',
      billing_details: {
        name: 'Jane Doe',
        email: 'jane@example.com',
        address: {
          street: '123 Main St',
          city: 'Austin',
          state: 'TX',
          zip: '78701',
          country: 'US'
        }
      },
      card: {
        number: '4111111111111111',
        exp_month: 12,
        exp_year: 2026,
        cvc: '123'
      }
    };

    const response = await paymentMethodsApi.createPaymentMethod({
      tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
      PaymentMethodCreateParams: params
    });

    console.log('Created PaymentMethod:', response.data.id);
    console.log('Last4:', response.data.card?.last4);
    return response.data;
  } catch (error) {
    console.error('PaymentMethod creation failed:', error);
    throw error;
  }
}
```

--------------------------------

### Create a Connected Account

Source: https://context7.com/gettilled/tilled-node/llms.txt

Creates a merchant sub-account (connected account) under a partner/platform account for multi-merchant payment facilitation.

```APIDOC
## AccountsApi.createConnectedAccount

### Description
Creates a merchant sub-account (connected account) under a partner/platform account for multi-merchant payment facilitation.

### Method
POST (inferred from SDK method)

### Endpoint
(Inferred from SDK method context, typically related to accounts)

### Parameters
#### Path Parameters
None explicitly defined in the example.

#### Query Parameters
None explicitly defined in the example.

#### Request Body
- **tilled_account** (string) - Required - The Tilled account ID of the partner/platform.
- **CreateConnectedAccountRequest** (object) - Required - The details for the new connected account.
  - **email** (string) - Required - The email address of the merchant.
  - **business_profile** (object) - Required - Information about the merchant's business.
    - **legal_name** (string) - Required - The legal name of the business.
    - **mcc** (string) - Required - The Merchant Category Code.
    - **url** (string) - Required - The URL of the business.

### Request Example
```json
{
  "tilled_account": "acct_PARTNER_ACCOUNT_ID",
  "CreateConnectedAccountRequest": {
    "email": "merchant@example.com",
    "business_profile": {
      "legal_name": "Acme Corp",
      "mcc": "5734",
      "url": "https://acme.example.com"
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the created connected account details.
  - **id** (string) - The unique identifier of the created connected account.

#### Response Example
```json
{
  "data": {
    "id": "acct_CONNECTED_ACCOUNT_ID",
    "email": "merchant@example.com",
    "business_profile": {
      "legal_name": "Acme Corp",
      "mcc": "5734",
      "url": "https://acme.example.com"
    }
    // ... other account details
  }
}
```
```

--------------------------------

### Attach Payment Method to Customer

Source: https://context7.com/gettilled/tilled-node/llms.txt

Converts a single-use Payment Method into a reusable one by attaching it to a Customer. Payment Methods expire 15 minutes after creation.

```APIDOC
## Attach Payment Method to Customer

### Description
Converts a single-use Payment Method into a reusable one by attaching it to a Customer. Payment Methods expire 15 minutes after creation.

### Method
`PaymentMethodsApi.attachPaymentMethodToCustomer`

### Endpoint
`/payment-methods/{id}/attach`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Payment Method to attach.

#### Request Body
- **tilled_account** (string) - Required - The Tilled account ID.
- **PaymentMethodAttachParams** (object) - Required - The parameters for attaching the payment method.
  - **customer_id** (string) - Required - The ID of the Customer to attach the Payment Method to.

### Request Example
```typescript
const params = {
  customer_id: 'cust_XXXXXXXXXXXXXXXXXXXXXXXXX'
};

const response = await paymentMethodsApi.attachPaymentMethodToCustomer({
  tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
  id: 'pm_XXXXXXXXXXXXXXXXXXXXXXXXX',
  PaymentMethodAttachParams: params
});
```

### Response
#### Success Response (200)
- **data** (object) - The updated PaymentMethod object.
  - **customer_id** (string) - The ID of the Customer the Payment Method is now attached to.

#### Response Example
```json
{
  "data": {
    "id": "pm_XXXXXXXXXXXXXXXXXXXXXXXXX",
    "customer_id": "cust_XXXXXXXXXXXXXXXXXXXXXXXXX"
  }
}
```
```

--------------------------------

### Bump SDK Version

Source: https://github.com/gettilled/tilled-node/blob/main/CONTRIBUTING.md

Use these npm commands to increment the version number of the SDK before committing changes. Choose 'patch', 'minor', or 'major' based on the type of changes.

```bash
npm version patch // 1.0.1
```

```bash
npm version minor // 1.1.0
```

```bash
npm version major // 2.0.0
```

--------------------------------

### Create a Connected Account with Tilled Node

Source: https://context7.com/gettilled/tilled-node/llms.txt

Use `createConnectedAccount` to create a sub-account for a merchant. Ensure you provide the necessary business profile details.

```typescript
import { Configuration, AccountsApi, CreateConnectedAccountRequest } from 'tilled-node';

const accountsApi = new AccountsApi(config);

async function createMerchantAccount() {
  try {
    const params: CreateConnectedAccountRequest = {
      email: 'merchant@example.com',
      business_profile: {
        legal_name: 'Acme Corp',
        mcc: '5734',
        url: 'https://acme.example.com'
      }
    };

    const response = await accountsApi.createConnectedAccount({
      tilled_account: 'acct_PARTNER_ACCOUNT_ID',
      CreateConnectedAccountRequest: params
    });

    console.log('Connected account created:', response.data.id);
    return response.data;
  } catch (error) {
    console.error('Account creation failed:', error);
    throw error;
  }
}
```

--------------------------------

### Attach Payment Method to Customer

Source: https://context7.com/gettilled/tilled-node/llms.txt

Converts a single-use Payment Method into a reusable one by attaching it to a Customer. Payment Methods expire 15 minutes after creation.

```typescript
import { Configuration, PaymentMethodsApi, PaymentMethodAttachParams } from 'tilled-node';

const paymentMethodsApi = new PaymentMethodsApi(config);

async function attachPaymentMethod(paymentMethodId: string, customerId: string) {
  try {
    const params: PaymentMethodAttachParams = {
      customer_id: customerId
    };

    const response = await paymentMethodsApi.attachPaymentMethodToCustomer({
      tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
      id: paymentMethodId,
      PaymentMethodAttachParams: params
    });

    console.log('Attached PaymentMethod to customer:', response.data.customer_id);
    return response.data;
  } catch (error) {
    console.error('Attach failed:', error);
    throw error;
  }
}
```

--------------------------------

### Create Payment Method

Source: https://context7.com/gettilled/tilled-node/llms.txt

Creates a Payment Method directly from card or bank account data. Requires PCI Attestation of Compliance (AOC) submission to Tilled before use.

```APIDOC
## Create Payment Method

### Description
Creates a Payment Method directly from card or bank account data. Requires PCI Attestation of Compliance (AOC) submission to Tilled before use.

### Method
`PaymentMethodsApi.createPaymentMethod`

### Parameters
#### Request Body
- **tilled_account** (string) - Required - The Tilled account ID.
- **PaymentMethodCreateParams** (object) - Required - The parameters for creating a payment method.
  - **type** (string) - Required - The type of payment method ('card' or 'bank_account').
  - **billing_details** (object) - Required - Billing information for the payment method.
    - **name** (string) - Required - Full name of the cardholder or account holder.
    - **email** (string) - Required - Email address of the cardholder or account holder.
    - **address** (object) - Required - Billing address.
      - **street** (string) - Required - Street address.
      - **city** (string) - Required - City.
      - **state** (string) - Required - State or province (2-letter code for US/CA, full name otherwise).
      - **zip** (string) - Required - Postal code.
      - **country** (string) - Required - Country (2-letter ISO code).
  - **card** (object) - Required if type is 'card' - Card details.
    - **number** (string) - Required - The card number.
    - **exp_month** (integer) - Required - The expiration month (1-12).
    - **exp_year** (integer) - Required - The expiration year.
    - **cvc** (string) - Required - The CVC security code.

### Request Example
```typescript
const params = {
  type: 'card',
  billing_details: {
    name: 'Jane Doe',
    email: 'jane@example.com',
    address: {
      street: '123 Main St',
      city: 'Austin',
      state: 'TX',
      zip: '78701',
      country: 'US'
    }
  },
  card: {
    number: '4111111111111111',
    exp_month: 12,
    exp_year: 2026,
    cvc: '123'
  }
};

const response = await paymentMethodsApi.createPaymentMethod({
  tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
  PaymentMethodCreateParams: params
});
```

### Response
#### Success Response (200)
- **data** (object) - The created PaymentMethod object.
  - **id** (string) - The unique identifier for the PaymentMethod.
  - **card** (object) - Card details if the type is 'card'.
    - **last4** (string) - The last 4 digits of the card number.
    - **brand** (string) - The brand of the card (e.g., 'visa', 'mastercard').
    - **exp_month** (integer) - The expiration month.
    - **exp_year** (integer) - The expiration year.

#### Response Example
```json
{
  "data": {
    "id": "pm_XXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "card",
    "card": {
      "last4": "1111",
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2026
    },
    "billing_details": {
      "name": "Jane Doe",
      "email": "jane@example.com",
      "address": {
        "street": "123 Main St",
        "city": "Austin",
        "state": "TX",
        "zip": "78701",
        "country": "US"
      }
    }
  }
}
```
```

--------------------------------

### Confirm a Payment Intent Endpoint

Source: https://github.com/gettilled/tilled-node/blob/main/README.md

Set up a POST endpoint to confirm a payment intent. This endpoint requires the payment intent ID in the URL parameters and confirmation details in the request body.

```typescript
app.post(
  '/payment-intents/:id/confirm',
  (
    req: Request & {
      headers: {
        tilled_account: string;
      };
      params: {
        id: string;
      };
      body: PaymentIntentConfirmParams;
    },
    res: Response & {
      json: any;
      send: any;
      status: any;
    }
  ) => {
    const { tilled_account } = req.headers;
    const { id } = req.params;

    paymentIntentsApi
      .confirmPaymentIntent({
        tilled_account,
        id,
        PaymentIntentConfirmParams: req.body
      })
      .then((response) => {
        return response.data;
      })
      .then((data) => {
        res.json(data);
        console.log(data);
      })
      .catch((error) => {
        console.error(error);
        res.status(404).json(error);
      });
  }
);
```

--------------------------------

### Create a Payment Intent

Source: https://context7.com/gettilled/tilled-node/llms.txt

Create a new Payment Intent for a given amount and currency. The `client_secret` returned is used with Tilled.js on the frontend. Ensure the `tilled_account` header is correctly set.

```typescript
import { Configuration, PaymentIntentsApi, PaymentIntentCreateParams } from 'tilled-node';

const config = new Configuration({
  apiKey: process.env.TILLED_SECRET_KEY,
  basePath: 'https://sandbox-api.tilled.com'
});
const paymentIntentsApi = new PaymentIntentsApi(config);

const tilledAccount = 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX';

async function createPaymentIntent() {
  try {
    const params: PaymentIntentCreateParams = {
      amount: 10000,           // amount in cents ($100.00)
      currency: 'usd',
      payment_method_types: ['card'],
      capture_method: 'automatic',
      metadata: { order_id: 'ord_abc123' }
    };

    const response = await paymentIntentsApi.createPaymentIntent({
      tilled_account: tilledAccount,
      PaymentIntentCreateParams: params
    });

    const paymentIntent = response.data;
    console.log('Created PaymentIntent:', paymentIntent.id);
    // paymentIntent.client_secret → pass to Tilled.js frontend
    return paymentIntent;
  } catch (error) {
    console.error('Failed to create payment intent:', error);
    throw error;
  }
}
```

--------------------------------

### Create a Refund

Source: https://context7.com/gettilled/tilled-node/llms.txt

Issues a partial or full refund against a succeeded charge or payment intent. Specify an amount in cents for a partial refund; omit for a full refund.

```typescript
import { Configuration, RefundsApi, RefundCreateParams } from 'tilled-node';

const refundsApi = new RefundsApi(config);

async function createRefund(chargeId: string, amountCents?: number) {
  try {
    const params: RefundCreateParams = {
      charge_id: chargeId,
      amount: amountCents,   // omit for full refund
      reason: 'requested_by_customer',
      metadata: { support_ticket: 'TICK-4321' }
    };

    const response = await refundsApi.createRefund({
      tilled_account: 'acct_XXXXXXXXXXXXXXXXXXXXXXXXX',
      RefundCreateParams: params
    });

    console.log('Refund created:', response.data.id, '→ amount:', response.data.amount);
    return response.data;
  } catch (error) {
    console.error('Refund failed:', error);
    throw error;
  }
}
```

--------------------------------

### List Payment Intents

Source: https://context7.com/gettilled/tilled-node/llms.txt

`PaymentIntentsApi.listPaymentIntents` retrieves a paginated list of Payment Intents, sortable and filterable by status, date range, customer, subscription, and more.

```APIDOC
## List Payment Intents

### Description
Retrieves a paginated list of Payment Intents. The results can be sorted and filtered by various criteria including status, date range, customer, and subscription.

### Method
`PaymentIntentsApi.listPaymentIntents`

### Parameters
- `tilled_account` (string) - Required - The Tilled account ID.
- `status` (array of strings) - Optional - Filters the list by Payment Intent status. Possible values include `SUCCEEDED`, `FAILED`, `REQUIRES_PAYMENT_METHOD`, etc.
- `created_at_gte` (string) - Optional - Filters Payment Intents created on or after this date/time (ISO 8601 format).
- `created_at_lte` (string) - Optional - Filters Payment Intents created on or before this date/time (ISO 8601 format).
- `limit` (number) - Optional - The maximum number of Payment Intents to return per page. Defaults to 20.
- `offset` (number) - Optional - The number of Payment Intents to skip before returning results. Defaults to 0.
```