Store API

The Store API provides a powerful interface for managing server-specific stores with customizable items, categories, and reward systems.

✨ Features

• Per-server stores — Each guild has its own store

• Multiple categories — Pets, roles, boosters, titles, items, special

• Reward types — Pets, roles, boosters, titles, items, custom

• Requirements — Level and prestige requirements

• Stock management — Limited or unlimited stock

• Purchase limits — Max purchases per user

• Transaction logging — Full purchase history

🚀 Quick Start

The Store API is available globally as global.storeAPI — no require needed.

quick-start.js

// Add a custom item
await global.storeAPI.addItem(guildId, {
    name: 'VIP Role',
    category: 'roles',
    price: 50000,
    rewardType: 'role',
    rewardData: { roleId: '123456789', roleDuration: null },
    emoji: '👑'
});

// Get all items in a category
const pets = await global.storeAPI.getItems(guildId, 'pets');

// Purchase an item for a user
const result = await global.storeAPI.purchaseItem(guildId, userId, itemId);
if (result.success) {
    console.log(`Purchased: ${result.item.name}`);
}

📦 Methods Reference

addItem(guildId, itemData)

Add a new item to the store.

addItem example

await global.storeAPI.addItem(guildId, {
    name: 'Dragon Pet',
    description: 'A legendary beast',
    category: 'pets',           // pets, roles, boosters, titles, items, special
    price: 50000,
    stock: -1,                  // -1 = unlimited
    maxPerUser: 1,              // -1 = unlimited
    enabled: true,
    rewardType: 'pet',
    rewardData: {
        petType: 'Dragon',
        petMultiplier: 1.15,
        petPassiveIncome: 100
    },
    requirements: {
        level: 10,
        prestige: 0
    },
    emoji: '🐉',
    color: '#FF4500',
    featured: true,
    sortOrder: 1
});

removeItem(guildId, itemId)

Remove an item from the store.

removeItem example

const removed = await global.storeAPI.removeItem(guildId, 'item-uuid');
// Returns: true if deleted, false if not found

updateItem(guildId, itemId, updates)

Update an existing item.

updateItem example

await global.storeAPI.updateItem(guildId, 'item-uuid', {
    price: 75000,
    'metadata.featured': true,
    enabled: false
});

getItem(guildId, itemId)

Get a single item by ID.

getItem example

const item = await global.storeAPI.getItem(guildId, 'item-uuid');

getItems(guildId, category?)

Get all items, optionally filtered by category.

getItems examples

// All items
const allItems = await global.storeAPI.getItems(guildId);

// Only pets
const pets = await global.storeAPI.getItems(guildId, 'pets');

// Only boosters
const boosters = await global.storeAPI.getItems(guildId, 'boosters');

getCategories(guildId)

Get all categories that have items.

getCategories example

const categories = await global.storeAPI.getCategories(guildId);
// Returns: ['pets', 'boosters', 'titles']

getFeaturedItems(guildId)

Get all featured items.

getFeaturedItems example

const featured = await global.storeAPI.getFeaturedItems(guildId);

purchaseItem(guildId, userId, itemId, client?)

Process a purchase. Handles balance deduction, requirements validation, stock management, and reward application.

The client parameter is optional — if not provided, the API uses the client from its context.

purchaseItem example

const result = await global.storeAPI.purchaseItem(guildId, userId, itemId);

if (result.success) {
    console.log(result.item);     // The purchased item
    console.log(result.purchase); // Purchase record
    console.log(result.reward);   // Reward message string
} else {
    console.log(result.error);    // Error message
}

Possible errors:

• Item not found

• Item out of stock

• User not found

• Insufficient funds

• Requires level X

• Requires prestige X

• Purchase limit reached

• You already own this pet!

getUserPurchases(guildId, userId)

Get a user's purchase history.

getUserPurchases example

const purchases = await global.storeAPI.getUserPurchases(guildId, userId);
// Returns array of purchase records sorted by date (newest first)

🎁 Reward Types

pet

Adds a pet to the user's collection.

pet reward example

rewardType: 'pet',
rewardData: {
    petType: 'Dragon',        // Pet type name
    petMultiplier: 1.15,      // Earnings multiplier (1.15 = +15%)
    petPassiveIncome: 100     // Coins per hour passive income
}

role

Grants a Discord role to the user.

role reward example

rewardType: 'role',
rewardData: {
    roleId: '123456789012345678',  // Discord role ID
    roleDuration: 2592000000       // Duration in ms (null = permanent)
}

booster

Activates a temporary multiplier booster.

booster reward example

rewardType: 'booster',
rewardData: {
    boosterType: 'Money',       // 'Money' or 'XP'
    boosterMultiplier: 1.5,     // 1.5 = +50% bonus
    boosterDuration: 86400000   // Duration in ms (24 hours)
}

title

Unlocks a display title for the user.

title reward example

rewardType: 'title',
rewardData: {
    title: '💰 Rich'   // The title string
}

