KosmoKrator

analytics

ChartMogul Lua API for KosmoKrator Agents

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

7 functions 7 read 0 write API key auth
Submit ChartMogul feedback View package source

Lua Namespace

Agents call this integration through app.integrations.chartmogul.*. Use lua_read_doc("integrations.chartmogul") 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.

ChartMogul — Lua API Reference

list_customers

List customers from ChartMogul with optional filtering and pagination.

Parameters

NameTypeRequiredDescription
per_pageintegernoNumber of results per page (default: 50, max: 200)
pageintegernoPage number, starting from 1 (default: 1)
statusstringnoFilter by customer status: “Active”, “Cancelled”, “Future”
emailstringnoFilter by customer email address

Examples

-- List all active customers
local result = app.integrations.chartmogul.list_customers({
  status = "Active",
  per_page = 50,
  page = 1
})

for _, customer in ipairs(result.entries) do
  print(customer.name .. " (" .. customer.email .. ")")
end

-- Search by email
local result = app.integrations.chartmogul.list_customers({
  email = "[email protected]"
})

get_customer

Get details for a single ChartMogul customer by UUID.

Parameters

NameTypeRequiredDescription
idstringyesThe ChartMogul customer UUID

Examples

local result = app.integrations.chartmogul.get_customer({
  id = "cus_abc123-def456"
})

print(result.name .. " - " .. result.status)

list_subscriptions

List subscriptions with optional filtering by customer or status.

Parameters

NameTypeRequiredDescription
per_pageintegernoNumber of results per page (default: 50, max: 200)
pageintegernoPage number, starting from 1 (default: 1)
customer_uuidstringnoFilter by customer UUID
statusstringnoFilter by status: “active”, “cancelled”, “expired”, “future”

Examples

-- List active subscriptions for a customer
local result = app.integrations.chartmogul.list_subscriptions({
  customer_uuid = "cus_abc123",
  status = "active"
})

for _, sub in ipairs(result.entries) do
  print(sub.plan .. " - " .. sub.state)
end

list_plans

List billing plans from ChartMogul.

Parameters

NameTypeRequiredDescription
per_pageintegernoNumber of results per page (default: 50, max: 200)
pageintegernoPage number, starting from 1 (default: 1)

Examples

local result = app.integrations.chartmogul.list_plans({
  per_page = 100
})

for _, plan in ipairs(result.plans) do
  print(plan.name .. " - " .. plan.amount .. " " .. plan.currency)
end

list_invoices

List invoices with optional filtering by customer.

Parameters

NameTypeRequiredDescription
per_pageintegernoNumber of results per page (default: 50, max: 200)
pageintegernoPage number, starting from 1 (default: 1)
customer_uuidstringnoFilter by customer UUID

Examples

-- List invoices for a specific customer
local result = app.integrations.chartmogul.list_invoices({
  customer_uuid = "cus_abc123",
  per_page = 10
})

for _, invoice in ipairs(result.entries) do
  print(invoice.external_id .. ": " .. invoice.amount .. " on " .. invoice.date)
end

get_metrics

Query subscription analytics metrics from ChartMogul.

Parameters

NameTypeRequiredDescription
start_datestringyesStart date (ISO 8601, e.g. “2025-01-01”)
end_datestringyesEnd date (ISO 8601, e.g. “2025-01-31”)
intervalstringnoGrouping interval: “day”, “week”, “month” (default: “month”)
typestringnoMetrics type: “absolute” or “percentage”

Examples

-- Monthly MRR over a quarter
local result = app.integrations.chartmogul.get_metrics({
  start_date = "2025-01-01",
  end_date = "2025-03-31",
  interval = "month"
})

for _, entry in ipairs(result.entries) do
  print(entry.date .. ": MRR = " .. entry.mrr .. ", ARR = " .. entry.arr)
end

-- Daily metrics
local result = app.integrations.chartmogul.get_metrics({
  start_date = "2025-03-01",
  end_date = "2025-03-31",
  interval = "day"
})

get_current_user

