KosmoKrator

finance

QuickBooks Lua API for KosmoKrator Agents

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

7 functions 6 read 1 write Manual OAuth token auth
Submit QuickBooks feedback View package source

Lua Namespace

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

QuickBooks — Lua API Reference

list_invoices

List QuickBooks invoices with pagination.

Parameters

NameTypeRequiredDescription
limitintegernoMaximum number of invoices to return (default 10, max 1000)

Example

local result = app.integrations.quickbooks.list_invoices({
  limit = 10
})

for _, invoice in ipairs(result.invoices) do
  print(invoice.doc_number .. " - $" .. invoice.total_amt)
end

get_invoice

Retrieve a QuickBooks invoice by ID with full details.

Parameters

NameTypeRequiredDescription
invoice_idstringyesQuickBooks invoice ID

Example

local invoice = app.integrations.quickbooks.get_invoice({
  invoice_id = "42"
})

print("Invoice #" .. invoice.doc_number)
print("Total: $" .. invoice.total_amt)
print("Balance: $" .. invoice.balance)

create_invoice

Create a new QuickBooks invoice for a customer.

Parameters

NameTypeRequiredDescription
customer_idstringyesQuickBooks customer ID to bill
line_itemsarrayyesArray of line items. Each item should include DetailType, Amount, and SalesItemLineDetail with ItemRef
due_datestringnoDue date for the invoice in YYYY-MM-DD format

Example

local invoice = app.integrations.quickbooks.create_invoice({
  customer_id = "42",
  line_items = {
    {
      DetailType = "SalesItemLineDetail",
      Amount = 150.00,
      SalesItemLineDetail = { ItemRef = { value = "1" } }
    }
  },
  due_date = "2026-05-01"
})

print("Created invoice ID: " .. invoice.id)

list_customers

List QuickBooks customers with pagination.

Parameters

NameTypeRequiredDescription
limitintegernoMaximum number of customers to return (default 10, max 1000)

Example

local result = app.integrations.quickbooks.list_customers({
  limit = 10
})

for _, customer in ipairs(result.customers) do
  print(customer.display_name .. " - " .. (customer.email or "N/A"))
end

get_customer

Retrieve a QuickBooks customer by ID.

Parameters

NameTypeRequiredDescription
customer_idstringyesQuickBooks customer ID

Example

local customer = app.integrations.quickbooks.get_customer({
  customer_id = "42"
})

print(customer.display_name)
print("Email: " .. (customer.email or "N/A"))
print("Balance: $" .. customer.balance)

list_accounts

List QuickBooks accounts (chart of accounts).

Parameters

NameTypeRequiredDescription
limitintegernoMaximum number of accounts to return (default 10, max 1000)

Example

local result = app.integrations.quickbooks.list_accounts({
  limit = 20
})

for _, account in ipairs(result.accounts) do
  print(account.name .. " (" .. account.classification .. ") - $" .. account.current_balance)
end

get_current_user

Get current user / company info and verify API connection.

Parameters

None.

Example

local info = app.integrations.quickbooks.get_current_user({})
print("Connected to QuickBooks")

Multi-Account Usage

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

-- Default account (always works)
app.integrations.quickbooks.list_invoices({limit = 10})

-- Explicit default (portable across setups)
app.integrations.quickbooks.default.list_invoices({limit = 10})

-- Named accounts (e.g., different companies)
app.integrations.quickbooks.us_company.list_invoices({limit = 10})
app.integrations.quickbooks.uk_company.list_invoices({limit = 10})

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

Raw agent markdown 
# QuickBooks — Lua API Reference

## list_invoices

List QuickBooks invoices with pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Maximum number of invoices to return (default 10, max 1000) |

### Example

```lua
local result = app.integrations.quickbooks.list_invoices({
  limit = 10
})

for _, invoice in ipairs(result.invoices) do
  print(invoice.doc_number .. " - $" .. invoice.total_amt)
end
```

---

## get_invoice

Retrieve a QuickBooks invoice by ID with full details.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `invoice_id` | string | yes | QuickBooks invoice ID |

### Example

```lua
local invoice = app.integrations.quickbooks.get_invoice({
  invoice_id = "42"
})

print("Invoice #" .. invoice.doc_number)
print("Total: $" .. invoice.total_amt)
print("Balance: $" .. invoice.balance)
```

---

## create_invoice

Create a new QuickBooks invoice for a customer.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `customer_id` | string | yes | QuickBooks customer ID to bill |
| `line_items` | array | yes | Array of line items. Each item should include DetailType, Amount, and SalesItemLineDetail with ItemRef |
| `due_date` | string | no | Due date for the invoice in YYYY-MM-DD format |

