KosmoKrator

data

Paddle Lua API for KosmoKrator Agents

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

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.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Paddle workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.paddle.list_transactions({limit = 1, after = "example_after", status = "example_status", customer_id = "example_customer_id"}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("paddle"))' --json
kosmo integrations:lua --eval 'print(docs.read("paddle.list_transactions"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

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

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.paddle, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.paddle.default.* or app.integrations.paddle.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Paddle, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

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 = "john@example.com"
})

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 = "jane@example.com",
  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 = "john@example.com"
})

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 = "jane@example.com",
  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.list_transactions({limit = 1, after = "example_after", status = "example_status", customer_id = "example_customer_id"})
print(result)

Functions

list_transactions Read

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

Lua path
app.integrations.paddle.list_transactions
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.
get_transaction Read

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

Lua path
app.integrations.paddle.get_transaction
Full name
paddle.paddle_get_transaction
ParameterTypeRequiredDescription
id string yes The Paddle transaction ID (e.g., "txn_01abc123").
list_customers Read

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

Lua path
app.integrations.paddle.list_customers
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.
get_customer Read

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

Lua path
app.integrations.paddle.get_customer
Full name
paddle.paddle_get_customer
ParameterTypeRequiredDescription
id string yes The Paddle customer ID (e.g., "ctm_01abc123").
create_customer Write

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

Lua path
app.integrations.paddle.create_customer
Full name
paddle.paddle_create_customer
ParameterTypeRequiredDescription
email string yes Customer email address.
name string no Customer display name.
list_products Read

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

Lua path
app.integrations.paddle.list_products
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".
health_check Read

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

Lua path
app.integrations.paddle.health_check
Full name
paddle.paddle_get_current_user
ParameterTypeRequiredDescription
No parameters.