KosmoKrator

other

Paddle Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Paddle KosmoKrator integration.

7 functions 6 read 1 write Bearer token auth
Submit Paddle feedback View package source

Lua Namespace

Agents call this integration through app.integrations.paddle.*. Use lua_read_doc("integrations.paddle") inside KosmoKrator to discover the same reference at runtime.

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Paddle — Lua API Reference

list_transactions

List Paddle transactions with optional filters and cursor-based pagination.

Parameters

NameTypeRequiredDescription
limitintegernoMax results per page (default: 50)
afterstringnoPagination cursor from a previous response
statusstringnoFilter by status: "completed", "pending", "billed", "paid", "canceled", "past_due"
customer_idstringnoFilter by customer ID

Examples

local result = app.integrations.paddle.list_transactions({
  limit = 10,
  status = "completed"
})

for _, txn in ipairs(result.data) do
  print(txn.id .. ": " .. txn.status .. " — " .. txn.details.totals.grand_total)
end

get_transaction

Get details of a specific Paddle transaction.

Parameters

NameTypeRequiredDescription
idstringyesTransaction ID (e.g., "txn_01abc123")

Examples

local result = app.integrations.paddle.get_transaction({
  id = "txn_01abc123"
})

print("Status: " .. result.data.status)
print("Amount: " .. result.data.details.totals.grand_total)

list_customers

List Paddle customers with optional filters and cursor-based pagination.

Parameters

NameTypeRequiredDescription
limitintegernoMax results per page (default: 50)
afterstringnoPagination cursor from a previous response
emailstringnoFilter by email address
namestringnoFilter by customer name

Examples

local result = app.integrations.paddle.list_customers({
  email = "[email protected]"
})

for _, customer in ipairs(result.data) do
  print(customer.id .. ": " .. customer.name .. " <" .. customer.email .. ">")
end

get_customer

Get details of a specific Paddle customer.

Parameters

NameTypeRequiredDescription
idstringyesCustomer ID (e.g., "ctm_01abc123")

Examples

local result = app.integrations.paddle.get_customer({
  id = "ctm_01abc123"
})

print("Name: " .. result.data.name)
print("Email: " .. result.data.email)

create_customer

Create a new customer in Paddle.

Parameters

NameTypeRequiredDescription
emailstringyesCustomer email address
namestringnoCustomer display name

Examples

local result = app.integrations.paddle.create_customer({
  email = "[email protected]",
  name = "Jane Doe"
})

print("Created customer: " .. result.data.id)

list_products

List Paddle products with optional filters and cursor-based pagination.

Parameters

NameTypeRequiredDescription
limitintegernoMax results per page (default: 50)
afterstringnoPagination cursor from a previous response
statusstringnoFilter by status: "active", "archived"

Examples

local result = app.integrations.paddle.list_products({
  status = "active",
  limit = 20
})

for _, product in ipairs(result.data) do
  print(product.id .. ": " .. product.name)
end

get_current_user

Verify Paddle API connectivity with a health check.

Parameters

None.

Examples

local result = app.integrations.paddle.get_current_user({})

if result.connected then
  print("Paddle API is reachable!")
else
  print("Connection failed: " .. result.error)
end

Multi-Account Usage

If you have multiple Paddle accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.paddle.list_transactions({...})

-- Explicit default (portable across setups)
app.integrations.paddle.default.list_transactions({...})

-- Named accounts
app.integrations.paddle.sandbox.list_transactions({...})
app.integrations.paddle.production.list_transactions({...})

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Paddle — Lua API Reference

## list_transactions

List Paddle transactions with optional filters and cursor-based pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Max results per page (default: 50) |
| `after` | string | no | Pagination cursor from a previous response |
| `status` | string | no | Filter by status: `"completed"`, `"pending"`, `"billed"`, `"paid"`, `"canceled"`, `"past_due"` |
| `customer_id` | string | no | Filter by customer ID |

### Examples

```lua
local result = app.integrations.paddle.list_transactions({
  limit = 10,
  status = "completed"
})

for _, txn in ipairs(result.data) do
  print(txn.id .. ": " .. txn.status .. " — " .. txn.details.totals.grand_total)
end
```

---

## get_transaction

Get details of a specific Paddle transaction.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | Transaction ID (e.g., `"txn_01abc123"`) |

### Examples

```lua
local result = app.integrations.paddle.get_transaction({
  id = "txn_01abc123"
})

print("Status: " .. result.data.status)
print("Amount: " .. result.data.details.totals.grand_total)
```

---

## list_customers

