KosmoKrator

sales

Shopify Lua API for KosmoKrator Agents

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

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

Lua Namespace

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

Shopify — Lua API Reference

list_products

List products from the Shopify store with filtering and pagination.

Parameters

NameTypeRequiredDescription
limitintegernoNumber of products per page (default: 50, max: 250)
statusstringnoFilter by status: “active”, “draft”, or “archived”
product_typestringnoFilter by product type
vendorstringnoFilter by vendor name
collection_idstringnoFilter by collection ID
page_infostringnoCursor for pagination (from a previous response)

Example

local result = app.integrations.shopify.list_products({
  limit = 10,
  status = "active",
  sort = "price",
  direction = "desc"
})

for _, product in ipairs(result) do
  print(product.title .. " - $" .. product.price)
end

get_product

Get a single product by ID with full details.

Parameters

NameTypeRequiredDescription
idstringyesThe product ID

Example

local product = app.integrations.shopify.get_product({
  id = "1234567890"
})

print(product.title)
print("Price: $" .. product.price)
print("SKU: " .. (product.sku or "N/A"))

create_product

Create a new product in the Shopify store.

Parameters

NameTypeRequiredDescription
titlestringyesProduct title
body_htmlstringnoProduct description (HTML allowed)
vendorstringnoProduct vendor
product_typestringnoProduct type (e.g., “Shirts”, “Electronics”)
statusstringnoProduct status: “active”, “draft”, or “archived”
tagsstringnoComma-separated tags (e.g., “cotton, summer”)
publishedbooleannoWhether the product is published (default: true)

Example

local product = app.integrations.shopify.create_product({
  title = "Premium Widget",
  body_html = "<p>A premium quality widget.</p>",
  vendor = "Acme Corp",
  product_type = "Widgets",
  status = "active",
  tags = "premium, new"
})

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

list_orders

List orders with filtering and pagination.

Parameters

NameTypeRequiredDescription
limitintegernoOrders per page (default: 50, max: 250)
statusstringnoFilter by status: “open”, “closed”, “cancelled”, or “any”
financial_statusstringnoFilter by financial status: “pending”, “paid”, “partially_paid”, “refunded”, “voided”
fulfillment_statusstringnoFilter by fulfillment status: “shipped”, “partial”, “unshipped”, “any”
page_infostringnoCursor for pagination (from a previous response)

Example

local orders = app.integrations.shopify.list_orders({
  status = "open",
  financial_status = "paid",
  fulfillment_status = "unshipped",
  limit = 10
})

for _, order in ipairs(orders) do
  print("Order #" .. order.name .. " - $" .. order.total_price)
end

get_order

Get a single order by ID.

Parameters

NameTypeRequiredDescription
idstringyesThe order ID

Example

local order = app.integrations.shopify.get_order({
  id = "5678901234"
})

print("Order: " .. order.name)
print("Status: " .. order.financial_status)
print("Total: $" .. order.total_price)

list_customers

List customers with filtering and pagination.

Parameters

NameTypeRequiredDescription
limitintegernoCustomers per page (default: 50, max: 250)
emailstringnoFilter by email address
tagstringnoFilter by customer tag
page_infostringnoCursor for pagination (from a previous response)

Example

local customers = app.integrations.shopify.list_customers({
  limit = 10
})

for _, customer in ipairs(customers) do
  print(customer.first_name .. " " .. customer.last_name .. " - " .. customer.email)
end

get_current_user

Get shop info and verify the API connection.

Parameters

None.

Example

local shop = app.integrations.shopify.get_current_user({})

print("Store: " .. shop.name)

Multi-Account Usage

If you have multiple Shopify stores configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.shopify.list_products({limit = 10})

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

-- Named accounts (e.g., different stores)
app.integrations.shopify.us_store.list_products({limit = 10})
app.integrations.shopify.eu_store.list_products({limit = 10})

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

Raw agent markdown 
# Shopify — Lua API Reference

## list_products

List products from the Shopify store with filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Number of products per page (default: 50, max: 250) |
| `status` | string | no | Filter by status: "active", "draft", or "archived" |
| `product_type` | string | no | Filter by product type |
| `vendor` | string | no | Filter by vendor name |
| `collection_id` | string | no | Filter by collection ID |
| `page_info` | string | no | Cursor for pagination (from a previous response) |

### Example

```lua
local result = app.integrations.shopify.list_products({
  limit = 10,
  status = "active",
  sort = "price",
  direction = "desc"
})

for _, product in ipairs(result) do
  print(product.title .. " - $" .. product.price)
end
```

---

## get_product

Get a single product by ID with full details.

### Parameters

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

### Example

```lua
local product = app.integrations.shopify.get_product({
  id = "1234567890"
})

print(product.title)
print("Price: $" .. product.price)
print("SKU: " .. (product.sku or "N/A"))
```

---

## create_product

Create a new product in the Shopify store.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `title` | string | yes | Product title |
| `body_html` | string | no | Product description (HTML allowed) |
| `vendor` | string | no | Product vendor |
| `product_type` | string | no | Product type (e.g., "Shirts", "Electronics") |
| `status` | string | no | Product status: "active", "draft", or "archived" |
| `tags` | string | no | Comma-separated tags (e.g., "cotton, summer") |
| `published` | boolean | no | Whether the product is published (default: true) |