### Example

```lua
local invoice = app.integrations.quickbooks.create_invoice({
  customer_id = "42",
  line_items = {
    {
      DetailType = "SalesItemLineDetail",
      Amount = 150.00,
      SalesItemLineDetail = { ItemRef = { value = "1" } }
    }
  },
  due_date = "2026-05-01"
})

print("Created invoice ID: " .. invoice.id)
```

---

## list_customers

List QuickBooks customers with pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Maximum number of customers to return (default 10, max 1000) |

### Example

```lua
local result = app.integrations.quickbooks.list_customers({
  limit = 10
})

for _, customer in ipairs(result.customers) do
  print(customer.display_name .. " - " .. (customer.email or "N/A"))
end
```

---

## get_customer

Retrieve a QuickBooks customer by ID.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `customer_id` | string | yes | QuickBooks customer ID |

### Example

```lua
local customer = app.integrations.quickbooks.get_customer({
  customer_id = "42"
})

print(customer.display_name)
print("Email: " .. (customer.email or "N/A"))
print("Balance: $" .. customer.balance)
```

---

## list_accounts

List QuickBooks accounts (chart of accounts).

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Maximum number of accounts to return (default 10, max 1000) |

### Example

```lua
local result = app.integrations.quickbooks.list_accounts({
  limit = 20
})

for _, account in ipairs(result.accounts) do
  print(account.name .. " (" .. account.classification .. ") - $" .. account.current_balance)
end
```

---

## get_current_user

Get current user / company info and verify API connection.

### Parameters

None.

### Example

```lua
local info = app.integrations.quickbooks.get_current_user({})
print("Connected to QuickBooks")
```

---

## Multi-Account Usage

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

```lua
-- Default account (always works)
app.integrations.quickbooks.list_invoices({limit = 10})

-- Explicit default (portable across setups)
app.integrations.quickbooks.default.list_invoices({limit = 10})

-- Named accounts (e.g., different companies)
app.integrations.quickbooks.us_company.list_invoices({limit = 10})
app.integrations.quickbooks.uk_company.list_invoices({limit = 10})
```

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

Metadata-Derived Lua Example

local result = app.integrations.quickbooks.quickbooks_list_invoices({
  limit = 1
})
print(result)

Functions

quickbooks_list_invoices

List QuickBooks invoices. Returns a list of invoices with key fields. Use the limit parameter to control page size.

Operation
Read read
Full name
quickbooks.quickbooks_list_invoices
ParameterTypeRequiredDescription
limit integer no Maximum number of invoices to return (default 10, max 1000).

quickbooks_get_invoice

Retrieve a QuickBooks invoice by ID. Returns full invoice details including line items, totals, balance, and status.

Operation
Read read
Full name
quickbooks.quickbooks_get_invoice
ParameterTypeRequiredDescription
invoice_id string yes QuickBooks invoice ID.

quickbooks_create_invoice

Create a new QuickBooks invoice for a customer. Provide customer_id, line_items (array of items with DetailType, Amount, and SalesItemLineDetail), and an optional due_date.

Operation
Write write
Full name
quickbooks.quickbooks_create_invoice
ParameterTypeRequiredDescription
customer_id string yes QuickBooks customer ID to bill.
line_items object yes Array of line items. Each item should include DetailType, Amount, and SalesItemLineDetail with ItemRef.
due_date string no Due date for the invoice in YYYY-MM-DD format.

quickbooks_list_customers

List QuickBooks customers. Returns a list of customers with key fields. Use the limit parameter to control page size.

Operation
Read read
Full name
quickbooks.quickbooks_list_customers
ParameterTypeRequiredDescription
limit integer no Maximum number of customers to return (default 10, max 1000).

quickbooks_get_customer

Retrieve a QuickBooks customer by ID. Returns full customer details including name, email, phone, and balance.

Operation
Read read
Full name
quickbooks.quickbooks_get_customer
ParameterTypeRequiredDescription
customer_id string yes QuickBooks customer ID.

quickbooks_list_accounts

List QuickBooks accounts (chart of accounts). Returns a list of accounts with name, type, classification, and balance. Use the limit parameter to control page size.

Operation
Read read
Full name
quickbooks.quickbooks_list_accounts
ParameterTypeRequiredDescription
limit integer no Maximum number of accounts to return (default 10, max 1000).

quickbooks_get_current_user

Get the current user / company info from QuickBooks. Use this to verify the API connection is working.

Operation
Read read
Full name
quickbooks.quickbooks_get_current_user
ParameterTypeRequiredDescription
No parameters.