List Paddle customers with optional filters and cursor-based pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Max results per page (default: 50) |
| `after` | string | no | Pagination cursor from a previous response |
| `email` | string | no | Filter by email address |
| `name` | string | no | Filter by customer name |

### Examples

```lua
local result = app.integrations.paddle.list_customers({
  email = "[email protected]"
})

for _, customer in ipairs(result.data) do
  print(customer.id .. ": " .. customer.name .. " <" .. customer.email .. ">")
end
```

---

## get_customer

Get details of a specific Paddle customer.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | Customer ID (e.g., `"ctm_01abc123"`) |

### Examples

```lua
local result = app.integrations.paddle.get_customer({
  id = "ctm_01abc123"
})

print("Name: " .. result.data.name)
print("Email: " .. result.data.email)
```

---

## create_customer

Create a new customer in Paddle.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `email` | string | yes | Customer email address |
| `name` | string | no | Customer display name |

### Examples

```lua
local result = app.integrations.paddle.create_customer({
  email = "[email protected]",
  name = "Jane Doe"
})

print("Created customer: " .. result.data.id)
```

---

## list_products

List Paddle products with optional filters and cursor-based pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Max results per page (default: 50) |
| `after` | string | no | Pagination cursor from a previous response |
| `status` | string | no | Filter by status: `"active"`, `"archived"` |

### Examples

```lua
local result = app.integrations.paddle.list_products({
  status = "active",
  limit = 20
})

for _, product in ipairs(result.data) do
  print(product.id .. ": " .. product.name)
end
```

---

## get_current_user

Verify Paddle API connectivity with a health check.

### Parameters

None.

### Examples

```lua
local result = app.integrations.paddle.get_current_user({})

if result.connected then
  print("Paddle API is reachable!")
else
  print("Connection failed: " .. result.error)
end
```

---

## Multi-Account Usage

If you have multiple Paddle accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.paddle.list_transactions({...})

-- Explicit default (portable across setups)
app.integrations.paddle.default.list_transactions({...})

-- Named accounts
app.integrations.paddle.sandbox.list_transactions({...})
app.integrations.paddle.production.list_transactions({...})
```

All functions are identical across accounts — only the credentials differ.

Metadata-Derived Lua Example

local result = app.integrations.paddle.paddle_list_transactions({
  limit = 1,
  after = "example_after",
  status = "example_status",
  customer_id = "example_customer_id"
})
print(result)

Functions

paddle_list_transactions

List Paddle transactions. Supports filtering by status and customer ID, with cursor-based pagination.

Operation
Read read
Full name
paddle.paddle_list_transactions
ParameterTypeRequiredDescription
limit integer no Maximum number of transactions to return per page (default: 50).
after string no Cursor for pagination — pass the value from a previous response to get the next page.
status string no Filter by transaction status: "completed", "pending", "billed", "paid", "canceled", "past_due".
customer_id string no Filter transactions by customer ID.

paddle_get_transaction

Get detailed information about a specific Paddle transaction by its ID.

Operation
Read read
Full name
paddle.paddle_get_transaction
ParameterTypeRequiredDescription
id string yes The Paddle transaction ID (e.g., "txn_01abc123").

paddle_list_customers

List Paddle customers. Supports filtering by email and name, with cursor-based pagination.

Operation
Read read
Full name
paddle.paddle_list_customers
ParameterTypeRequiredDescription
limit integer no Maximum number of customers to return per page (default: 50).
after string no Cursor for pagination — pass the value from a previous response to get the next page.
email string no Filter customers by email address.
name string no Filter customers by name.

paddle_get_customer

Get detailed information about a specific Paddle customer by their ID.

Operation
Read read
Full name
paddle.paddle_get_customer
ParameterTypeRequiredDescription
id string yes The Paddle customer ID (e.g., "ctm_01abc123").

paddle_create_customer

Create a new customer in Paddle. An email address is required.

Operation
Write write
Full name
paddle.paddle_create_customer
ParameterTypeRequiredDescription
email string yes Customer email address.
name string no Customer display name.

paddle_list_products

List Paddle products. Supports filtering by status with cursor-based pagination.

Operation
Read read
Full name
paddle.paddle_list_products
ParameterTypeRequiredDescription
limit integer no Maximum number of products to return per page (default: 50).
after string no Cursor for pagination — pass the value from a previous response to get the next page.
status string no Filter by product status: "active", "archived".

paddle_get_current_user

Verify Paddle API connectivity by performing a health check request. Returns connection status and API response.

Operation
Read read
Full name
paddle.paddle_get_current_user
ParameterTypeRequiredDescription
No parameters.