Shop

Shop helpers are useful in shop item actions and commands that need to reference the configured item or previous purchases.

Read a shop item

Use shop.item(itemId) when a response needs the configured shop item name, price, description, custom fields, or action settings. The item ID is the item's id in Kicklet. In the dashboard, open the item under Shop > Items; the ID is the :itemId part of the item detail URL and is also the id returned by the shop item API.

shop.item(itemId) can only read shop items owned by the current Kicklet account. Kicklet checks the current account together with the item ID in the backend.

Engine v2

Reads a shop item owned by the current Kicklet account.

API reference

shop.item

shop.item(itemId)

Input

itemId

number

Shop item ID.

Output

object

Shop item object.

This example reads item 123 and uses its configured name and price.

Shop item nameAdvanced Script

const item = shop.item(123);
const currency = points.currency();

async.messages.send(`Shop item ${item.id}: ${item.name} costs ${item.price} ${currency}.`);

The returned object has this shape:

{
  "id": 123,
  "active": true,
  "createdAt": "2026-05-08T11:43:14Z",
  "price": 250,
  "name": "VIP Highlight",
  "description": "A highlighted chat reward for docs examples.",
  "image": "https://example.com/shop/vip-highlight.png",
  "stock": 10,
  "isOrder": true,
  "command": "!highlight",
  "globalPeriod": 300000000000,
  "userPeriod": 1800000000000,
  "actionDuration": 30,
  "actionVolume": 60,
  "customFields": ["message"],
  "actions": [
    {
      "actionId": "chat-message",
      "actionValue": "Thanks for the purchase!"
    }
  ],
  "position": 1
}

Engine v1

Engine v1 does not provide a direct helper for reading the full shop item object.

Count shop purchases

Use this in shop code actions when a reward should behave differently after a viewer has bought the same item before.

Engine v2

Returns how often one viewer bought a specific shop item.

API reference

shop.countCustomerSales

shop.countCustomerSales(itemId, customerUsername, options?)

Input

itemId

number

Shop item ID.

customerUsername

string

Viewer username.

optionsoptional

object

Optional count filter.

deliveredoptional

boolean

When true, only delivered sales are counted.

Output

number

Matching purchase count.

shop.countCustomerSales(itemId, customerUsername, options) returns how often one viewer bought a specific shop item. The first argument is the shop item ID. The second argument is the viewer username. Pass {delivered: true} when only purchases already marked as delivered should count.

This example checks item 123 for the current sender and only counts delivered sales.

Count shop purchasesAdvanced Script

const itemId = 123;
const item = shop.item(itemId);
const count = shop.countCustomerSales(itemId, sender.username, { delivered: true });
async.messages.send(`${sender.username} has received ${item.name} ${count} time(s).`);

Engine v1

Engine v1 response example:

{{sender.String}} has received item 123 {{kicklet.ShopCountItemCustomerSales 123 sender.String}} time(s).

Async shop wrappers

Engine v2

Async wrapper for shop.item(itemId).

API reference

async.shop.item

async.shop.item(itemId)

Input

itemId

number

Shop item ID.

Output

object

Shop item object.

Async wrapper for shop.countCustomerSales(itemId, customerUsername, options?).

API reference

async.shop.countCustomerSales

async.shop.countCustomerSales(itemId, customerUsername, options?)

Input

itemId

number

Shop item ID.

customerUsername

string

Viewer username.

optionsoptional

object

Optional count filter.

deliveredoptional

boolean

When true, only delivered sales are counted.

Output

number

Matching purchase count.

Engine v1

Engine v1 does not provide async shop helper wrappers.