KosmoKrator

productivity

TaxJar Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.taxjar.*. Use lua_read_doc("integrations.taxjar") 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 TaxJar workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.taxjar.list_orders({from_date = "example_from_date", to_date = "example_to_date", limit = 1, offset = 1}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("taxjar"))' --json
kosmo integrations:lua --eval 'print(docs.read("taxjar.list_orders"))' --json

Workflow file

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

workflow.lua 
local taxjar = app.integrations.taxjar
local result = taxjar.list_orders({from_date = "example_from_date", to_date = "example_to_date", limit = 1, offset = 1})

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.taxjar, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.taxjar.default.* or app.integrations.taxjar.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need TaxJar, 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.

TaxJar — Lua API Reference

list_orders

List order transactions from TaxJar with optional date filtering and pagination.

Parameters

NameTypeRequiredDescription
from_datestringnoFilter by start date (ISO 8601 format, e.g. 2024-01-01)
to_datestringnoFilter by end date (ISO 8601 format, e.g. 2024-12-31)
limitintegernoNumber of results per page
offsetintegernoOffset for pagination

Example

local result = app.integrations.taxjar.list_orders({
  from_date = "2024-01-01",
  to_date = "2024-12-31",
  limit = 50
})

for _, order in ipairs(result.orders) do
  print(order.transaction_id .. " — " .. order.amount .. " — " .. order.transaction_date)
end

get_order

Retrieve details of a single order transaction.

Parameters

NameTypeRequiredDescription
idstringyesThe order transaction ID

Example

local result = app.integrations.taxjar.get_order({
  id = "ORDER-123"
})

local order = result.order
print("Amount: " .. order.amount)
print("Tax: " .. order.tax)
print("Shipping: " .. (order.shipping or "N/A"))

list_refunds

List refund transactions from TaxJar with optional date filtering and pagination.

Parameters

NameTypeRequiredDescription
from_datestringnoFilter by start date (ISO 8601 format, e.g. 2024-01-01)
to_datestringnoFilter by end date (ISO 8601 format, e.g. 2024-12-31)
limitintegernoNumber of results per page
offsetintegernoOffset for pagination

Example

local result = app.integrations.taxjar.list_refunds({
  from_date = "2024-01-01",
  limit = 25
})

for _, refund in ipairs(result.refunds) do
  print(refund.transaction_id .. " — " .. refund.amount .. " — " .. refund.transaction_date)
end

list_transactions

List all transactions (orders and refunds) from TaxJar with optional filtering and pagination.

Parameters

NameTypeRequiredDescription
from_datestringnoFilter by start date (ISO 8601 format, e.g. 2024-01-01)
to_datestringnoFilter by end date (ISO 8601 format, e.g. 2024-12-31)
limitintegernoNumber of results per page
offsetintegernoOffset for pagination

Example

local result = app.integrations.taxjar.list_transactions({
  from_date = "2024-06-01",
  to_date = "2024-06-30"
})

for _, txn in ipairs(result.transactions) do
  print(txn.transaction_id .. " — " .. txn.amount .. " — " .. txn.transaction_date)
end

get_transaction

Retrieve details of a single transaction by ID.

Parameters

NameTypeRequiredDescription
idstringyesThe transaction ID

Example

local result = app.integrations.taxjar.get_transaction({
  id = "TXN-456"
})