Get the currently authenticated ChartMogul user.

Parameters

None.

Examples

local result = app.integrations.chartmogul.get_current_user({})
print("Connected as: " .. result.first_name .. " " .. result.last_name .. " (" .. result.email .. ")")

Multi-Account Usage

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

-- Default account (always works)
app.integrations.chartmogul.function_name({...})

-- Explicit default (portable across setups)
app.integrations.chartmogul.default.function_name({...})

-- Named accounts
app.integrations.chartmogul.production.function_name({...})
app.integrations.chartmogul.staging.function_name({...})

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

Raw agent markdown 
# ChartMogul — Lua API Reference

## list_customers

List customers from ChartMogul with optional filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `per_page` | integer | no | Number of results per page (default: 50, max: 200) |
| `page` | integer | no | Page number, starting from 1 (default: 1) |
| `status` | string | no | Filter by customer status: "Active", "Cancelled", "Future" |
| `email` | string | no | Filter by customer email address |

### Examples

```lua
-- List all active customers
local result = app.integrations.chartmogul.list_customers({
  status = "Active",
  per_page = 50,
  page = 1
})

for _, customer in ipairs(result.entries) do
  print(customer.name .. " (" .. customer.email .. ")")
end

-- Search by email
local result = app.integrations.chartmogul.list_customers({
  email = "[email protected]"
})
```

---

## get_customer

Get details for a single ChartMogul customer by UUID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The ChartMogul customer UUID |

### Examples

```lua
local result = app.integrations.chartmogul.get_customer({
  id = "cus_abc123-def456"
})

print(result.name .. " - " .. result.status)
```

---

## list_subscriptions

List subscriptions with optional filtering by customer or status.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `per_page` | integer | no | Number of results per page (default: 50, max: 200) |
| `page` | integer | no | Page number, starting from 1 (default: 1) |
| `customer_uuid` | string | no | Filter by customer UUID |
| `status` | string | no | Filter by status: "active", "cancelled", "expired", "future" |

### Examples

```lua
-- List active subscriptions for a customer
local result = app.integrations.chartmogul.list_subscriptions({
  customer_uuid = "cus_abc123",
  status = "active"
})

for _, sub in ipairs(result.entries) do
  print(sub.plan .. " - " .. sub.state)
end
```

---

## list_plans

List billing plans from ChartMogul.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `per_page` | integer | no | Number of results per page (default: 50, max: 200) |
| `page` | integer | no | Page number, starting from 1 (default: 1) |

### Examples

```lua
local result = app.integrations.chartmogul.list_plans({
  per_page = 100
})

for _, plan in ipairs(result.plans) do
  print(plan.name .. " - " .. plan.amount .. " " .. plan.currency)
end
```

---

## list_invoices

List invoices with optional filtering by customer.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `per_page` | integer | no | Number of results per page (default: 50, max: 200) |
| `page` | integer | no | Page number, starting from 1 (default: 1) |
| `customer_uuid` | string | no | Filter by customer UUID |

### Examples

```lua
-- List invoices for a specific customer
local result = app.integrations.chartmogul.list_invoices({
  customer_uuid = "cus_abc123",
  per_page = 10
})

for _, invoice in ipairs(result.entries) do
  print(invoice.external_id .. ": " .. invoice.amount .. " on " .. invoice.date)
end
```

---

## get_metrics

Query subscription analytics metrics from ChartMogul.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `start_date` | string | yes | Start date (ISO 8601, e.g. "2025-01-01") |
| `end_date` | string | yes | End date (ISO 8601, e.g. "2025-01-31") |
| `interval` | string | no | Grouping interval: "day", "week", "month" (default: "month") |
| `type` | string | no | Metrics type: "absolute" or "percentage" |

### Examples

```lua
-- Monthly MRR over a quarter
local result = app.integrations.chartmogul.get_metrics({
  start_date = "2025-01-01",
  end_date = "2025-03-31",
  interval = "month"
})

for _, entry in ipairs(result.entries) do
  print(entry.date .. ": MRR = " .. entry.mrr .. ", ARR = " .. entry.arr)
end

-- Daily metrics
local result = app.integrations.chartmogul.get_metrics({
  start_date = "2025-03-01",
  end_date = "2025-03-31",
  interval = "day"
})
```