### Example

```lua
local product = app.integrations.shopify.create_product({
  title = "Premium Widget",
  body_html = "<p>A premium quality widget.</p>",
  vendor = "Acme Corp",
  product_type = "Widgets",
  status = "active",
  tags = "premium, new"
})

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

---

## list_orders

List orders with filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Orders per page (default: 50, max: 250) |
| `status` | string | no | Filter by status: "open", "closed", "cancelled", or "any" |
| `financial_status` | string | no | Filter by financial status: "pending", "paid", "partially_paid", "refunded", "voided" |
| `fulfillment_status` | string | no | Filter by fulfillment status: "shipped", "partial", "unshipped", "any" |
| `page_info` | string | no | Cursor for pagination (from a previous response) |

### Example

```lua
local orders = app.integrations.shopify.list_orders({
  status = "open",
  financial_status = "paid",
  fulfillment_status = "unshipped",
  limit = 10
})

for _, order in ipairs(orders) do
  print("Order #" .. order.name .. " - $" .. order.total_price)
end
```

---

## get_order

Get a single order by ID.

### Parameters

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

### Example

```lua
local order = app.integrations.shopify.get_order({
  id = "5678901234"
})

print("Order: " .. order.name)
print("Status: " .. order.financial_status)
print("Total: $" .. order.total_price)
```

---

## list_customers

List customers with filtering and pagination.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `limit` | integer | no | Customers per page (default: 50, max: 250) |
| `email` | string | no | Filter by email address |
| `tag` | string | no | Filter by customer tag |
| `page_info` | string | no | Cursor for pagination (from a previous response) |

### Example

```lua
local customers = app.integrations.shopify.list_customers({
  limit = 10
})

for _, customer in ipairs(customers) do
  print(customer.first_name .. " " .. customer.last_name .. " - " .. customer.email)
end
```

---

## get_current_user

Get shop info and verify the API connection.

### Parameters

None.

### Example

```lua
local shop = app.integrations.shopify.get_current_user({})

print("Store: " .. shop.name)
```

---

## Multi-Account Usage

If you have multiple Shopify stores configured, use account-specific namespaces:

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

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

-- Named accounts (e.g., different stores)
app.integrations.shopify.us_store.list_products({limit = 10})
app.integrations.shopify.eu_store.list_products({limit = 10})
```

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

Metadata-Derived Lua Example

local result = app.integrations.shopify.shopify_list_products({
  limit = 1,
  status = "example_status",
  product_type = "example_product_type",
  vendor = "example_vendor",
  collection_id = "example_collection_id",
  page_info = "example_page_info"
})
print(result)

Functions

shopify_list_products

List products from the Shopify store. Supports filtering by status, product type, vendor, and pagination.

Operation
Read read
Full name
shopify.shopify_list_products
ParameterTypeRequiredDescription
limit integer no Number of products to return per page (default: 50, max: 250).
status string no Filter by status: "active", "draft", or "archived".
product_type string no Filter by product type.
vendor string no Filter by vendor name.
collection_id string no Filter by collection ID.
page_info string no Cursor for pagination (from a previous response).

shopify_get_product

Get a single product from the Shopify store by its ID. Returns full product details.

Operation
Read read
Full name
shopify.shopify_get_product
ParameterTypeRequiredDescription
id string yes The product ID.

shopify_create_product

Create a new product in the Shopify store. Requires a title. Supports description, vendor, product type, tags, and status.

Operation
Write write
Full name
shopify.shopify_create_product
ParameterTypeRequiredDescription
title string yes Product title.
body_html string no Product description (HTML allowed).
vendor string no Product vendor.
product_type string no Product type (e.g., "Shirts", "Electronics").
status string no Product status: "active", "draft", or "archived".
tags string no Comma-separated tags (e.g., "cotton, summer").
published boolean no Whether the product is published (default: true).

shopify_list_orders

List orders from the Shopify store. Supports filtering by status, financial status, fulfillment status, and pagination.

Operation
Read read
Full name
shopify.shopify_list_orders
ParameterTypeRequiredDescription
limit integer no Number of orders per page (default: 50, max: 250).
status string no Filter by order status: "open", "closed", "cancelled", or "any".
financial_status string no Filter by financial status: "pending", "paid", "partially_paid", "refunded", "voided".
fulfillment_status string no Filter by fulfillment status: "shipped", "partial", "unshipped", "any".
page_info string no Cursor for pagination (from a previous response).

shopify_get_order

Get a single order from the Shopify store by its ID. Returns full order details including line items and totals.

Operation
Read read
Full name
shopify.shopify_get_order
ParameterTypeRequiredDescription
id string yes The order ID.

shopify_list_customers

List customers from the Shopify store. Supports filtering by email or tag and pagination.

Operation
Read read
Full name
shopify.shopify_list_customers
ParameterTypeRequiredDescription
limit integer no Number of customers per page (default: 50, max: 250).
email string no Filter by customer email address.
tag string no Filter by customer tag.
page_info string no Cursor for pagination (from a previous response).

shopify_get_current_user

Get the current shop info from Shopify. Use this to verify the API connection is working.

Operation
Read read
Full name
shopify.shopify_get_current_user
ParameterTypeRequiredDescription
No parameters.