local txn = result.transaction
print("Amount: " .. txn.amount)
print("Tax: " .. txn.tax)
print("Line items: " .. #(txn.line_items or {}))

list_categories

List all tax categories available in TaxJar.

Parameters

None.

Example

local result = app.integrations.taxjar.list_categories({})

for _, cat in ipairs(result.categories) do
  print(cat.name .. " — " .. cat.product_tax_code .. " — " .. (cat.description or ""))
end

get_current_user

Retrieve the current authenticated user information.

Parameters

None.

Example

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

print("User: " .. (result.user and result.user.email or "N/A"))

Multi-Account Usage

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

-- Default account (always works)
app.integrations.taxjar.list_orders({from_date = "2024-01-01"})

-- Explicit default (portable across setups)
app.integrations.taxjar.default.list_orders({from_date = "2024-01-01"})

-- Named accounts
app.integrations.taxjar.production.list_orders({from_date = "2024-01-01"})
app.integrations.taxjar.staging.list_orders({from_date = "2024-01-01"})

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

Raw agent markdown 
# TaxJar — Lua API Reference

## list_orders

List order transactions from TaxJar with optional date filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from_date` | string | no | Filter by start date (ISO 8601 format, e.g. 2024-01-01) |
| `to_date` | string | no | Filter by end date (ISO 8601 format, e.g. 2024-12-31) |
| `limit` | integer | no | Number of results per page |
| `offset` | integer | no | Offset for pagination |

### Example

```lua
local result = app.integrations.taxjar.list_orders({
  from_date = "2024-01-01",
  to_date = "2024-12-31",
  limit = 50
})

for _, order in ipairs(result.orders) do
  print(order.transaction_id .. " — " .. order.amount .. " — " .. order.transaction_date)
end
```

---

## get_order

Retrieve details of a single order transaction.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The order transaction ID |

### Example

```lua
local result = app.integrations.taxjar.get_order({
  id = "ORDER-123"
})

local order = result.order
print("Amount: " .. order.amount)
print("Tax: " .. order.tax)
print("Shipping: " .. (order.shipping or "N/A"))
```

---

## list_refunds

List refund transactions from TaxJar with optional date filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from_date` | string | no | Filter by start date (ISO 8601 format, e.g. 2024-01-01) |
| `to_date` | string | no | Filter by end date (ISO 8601 format, e.g. 2024-12-31) |
| `limit` | integer | no | Number of results per page |
| `offset` | integer | no | Offset for pagination |

### Example

```lua
local result = app.integrations.taxjar.list_refunds({
  from_date = "2024-01-01",
  limit = 25
})

for _, refund in ipairs(result.refunds) do
  print(refund.transaction_id .. " — " .. refund.amount .. " — " .. refund.transaction_date)
end
```

---

## list_transactions

List all transactions (orders and refunds) from TaxJar with optional filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `from_date` | string | no | Filter by start date (ISO 8601 format, e.g. 2024-01-01) |
| `to_date` | string | no | Filter by end date (ISO 8601 format, e.g. 2024-12-31) |
| `limit` | integer | no | Number of results per page |
| `offset` | integer | no | Offset for pagination |

### Example

```lua
local result = app.integrations.taxjar.list_transactions({
  from_date = "2024-06-01",
  to_date = "2024-06-30"
})

for _, txn in ipairs(result.transactions) do
  print(txn.transaction_id .. " — " .. txn.amount .. " — " .. txn.transaction_date)
end
```

---

## get_transaction

Retrieve details of a single transaction by ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | yes | The transaction ID |

### Example

```lua
local result = app.integrations.taxjar.get_transaction({
  id = "TXN-456"
})

local txn = result.transaction
print("Amount: " .. txn.amount)
print("Tax: " .. txn.tax)
print("Line items: " .. #(txn.line_items or {}))
```

---

## list_categories

List all tax categories available in TaxJar.

### Parameters

None.

### Example

```lua
local result = app.integrations.taxjar.list_categories({})

for _, cat in ipairs(result.categories) do
  print(cat.name .. " — " .. cat.product_tax_code .. " — " .. (cat.description or ""))
end
```

---

## get_current_user

Retrieve the current authenticated user information.

### Parameters

None.

### Example

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

print("User: " .. (result.user and result.user.email or "N/A"))
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.taxjar.list_orders({from_date = "2024-01-01"})

-- Explicit default (portable across setups)
app.integrations.taxjar.default.list_orders({from_date = "2024-01-01"})

-- Named accounts
app.integrations.taxjar.production.list_orders({from_date = "2024-01-01"})
app.integrations.taxjar.staging.list_orders({from_date = "2024-01-01"})
```

All functions are identical across accounts — only the credentials differ.
Metadata-derived Lua example 
local result = app.integrations.taxjar.list_orders({from_date = "example_from_date", to_date = "example_to_date", limit = 1, offset = 1})
print(result)

Functions

list_orders Read

List order transactions from TaxJar with optional date filtering and pagination. Returns order details including transaction ID, amount, tax, and date.

Lua path
app.integrations.taxjar.list_orders
Full name
taxjar.taxjar_list_orders
ParameterTypeRequiredDescription
from_date string no Filter by start date (ISO 8601 format, e.g. 2024-01-01).
to_date string no Filter by end date (ISO 8601 format, e.g. 2024-12-31).
limit integer no Number of results per page.
offset integer no Offset for pagination.
get_order Read

Retrieve detailed information about a specific TaxJar order transaction by its ID, including amount, tax, shipping, line items, and addresses.

Lua path
app.integrations.taxjar.get_order
Full name
taxjar.taxjar_get_order
ParameterTypeRequiredDescription
id string yes The order transaction ID.
list_refunds Read

List refund transactions from TaxJar with optional date filtering and pagination. Returns refund details including transaction ID, amount, tax, and date.

Lua path
app.integrations.taxjar.list_refunds
Full name
taxjar.taxjar_list_refunds
ParameterTypeRequiredDescription
from_date string no Filter by start date (ISO 8601 format, e.g. 2024-01-01).
to_date string no Filter by end date (ISO 8601 format, e.g. 2024-12-31).
limit integer no Number of results per page.
offset integer no Offset for pagination.
list_transactions Read

List all transactions (orders and refunds) from TaxJar with optional date filtering and pagination. Returns transaction details including ID, amount, tax, date, and type.

Lua path
app.integrations.taxjar.list_transactions
Full name
taxjar.taxjar_list_transactions
ParameterTypeRequiredDescription
from_date string no Filter by start date (ISO 8601 format, e.g. 2024-01-01).
to_date string no Filter by end date (ISO 8601 format, e.g. 2024-12-31).
limit integer no Number of results per page.
offset integer no Offset for pagination.
get_transaction Read

Retrieve detailed information about a specific TaxJar transaction by its ID, including amount, tax, shipping, line items, and addresses.

Lua path
app.integrations.taxjar.get_transaction
Full name
taxjar.taxjar_get_transaction
ParameterTypeRequiredDescription
id string yes The transaction ID.
list_categories Read

List all tax categories available in TaxJar. Returns category details including name, product tax code, and description.

Lua path
app.integrations.taxjar.list_categories
Full name
taxjar.taxjar_list_categories
ParameterTypeRequiredDescription
No parameters.
get_current_user Read

Retrieve the current authenticated user information from TaxJar. Use this to verify credentials are working and check user details.

Lua path
app.integrations.taxjar.get_current_user
Full name
taxjar.taxjar_get_current_user
ParameterTypeRequiredDescription
No parameters.