Skip to main content

Introduction

🎯 What does this module do?​

The ProductStatuses module enables additional filtering conditions for catalog items alongside existing attribute-based filters. Product Statuses 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.

Statuses serve as supplementary filtering mechanisms for catalog items, working in conjunction with attribute-based filtering to provide more granular organization and categorization options for product management.

Think of it as your product tagging system - you define status labels in OneEntry admin panel (Catalog > Product Statuses), 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

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:

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 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?​

BenefitDescription
Flexible FilteringFilter products by multiple custom criteria
Dynamic BadgesShow visual badges without hardcoding
Easy ManagementAdd/remove statuses in admin panel
Reusable LabelsApply same status to many products
Multi-LanguageStatus names localized per language
Custom StylingDefine colors and styles per status

📋 What You Need to Know​

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 → Catalog → Product Statuses → Create Status → Set Name/Marker → Save

Creation Process:

  • Provide a Name - Status designation (required)
  • Provide a Marker - Unique identifier (required, Latin letters/numbers/'_'/'-' only)
  • Click "Create" to finalize

Marker Constraints:

  • Only Latin letters (a-z, A-Z)
  • Numbers (0-9)
  • Underscore (_) and hyphen (-) symbols
  • No special characters or spaces allowed

Status Management:

  • View List - Table with Name, Marker, and Actions columns
  • Edit Status - Modify Name and Marker fields
  • Delete Status - Remove unused statuses
  • Reorder - Drag-and-drop to change display order (affects sortOrder field)

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

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

Filtering by Status​

Use status ID to filter products

Multi-Language Support​

Status names are automatically localized

💡 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.

Status List Interface​

The admin panel displays all statuses in a table with three columns:

  • Name - Status designation
  • Marker - Unique identifier
  • Actions - Edit and delete operations, plus drag-and-drop reordering

Marker Validation​

Important: The validateMarker() method helps check if a marker already exists before creating/using it.

Marker constraints:

  • Only Latin alphanumeric characters (a-z, A-Z, 0-9)
  • Underscore (_) and hyphen (-) allowed
  • No spaces or special characters
  • Must be unique across all statuses

Multiple Statuses per Product​

Products can have multiple statuses simultaneously (e.g., "New Arrival" + "On Sale")

Status vs Attributes​

ProductStatuses are different from product attributes:

FeatureProductStatusesAttributes
PurposeLabels/badges/filtersProduct properties
Examples"New", "Sale", "Featured"Color, Size, Material
Multiple valuesYes (multiple statuses)Yes (multiple attributes)
FilteringSimple (by status ID)Complex (ranges, values)
Use caseMarketing labelsProduct specifications

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

📊 Quick Reference Table​

MethodDescriptionUse Case
getProductStatuses()Get all product statusesList all available statuses
getProductsByStatusMarker()Get product status by markerFetch status by identifier
validateMarker()Check if marker existsValidate marker before use

❓ Common Questions (FAQ)​

What's the difference between product statuses and product attributes?​

Product statuses are marketing labels (New, Sale, Featured) for filtering and badging, while attributes are product specifications (Color, Size, Material). Use statuses for promotional tags and attributes for product properties.

Can a product have multiple statuses at once?​

Yes! Products can have multiple statuses simultaneously. For example, a product can be both "New Arrival" and "On Sale" at the same time. The statusIds array in the product object contains all assigned status IDs.

How do I filter products by status?​

Use the Products module methods with status filters. Pass the status ID or marker in your query to fetch products with specific statuses. You can also combine multiple status filters.

How do I validate a marker before creating a status?​

Use the validateMarker() method to check if a marker already exists. This helps prevent duplicate markers and ensures your marker follows the naming conventions (Latin letters, numbers, underscore, hyphen only).

Can I change the order of statuses displayed?​

Yes! In the admin panel, you can drag-and-drop statuses to reorder them. This affects the sortOrder field and determines the display priority in your application.

How do I add custom styling to status badges?​

Fetch all statuses, create a mapping of status markers to CSS classes or inline styles in your frontend code. Apply these styles when rendering product badges based on the product's statusIds array.

🎓 Best Practices​

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

More information about product statuses in the OneEntry admin panel: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/catalog/product-statuses/

Definition of the ProductStatuses module​

The ProductStatuses module manages statuses that serve as additional filters alongside conditions defined by attributes. Product Statuses enable additional filtering conditions for catalog items in Platform OneEntry, working in conjunction with attribute-based filtering.


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

🔗 Related Documentation​