# Products & Categories
{% hint style="info" %}
**Related Documentation**
This document covers product and category configuration. For server lifecycle and pricing operations, see [Servers & Pricing Models](/business-configuration/business-configuration/servers-and-pricing.md). For promotional tools, see [Vouchers & Promotions](/business-configuration/business-configuration/vouchers-and-promotions.md).
{% endhint %}
## Overview
Products are the server packages you offer to customers in your PteroCA shop. Each product defines the resources, pricing, and game types available for purchase.
**Key Concepts:**
* **Product** - The template you configure (resources, pricing, nodes, eggs)
* **Server** - The actual game server created when a customer purchases a product
* **Product Snapshot** - An immutable copy of product settings at purchase time (ensures customers keep what they paid for)
* **Categories** - Organize products in your shop for easier browsing
{% hint style="info" %}
**For UI Walkthrough**
This guide focuses on configuration concepts and strategies. For step-by-step instructions on using the Admin Panel to create and manage products, see [Managing Products](/using-pteroca/admin-panel/managing-products.md).
{% endhint %}
***
## Creating Products
### Product Configuration Tabs
When creating a product, you'll configure four main areas:
**1. Details Tab**
* Product name and description
* Category assignment
* Active/inactive status
* Product image (shown in shop)
* Banner image (shown on product page)
#### Short Description
**Field:** `shortDescription` **Type:** VARCHAR(255) **Required:** No (nullable)
A brief summary of the product displayed in contexts where the full description is too long.
**Displayed in:**
* Product cards in the shop/store listing
* Featured Products section on the landing page
* Meta description for SEO purposes
> **Best Practice:** Write 1–2 concise sentences that highlight the key benefit of the product. Keep it under 255 characters.
**2. Server Resources Tab**
* Disk space (MB)
* RAM memory (MB)
* CPU allocation (%)
* I/O priority
* Database count
* Backup slots
* Port allocations
* Scheduled tasks limit
**3. Pricing Tab**
* Choose pricing model (Static, Slot-based, or On-Demand)
* Configure prices for different billing periods
* Set discount pricing for longer commitments
#### Price Preview
While configuring a product's pricing, a real-time **price preview** is displayed showing how the price will appear to customers.
**Example outputs:**
* `25.00 USD per 30 Days`
* `0.50 USD per minutes`
* `15.00 USD per slot per 7 Days`
The preview uses the price format configured in **General Settings → Price Format**, ensuring consistency between the admin view and the customer-facing store.
**4. Product Connections Tab**
* Select Pterodactyl nodes where servers can be created
* Choose nest (game category)
* Select available eggs (game versions)
* Configure egg variables and defaults
* Set whether customers can change eggs
### Quick Setup Example
Let's configure a Minecraft server product:
**Step 1: Basic Details**
* Name: "Minecraft Basic Server"
* Category: Minecraft Servers
* Active: Yes
* Description: "Perfect starter server for small communities"
### Configuring Egg Variables
Each egg has default configuration options and variables. You can customize these for your product:
**Default Configuration:**
* **Startup Command** - Sets how the server starts (e.g., Java memory allocation)
* **Docker Image** - The container image used
**Variables:**
* **Version** - Game version to install (e.g., SpongeVanilla version)
* **Server Jar File** - Main executable file name
You can control which settings customers can view or edit after purchase.
Egg configuration with variables
{% hint style="info" %}
If you set RAM limits in the startup command, ensure they don't exceed the RAM allocated in Server Resources tab.
{% endhint %}
{% hint style="danger" %}
Configuration options vary by egg. Different game types have different variables and requirements.
{% endhint %}
#### Egg Variable Validation Rules
When configuring egg variables, you can define validation rules to ensure user input meets the required format. Multiple rules are combined using the pipe character (`|`).
**Example:** `required|integer|between:1,100`
| Rule | Description |
| ----------------- | -------------------------------------------------- |
| `required` | Field must not be empty |
| `string` | Must be a string value |
| `numeric` | Must be a numeric value (integer or decimal) |
| `integer` | Must be a whole number |
| `email` | Must be a valid email address |
| `url` | Must be a valid URL |
| `ip` | Must be a valid IP address |
| `min:N` | Minimum value (numeric) or minimum length (string) |
| `max:N` | Maximum value (numeric) or maximum length (string) |
| `between:N,M` | Value or length must be between N and M |
| `in:a,b,c` | Value must be one of the listed options |
| `regex:/pattern/` | Value must match the regular expression |
#### Required User Variables
Setting `user_required: true` on an egg variable causes it to be presented as a form field during the server purchase process. The user must fill in this field before the server can be created.
**Use cases:**
* **License Key** — required for games like FiveM that need a valid license key before the server can start
* **RCON Password** — allow users to set their own admin password
* **Message of the Day (MOTD)** — customizable server welcome message
* **Custom Subdomain** — user-defined subdomain for their server
Variables marked as `user_required` are validated against their rules before the server creation request is sent to Pterodactyl. If validation fails, the purchase is blocked until the user provides a valid value.
***
## Product Variants
**New in v0.6.3**
Product variants allow you to link related products that differ only in their node configuration. This enables location/node selection during purchase.
### What Are Product Variants?
Variants are separate products that represent the same offering hosted on different Pterodactyl nodes. For example:
* "Minecraft Server (US East)"
* "Minecraft Server (EU West)"
* "Minecraft Server (Asia Pacific)"
These are three separate products, but they're linked as variants of the same base product.
### Benefits of Variants
* **Geographic Distribution** - Offer the same product in multiple locations
* **Node Selection** - Let customers choose their preferred server location
* **Unified Management** - Link related products while maintaining separate configurations
* **Flexible Pricing** - Each variant can have different pricing if needed
### Creating Product Variants
1. Create your base product with all desired configuration
2. Create additional products for each variant (different nodes/locations)
3. Edit the base product
4. In **Variant Products** section, select related products
5. Save changes
**Example setup:**
* Create "Minecraft Server" (base product, US nodes)
* Create "Minecraft Server EU" (variant, EU nodes)
* Create "Minecraft Server Asia" (variant, Asia nodes)
* Link them as variants in the base product
### How Variants Work
When node selection is enabled:
* Product detail page shows all available nodes from base product AND variants
* Nodes are grouped by location for easy selection
* Customer selects preferred node during purchase
* System determines which product/variant owns that node
* Server created using the appropriate product configuration
***
## Node Selection
**New in v0.6.3**
Node selection allows customers to choose which Pterodactyl node their server will be created on during purchase.
### Enabling Node Selection
**Per-Product Setting:**
1. Navigate to **Admin Panel → Products**
2. Edit a product
3. Enable **Allow User Select Location** checkbox
4. Configure product nodes (assign multiple nodes)
5. Optionally link product variants for additional nodes
6. Save changes
**When enabled:**
* Product detail page shows available nodes grouped by location
* Customer can select preferred node before purchase
* System validates node has available resources
* Selected node stored with server for reference
**When disabled (default):**
* System automatically selects best available node
* Node selection based on available resources (memory/disk)
* No customer interaction required
### Node Resource Validation
Before purchase, system validates selected node has resources:
**Validation checks:**
* Memory: Node free memory ≥ product memory requirement
* Disk: Node free disk ≥ product disk requirement
* API connectivity: Node accessible via Pterodactyl API
**If validation fails:**
* Customer shown error message
* Must select different node
* Purchase cannot proceed
### API Endpoint
`POST /api/check-node-resources`
**Request:**
```json
{
"productId": 123,
"nodeId": 456
}
```
**Response:**
```json
{
"available": true,
"message": "node.resources.available"
}
```
### Automatic Node Selection
If customer doesn't select a node (or feature disabled):
**Selection algorithm:**
1. Get all configured nodes for product (including variants)
2. Check each node's available resources
3. Compare free memory and disk space
4. Select node with most available resources
5. Find best allocation on selected node
6. Create server
**Allocation priority:**
1. Public IP addresses (not 127.0.0.1 or 0.0.0.0)
2. Non-localhost allocations
3. First available allocation
### Node Display
Nodes are grouped by location for customer selection:
**Example display:**
```
United States (US)
└─ Node 1 - New York (512 MB available)
└─ Node 2 - Los Angeles (1024 MB available)
Europe (EU)
└─ Node 3 - London (2048 MB available)
└─ Node 4 - Frankfurt (512 MB available)
```
**Grouping rules:**
* Nodes grouped by location name/short code
* Shows node name and available resources
* Disabled if resources insufficient
* Real-time availability checking
### Best Practices
**Product Configuration:**
* Assign multiple nodes to products for redundancy
* Use variants for geographic distribution
* Test node selection flow before going live
* Monitor node resource usage
**Node Naming:**
* Use clear, geographic location names
* Include datacenter or region info
* Keep node names consistent across products
**Resource Planning:**
* Ensure nodes have sufficient overhead
* Monitor resource usage regularly
* Add nodes before reaching capacity
* Balance load across available nodes
***
## Setup Fee
**New in v0.6.5**
A setup fee is an optional one-time charge applied when a customer first purchases a product. It is **not** charged on renewals.
### Configuration
**Field:** `setupFee` **Type:** Decimal (precision: 10, scale: 2) **Required:** No (nullable) **Default:** None (no setup fee)
To configure a setup fee:
1. Navigate to **Admin Panel → Products**
2. Edit a product
3. In the **Pricing Tab**, set the **Setup Fee** value (e.g., `5.00`)
4. Save changes
### How It Works
* The setup fee is added to the product price during the **first purchase only**
* On **renewals**, only the regular product price is charged
* The setup fee is stored as part of the product snapshot at purchase time
* Works with all pricing models (Static, Slot-based, On-Demand)
### Use Cases
* **Server provisioning costs** - Cover the cost of initial server setup
* **Custom configuration** - Charge for one-time custom setup work
* **Premium onboarding** - Include setup assistance in the fee
* **Hardware allocation** - Offset costs of dedicating resources
### Example
A Minecraft server product with:
* Monthly price: $10.00
* Setup fee: $5.00
**First purchase:** Customer pays $15.00 ($10.00 + $5.00 setup fee) **Renewal:** Customer pays $10.00 (setup fee not applied)
***
## Pricing Models
PteroCA supports three pricing models. Choose the one that best fits your product:
### Static Pricing (Recommended)
**How it works:** Fixed price per billing period
**Best for:** Traditional hosting plans with predictable costs
**Configuration:**
* Monthly (30 days): $5.00
* Quarterly (90 days): $13.50 (10% discount)
* Semi-annually (180 days): $24.00 (20% discount)
* Annually (365 days): $48.00 (20% discount)
**Advantages:**
* Simple for customers to understand
* Predictable revenue
* Most common model in hosting industry
**Renewal:** Customers pay the same amount at each renewal
### Slot-Based Pricing
**How it works:** Base price + additional cost per player slot
**Best for:** Games where player count matters (Minecraft, ARK, Rust)
**Configuration:**
* Base price: $3.00/month
* Price per slot: $0.50/month
* Example: 20 slots = $3.00 + (20 × $0.50) = $13.00/month
**Advantages:**
* Flexible pricing based on server size
* Customers can choose their capacity
* Fair pricing (pay for what you use)
**Note:** Requires proper slot variable configuration in the egg
### On-Demand Pricing (Experimental)
**How it works:** Pay only when server is running (per hour/day)
**Best for:** Testing environments, rarely-used servers
**Configuration:**
* Price per hour/day
* Charges only accumulate when server is online
* Automatic billing based on usage
{% hint style="warning" %}
**Experimental Feature**
On-demand pricing is experimental and may not work correctly in all scenarios. Use static pricing for production environments.
{% endhint %}
**Advantages:**
* Cost-effective for intermittent use
* Customers pay for actual usage
**Disadvantages:**
* Unpredictable costs for customers
* More complex billing
* Not fully tested
### Pricing Strategy Tips
**Encourage longer commitments:**
* Offer 10-15% discount for quarterly
* Offer 20-25% discount for annual
* Makes pricing attractive while ensuring customer retention
**Keep it simple:**
* Round to clean numbers ($5.00, not $4.87)
* Make discounts obvious (show savings)
* Don't offer too many period options
**Competitive pricing:**
* Research competitor pricing
* Consider your actual costs (resources, overhead)
* Balance profitability with market rates
***
## Categories
Categories organize your products in the shop, making it easier for customers to find what they need.
### Category Management
**To manage categories:**
1. Go to **Shop** → **Categories**
2. Create, edit, or delete categories
3. Set priority (lower number = displayed first)
**Category Fields:**
* **Name** - Display name (e.g., "Minecraft Servers")
* **Description** - Brief explanation of category
* **Image** - Visual icon for the category
* **Priority** - Sort order (10, 20, 30, etc.)
### Organization Strategies
**By Game Type:**
* Minecraft Servers
* ARK Servers
* Rust Servers
* CS:GO Servers
* Voice Servers (TeamSpeak, Mumble)
**By Tier:**
* Starter Plans
* Professional Plans
* Enterprise Plans
**By Location:**
* US East Servers
* EU West Servers
* Asia Pacific Servers
**Best Practices:**
* Keep 5-10 categories maximum
* Use clear, descriptive names
* Add category images for visual appeal
* Use priority gaps (10, 20, 30) so you can insert categories later
***
## Best Practices
### Product Naming
**Good examples:**
* "Minecraft Basic" - Clear and specific
* "ARK 20-Slot Server" - Includes key info
* "Premium Rust Server" - Indicates tier
**Avoid:**
* "Server 1" - Not descriptive
* "Best plan ever" - Vague
* Internal node names
### Product Organization
**Keep shop clean:**
* Mark outdated products as inactive instead of deleting
* Use categories effectively
* Update egg selections when new versions release
* Regular health checks on all products
**Active vs Inactive:**
* Active: Visible and purchasable
* Inactive: Hidden but preserved
* Inactive better than deletion (keeps historical data)
### Testing
**Before activating new products:**
* Test purchase flow
* Verify server creation works
* Check all egg options
* Test renewal process
* Validate pricing calculations
***
## Troubleshooting
### Product Shows as Unhealthy
**Symptoms:** Red warning icon, cannot be purchased
**Common causes:**
* Selected eggs don't exist on all nodes
* Node is offline or deleted
* Nest or egg removed from Pterodactyl
* No pricing configured
**Solutions:**
1. Check which eggs are missing: Review error message
2. Add missing eggs to nodes in Pterodactyl
3. Remove unavailable nodes from product
4. Verify at least one price is configured
5. Check node connectivity
### Cannot Purchase Product
**If customers report they can't buy your product:**
{% hint style="info" %}
**Product Unavailable Error**
When a product shows as "unavailable" in the shop, it typically means either a configuration issue or insufficient node resources. See detailed troubleshooting steps below.
{% endhint %}
#### Common Causes
**1. Product Configuration Issues:**
* Product is not marked as Active
* Product shows as Unhealthy (red warning)
* No nodes selected
* No eggs selected
* No pricing configured for any period
* Category is inactive or doesn't exist
**2. Node Resource Limitations:**
Even with correct configuration, a product becomes unavailable when assigned nodes lack sufficient resources:
* **RAM** - Not enough free memory to allocate to new server
* **CPU** - CPU allocation limit reached on node
* **Disk Space** - Insufficient storage available
* **Allocations (Ports)** - No available port allocations
* **Server Slots** - Node server limit reached (if configured)
The system automatically marks products as unavailable to prevent failed server creation.
**3. Infrastructure Issues:**
* Selected node is offline or unreachable
* Nest or egg was deleted from Pterodactyl
* API connection to Pterodactyl failed
#### Quick Diagnostics
**Step 1: Check Product Status**
1. Go to **Shop** → **Products**
2. Verify product shows green checkmark (Healthy)
3. Verify "Active" is checked
**Step 2: Check Node Resources**
1. Go to Pterodactyl admin panel
2. Check node resource usage (RAM, Disk, CPU)
3. Verify allocations are available
4. Check node online status
**Step 3: Review Product Configuration**
* Verify at least one node is selected
* Verify at least one egg is selected
* Verify pricing is configured
* Check that selected eggs exist on all selected nodes
#### Solutions
**For configuration issues:**
* Fix product settings (activate, select nodes/eggs, configure pricing)
* Ensure eggs exist on all selected nodes
**For resource limitations:**
* Add more nodes to the product
* Upgrade node capacity (RAM, disk, CPU)
* Create additional port allocations in Pterodactyl
* Remove inactive servers to free resources
* Adjust product resource requirements
{% hint style="warning" %}
**Detailed Troubleshooting**
For complete troubleshooting steps including detailed error scenarios, see [Product Unavailable](/help-and-maintenance/troubleshooting/installation-issues.md#product-unavailable) in the Troubleshooting guide.
{% endhint %}
***
## Related Documentation
**Business Configuration:**
* [Servers & Pricing Models](/business-configuration/business-configuration/servers-and-pricing.md) - Server lifecycle and renewals
* [Vouchers & Promotions](/business-configuration/business-configuration/vouchers-and-promotions.md) - Discount codes and campaigns
* [Business Configuration Overview](/business-configuration/business-configuration.md) - All business settings
**Admin Panel Guides:**
* [Managing Products](/using-pteroca/admin-panel/managing-products.md) - Detailed UI walkthrough
* [Managing Servers](/using-pteroca/admin-panel/managing-servers.md) - Server administration
**Core Configuration:**
* [Payment Configuration](/core-configuration/core-configuration/payment-configuration.md) - Stripe, currencies
* [Pterodactyl Integration](/core-configuration/pterodactyl-integration.md) - API setup, nodes, eggs
* [Access Control](/access-and-permissions/access-control.md) - Permissions for product management
***
{% hint style="success" %}
**Need Help?**
If you encounter issues not covered here, join our [Discord server](https://discord.com/invite/Gz5phhuZym) for community support!
{% endhint %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.pteroca.com/business-configuration/business-configuration/products-and-categories.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.