---

## get_current_user

Get the currently authenticated ChartMogul user.

### Parameters

None.

### Examples

```lua
local result = app.integrations.chartmogul.get_current_user({})
print("Connected as: " .. result.first_name .. " " .. result.last_name .. " (" .. result.email .. ")")
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.chartmogul.function_name({...})

-- Explicit default (portable across setups)
app.integrations.chartmogul.default.function_name({...})

-- Named accounts
app.integrations.chartmogul.production.function_name({...})
app.integrations.chartmogul.staging.function_name({...})
```

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

Metadata-Derived Lua Example

local result = app.integrations.chartmogul.chartmogul_list_customers({
  per_page = 1,
  page = 1,
  status = "example_status",
  email = "example_email"
})
print(result)

Functions

chartmogul_list_customers

List customers from ChartMogul. Supports filtering by status or email and pagination. Returns customer details including UUID, name, email, company, and status.

Operation
Read read
Full name
chartmogul.chartmogul_list_customers
ParameterTypeRequiredDescription
per_page integer no Number of results per page (default: 50, max: 200).
page integer no Page number, starting from 1 (default: 1).
status string no Filter by customer status. Common values: "Active", "Cancelled", "Future".
email string no Filter by customer email address.

chartmogul_get_customer

Get details for a single ChartMogul customer by UUID. Returns full customer information including attributes, address, and custom fields.

Operation
Read read
Full name
chartmogul.chartmogul_get_customer
ParameterTypeRequiredDescription
id string yes The ChartMogul customer UUID.

chartmogul_list_subscriptions

List subscriptions from ChartMogul. Supports filtering by customer UUID or status and pagination. Returns subscription details including plan, dates, and state.

Operation
Read read
Full name
chartmogul.chartmogul_list_subscriptions
ParameterTypeRequiredDescription
per_page integer no Number of results per page (default: 50, max: 200).
page integer no Page number, starting from 1 (default: 1).
customer_uuid string no Filter subscriptions by customer UUID.
status string no Filter by subscription status. Common values: "active", "cancelled", "expired", "future".

chartmogul_list_plans

List billing plans from ChartMogul. Returns plan details including name, interval, amount, and currency.

Operation
Read read
Full name
chartmogul.chartmogul_list_plans
ParameterTypeRequiredDescription
per_page integer no Number of results per page (default: 50, max: 200).
page integer no Page number, starting from 1 (default: 1).

chartmogul_list_invoices

List invoices from ChartMogul. Supports filtering by customer UUID and pagination. Returns invoice details including amount, dates, line items, and status.

Operation
Read read
Full name
chartmogul.chartmogul_list_invoices
ParameterTypeRequiredDescription
per_page integer no Number of results per page (default: 50, max: 200).
page integer no Page number, starting from 1 (default: 1).
customer_uuid string no Filter invoices by customer UUID.

chartmogul_get_metrics

Query subscription analytics metrics from ChartMogul. Returns key metrics like MRR, ARR, churn rate, customer count, and more. Specify a date range and interval for timeseries data.

Operation
Read read
Full name
chartmogul.chartmogul_get_metrics
ParameterTypeRequiredDescription
start_date string yes Start date for the metrics period (ISO 8601, e.g. "2025-01-01").
end_date string yes End date for the metrics period (ISO 8601, e.g. "2025-01-31").
interval string no Interval for grouping results: "day", "week", or "month" (default: "month").
type string no Type of metrics to return: "absolute" or "percentage". Omit for default.

chartmogul_get_current_user

Get the currently authenticated ChartMogul user. Returns user details including name, email, and account information. Useful for verifying API credentials.

Operation
Read read
Full name
chartmogul.chartmogul_get_current_user
ParameterTypeRequiredDescription
No parameters.