Introduction

🎯 What does this module do?

The ProductStatuses module lets you create custom product labels and filters - like "New Arrival", "Best Seller", "Sale", "Out of Stock" - to organize and filter products in your e-commerce catalog beyond standard attributes.

Think of it as your product tagging system - you define status labels in OneEntry admin panel, assign them to products, and use them to filter, badge, and categorize products dynamically.

---

📖 Simple Explanation

Every e-commerce store needs to highlight special products:

• 🆕 New Arrival - Recently added products
• 🔥 Best Seller - Popular items
• 💰 On Sale - Discounted products
• ⭐ Featured - Highlighted products
• 📦 Out of Stock - Unavailable items
• 🎁 Limited Edition - Exclusive products
• 🚚 Free Shipping - Products with free delivery

The problem with hardcoding product badges:

// ❌ Bad - Hardcoded in product data
const product = {
  name: 'Laptop',
  price: 999,
  isNew: true,
  isBestSeller: false,
  isOnSale: true,
  isFeatured: false
  // Too many boolean fields!
};

Issues:

• 🔒 Inflexible - Need code changes to add new statuses
• 📊 Hard to manage - Multiple boolean fields
• 🔄 No reusability - Can't reuse status logic
• 🎨 Inconsistent - Different badge styles everywhere

The ProductStatuses solution:

// ✅ Good - Dynamic status management
const statuses = await ProductStatuses.getProductStatuses();
// Returns: [{ id: 1, name: 'New Arrival' }, { id: 2, name: 'On Sale' }, ...]

const product = await Products.getProductById(123);
// product.statuses = [1, 2] // Assigned status IDs

// Filter products by status
const saleProducts = await Products.getProducts({
  statusId: 2  // Get all "On Sale" products
});

Benefits:

• 🔒 Flexible - Add/remove statuses in admin panel
• 📊 Easy to manage - Centralized status definitions
• 🔄 Reusable - Same status for many products
• 🎨 Consistent - Uniform badge rendering

---

✨ Key Concepts

What is a Product Status?

A Product Status is a custom label/tag for products:

• Status Name - Display name (e.g., "New Arrival", "Sale")
• Status Marker - Unique identifier for filtering
• Color/Style - Visual representation (configured in admin)
• Product Association - Which products have this status
• Filtering - Query products by status

Product Status Structure

Each product status has this structure:

{
  id: 1,
  marker: "new_arrival",           // Unique identifier
  localizeInfos: {
    title: "New Arrival",          // Display name
    description: "Recently added"  // Description
  },
  color: "#FF5722",                // Badge color
  isActive: true,                  // Status enabled
  sortOrder: 1,                    // Display order
  createdAt: "2024-01-15T10:00:00Z",
  updatedAt: "2024-01-15T10:00:00Z"
}

Common Product Statuses

Status	When to Use	Visual Example
New Arrival	Products added in last 30 days	🆕 Green badge
Best Seller	Top-selling products	🔥 Red badge
On Sale	Discounted products	💰 Yellow badge
Featured	Highlighted products	⭐ Blue badge
Out of Stock	Unavailable items	📦 Gray badge
Limited Edition	Exclusive products	🎁 Purple badge
Free Shipping	Products with free delivery	🚚 Orange badge
Eco-Friendly	Sustainable products	🌱 Green badge

Product Status Workflow

1. Create status in admin panel
   (e.g., "New Arrival")
   ↓
2. Assign status to products
   (Select products in admin)
   ↓
3. Fetch statuses via SDK
   (ProductStatuses.getProductStatuses())
   ↓
4. Display status badges on products
   (Render badges in product listings)
   ↓
5. Filter products by status
   (Products.getProducts({ statusId }))

Why Use ProductStatuses Module?

Benefit	Description
Flexible Filtering	Filter products by multiple custom criteria
Dynamic Badges	Show visual badges without hardcoding
Easy Management	Add/remove statuses in admin panel
Reusable Labels	Apply same status to many products
Multi-Language	Status names localized per language
Custom Styling	Define colors and styles per status

---

📋 What You Need to Know

1. Product Statuses are Created in Admin Panel

You cannot create statuses via the SDK - they're created in the OneEntry admin panel:

OneEntry Admin Panel → Product Statuses → Create Status → Set Name/Color → Save

The SDK is for fetching statuses and filtering products, not creating statuses.

2. Status Assignment

Statuses are assigned to products in the admin panel:

OneEntry Admin Panel → Products → Edit Product → Assign Statuses → Save

In SDK: Products have statusIds array with assigned status IDs:

const product = await Products.getProductById(123);
console.log(product.statusIds); // [1, 2] - Status IDs

3. Filtering by Status

Use status ID to filter products

4. Multi-Language Support

Status names are automatically localized

---

📊 Quick Reference Table

Method	Description	Returns	Use Case
getProductStatuses()	Get all product statuses	Promise<ProductStatus[]>	List all available statuses
getProductStatusByMarker()	Get status by marker	Promise<ProductStatus>	Fetch status by identifier

ProductStatus Structure:

interface ProductStatus {
  id: number;
  marker: string;
  localizeInfos: {
    title: string;
    description: string;
  };
  color: string;           // Hex color code
  isActive: boolean;
  sortOrder: number;
  createdAt: string;
  updatedAt: string;
}

---

💡 Important Notes

⚠️ Statuses are Created in Admin Panel

Remember: The SDK is for fetching statuses, not creating them.

To create/edit statuses: Use OneEntry Admin Panel.

🏷️ Multiple Statuses per Product

Products can have multiple statuses simultaneously (e.g. "In Stock", "Out of Stock", "Preorder")

🔍 Status vs Attributes

ProductStatuses are different from product attributes:

Feature	ProductStatuses	Attributes
Purpose	Labels/badges/filters	Product properties
Examples	"New", "Sale", "Featured"	Color, Size, Material
Multiple values	Yes (multiple statuses)	Yes (multiple attributes)
Filtering	Simple (by status ID)	Complex (ranges, values)
Use case	Marketing labels	Product specifications

Best practice: Use statuses for marketing labels, attributes for product properties.

---

🎓 Best Practices

✅ DO:

1. Use descriptive markers - new_arrival, not status1
2. Define colors consistently - Use brand color palette
3. Limit active statuses - Don't overwhelm users with too many badges
4. Keep status names short - "Sale" better than "Products on Sale"
5. Use status for filtering - Make statuses filterable in UI
6. Cache statuses - They rarely change, cache for performance
7. Display multiple statuses - Show all relevant badges on products
8. Use status for sorting - Sort by "Featured" status first

---

❌ DON'T:

1. Don't use statuses for attributes - Use Attributes module instead
2. Don't hardcode status IDs - Use markers for stability
3. Don't skip color styling - Visual badges improve UX
4. Don't overuse statuses - Max 2-3 badges per product
5. Don't forget localization - Translate status names
6. Don't ignore sortOrder - Respect display order
7. Don't filter without caching - Cache status list client-side
8. Don't forget inactive statuses - Filter by isActive: true

---

Definition of the ProductStatuses module

The 'ProductStatuses' module manages statuses that serve as additional filters alongside conditions defined by attributes.

To create additional filtering conditions for catalog items in Platform OneEntry, the functionality of Product Statuses has been added.

const { ProductStatuses } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

---

🔗 Related Documentation

• Products Module - Manage products with statuses
• Attributes Module - Product attributes vs statuses
• GeneralTypes Module - Product types and categories
• Locales Module - Multi-language status names

---