item

Adds a generic item to user's inventory.

item reward example

rewardType: 'item',
rewardData: {
    itemType: 'charm',           // Custom item type
    itemData: { luckBonus: 0.05 } // Custom data
}

custom

For addon-handled rewards. The reward isn't automatically applied.

custom reward example

rewardType: 'custom',
rewardData: {
    // Your custom data here
}

📁 Categories

Category	Description
pets	Virtual companions with bonuses
roles	Discord roles (temporary or permanent)
boosters	Temporary multiplier effects
titles	Display titles for users
items	Generic inventory items
special	Limited edition or seasonal items

💡 Addon Examples

Adding Custom Shop Items

CustomShopItems.js

module.exports = {
    name: 'CustomShopItems',
    
    async run(client) {
        for (const guild of client.guilds.cache.values()) {
            const existing = await global.storeAPI.getItem(guild.id, 'vip-membership');
            if (existing) continue;
            
            await global.storeAPI.addItem(guild.id, {
                itemId: 'vip-membership',
                name: 'VIP Membership',
                description: 'Get exclusive VIP role for 30 days',
                category: 'roles',
                price: 100000,
                maxPerUser: 1,
                rewardType: 'role',
                rewardData: {
                    roleId: 'YOUR_VIP_ROLE_ID',
                    roleDuration: 2592000000  // 30 days
                },
                emoji: '💎',
                featured: true
            });
            
            console.log(`Added VIP item to ${guild.name}`);
        }
    }
};

Seasonal/Limited Items

SeasonalStore.js

module.exports = {
    name: 'SeasonalStore',
    
    async run(client) {
        const month = new Date().getMonth();
        
        // December = Christmas items
        if (month === 11) {
            for (const guild of client.guilds.cache.values()) {
                const existing = await global.storeAPI.getItem(guild.id, 'santa-hat-2024');
                if (existing) continue;
                
                await global.storeAPI.addItem(guild.id, {
                    itemId: 'santa-hat-2024',
                    name: 'Santa Hat 2024',
                    description: 'Limited edition holiday item!',
                    category: 'special',
                    price: 25000,
                    stock: 100,  // Only 100 available!
                    rewardType: 'title',
                    rewardData: { title: '🎅 Santa 2024' },
                    emoji: '🎄',
                    featured: true
                });
            }
        }
    }
};

Dynamic Pricing

DynamicPricing.js

module.exports = {
    name: 'DynamicPricing',
    
    events: {
        'discord:ready': async (eventData, context) => {
            // Update prices every hour based on purchases
            setInterval(async () => {
                for (const guild of context.client.guilds.cache.values()) {
                    const items = await global.storeAPI.getItems(guild.id, 'pets');
                    
                    for (const item of items) {
                        // Increase price if stock is running low
                        if (item.stock > 0 && item.stock < 10) {
                            await global.storeAPI.updateItem(guild.id, item.itemId, {
                                price: Math.floor(item.price * 1.1)
                            });
                        }
                    }
                }
            }, 3600000); // Every hour
        }
    }
};

Purchase Announcements

PurchaseAnnouncer.js

module.exports = {
    name: 'PurchaseAnnouncer',
    
    async run(client) {
        const originalPurchase = global.storeAPI.purchaseItem.bind(global.storeAPI);
        
        global.storeAPI.purchaseItem = async (guildId, userId, itemId, c) => {
            const result = await originalPurchase(guildId, userId, itemId, c);
            
            if (result.success && result.item.metadata?.featured) {
                const guild = client.guilds.cache.get(guildId);
                const channel = guild?.channels.cache.find(
                    ch => ch.name === 'purchases' || ch.name === 'general'
                );
                
                if (channel) {
                    const user = await client.users.fetch(userId);
                    await channel.send(
                        `🎉 **${user.username}** just purchased **${result.item.name}**!`
                    );
                }
            }
            
            return result;
        };
    }
};

📊 Item Schema

Full item object structure:

Item Schema

{
    itemId: 'uuid-string',
    guildId: 'guild-id',
    name: 'Item Name',
    description: 'Item description',
    category: 'pets',
    price: 50000,
    stock: -1,
    maxPerUser: -1,
    enabled: true,
    rewardType: 'pet',
    rewardData: { ... },
    requirements: {
        level: 0,
        prestige: 0
    },
    metadata: {
        emoji: '🐉',
        color: '#5865F2',
        image: null,
        featured: false,
        sortOrder: 0
    },
    createdAt: Date,
    updatedAt: Date
}

📋 Purchase Record Schema

Purchase Record Schema

{
    orderId: 'uuid-string',
    guildId: 'guild-id',
    userId: 'user-id',
    itemId: 'item-id',
    itemName: 'Item Name',
    category: 'pets',
    price: 50000,
    rewardType: 'pet',
    rewardData: { ... },
    status: 'completed',
    purchasedAt: Date
}