Skip to main content

Introduction

Fetch product status labels ("New", "Sale", "Out of Stock") to badge and filter catalog items.

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

🎯 What does this module do?​

The ProductStatuses module provides additional filtering conditions for catalog items alongside attribute-based filters. Product Statuses let you create custom labels - like "New Arrival", "Best Seller", "Sale", "Out of Stock" - to badge, organize, and filter products in your e-commerce catalog.

You define status labels in the OneEntry admin panel (Catalog > Product Statuses), assign them to products, and use this module to fetch statuses and filter products by them. The SDK is read-only: you cannot create statuses through it.

🚀 Quickstart​

Initialize the module from defineOneEntry:


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

Fetch all statuses and read their fields:

// Fetch every product status, localized to English.
const statuses = await ProductStatuses.getProductStatuses("en_US");

statuses.forEach((status) => {
  console.log(status.identifier, status.localizeInfos.title, status.isDefault);
});

// Or fetch a single status by its marker.
const sale = await ProductStatuses.getProductsByStatusMarker("sale", "en_US");
console.log(sale.localizeInfos.title); // "Sale"

✨ Key Concepts​

What is a Product Status?​

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

  • Status Name (localizeInfos) - Localized display name (e.g., "New Arrival", "Sale")
  • Status Marker (identifier) - Unique identifier used for filtering
  • Default flag (isDefault) - Whether this is the default status
  • Position (position) - Display order

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 marker
   (Products.getProducts([{ statusMarker }], langCode))

📋 What You Need to Know​

Statuses are created in the admin panel​

You cannot create statuses via the SDK - they're created in the OneEntry admin panel (Catalog > Product Statuses). Each status needs a Name (required) and a unique Marker (required).

Marker constraints:

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

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

One status per product​

A product references at most one status. The product object carries statusIdentifier (the status marker, or null):

const product = await Products.getProductById(123);
console.log(product.statusIdentifier); // "in_stock" - status marker, or null

Filtering by status​

To filter products by status, use the Products module's getProducts(body, langCode, userQuery). Pass a statusMarker field inside the IFilterParams body array to fetch products with a specific status.

Validating a marker​

validateMarker(marker) returns true if the marker exists and false otherwise. Since the SDK cannot create statuses, use it to verify a marker before referencing it in your code.

Status vs attributes​

ProductStatuses are different from product attributes:

FeatureProductStatusesAttributes
PurposeLabels/badges/filtersProduct properties
Examples"New", "Sale", "Featured"Color, Size, Material
Per productOne statusMany attributes
FilteringSimple (by status marker)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 a product status by markerFetch status by identifier
validateMarker()Check if a 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?​

No. A product references at most one status, exposed as statusIdentifier (the status marker) on the product object.

How do I filter products by status?​

Use the Products module's getProducts(body, langCode, userQuery) method. Pass a statusMarker field inside the IFilterParams body array to fetch products with a specific status.

How do I check whether a status marker exists?​

Use validateMarker() - it returns true if the marker exists and false otherwise. The SDK cannot create statuses; markers are defined in the admin panel following 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 position field, which determines display order in your application.

How do I add custom styling to status badges?​

Fetch all statuses, then map status markers to CSS classes or inline styles in your frontend code. Apply these styles when rendering a product badge based on the product's statusIdentifier.

🎓 Best Practices​

  • Use descriptive markers - new_arrival, not status1.
  • Validate before referencing - call validateMarker() before hardcoding a marker.
  • Render the status badge - show the product's statusIdentifier badge in listings.
  • Cache statuses - they rarely change, so cache for performance.

🔗 Related Documentation​