Product

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Overview

A Product is the central entity in Apiera, representing a sellable item with its associated data, relationships, and lifecycle state. Products can be simple standalone items or part of a variant structure.

Basics

Product types

Simple — A standalone product with no variants.

Variant parent — A parent product that groups variants together. Variant parents define which attributes are used for variation (e.g., Color, Size) but are not sellable themselves.

Variant — A specific variation of a parent product. Each variant represents a unique combination of attribute terms from the parent's variant attributes.

Core relationships

Products connect to several related entities:

Family — Defines which attributes and categories apply to the product and their requirement levels. The family acts as a template that ensures consistent data structure across similar products.

SKU — Links to inventory and logistics data including dimensions and weight. Simple products and variants connect to SKUs; variant parents typically do not.

Brand — Optional brand association for filtering and organization.

Assets — Images, documents, and videos attached to the product with ordering and a featured flag.

Contents — Localized versions of name, description, and short description.

Metadata — Custom key-value pairs for integration-specific data.

Categories and Tags — Classification and flexible labeling.

Relations — Cross-references to other products for alternatives, upsells, accessories, replacements, compatibility, and spare parts.

Variants and attribute terms

Variant parents declare which attributes are used for variation by associating them with isVariant: true. Variants don't connect to attributes directly—instead, they connect to specific attribute terms from those variant attributes.

For example, a T-Shirt variant parent might have Color and Size as variant attributes. A specific variant connects to the terms "Red" and "Large" to represent that combination.

Publishing

Products start in draft status and must be explicitly published to become visible in channels. Publishing triggers validation and sync to connected systems.

Publishing validation

Before a product can be published, the system validates:

Referenced resources must be published — Any Family or SKU linked to the product must already be in published status.

Family requirements must be satisfied — The product's Family defines requirement levels for each attribute:

A product with missing must attributes or present mustNot attributes will fail validation.

Status values

Lifecycle

Products move between statuses through explicit transitions rather than direct status updates. This ensures business rules are enforced consistently.

Transitions

Archiving vs removal

Archived products are moved to long-term storage. Use this for discontinued products, seasonal items, or anything you want to retain for historical reference but exclude from day-to-day operations.

Removed products are soft-deleted. This excludes the product from all standard reads while preserving the data for compliance or recovery purposes.

Both archived and removed products are excluded from the standard list queries and hydration results. Use explicit filters ( isArchived[eq]=true, isRemoved[eq]=true) when you need to access them.

Cascading effects

Changes to related entities can trigger automatic product transitions:

SKU unpublished or removed — Products linked to that SKU are automatically unpublished.

SKU deleted — Products linked to that SKU are reverted to draft.

Family deactivated or removed — Products in that family are automatically unpublished.

Family deleted — Products in that family are reverted to draft.

These cascading transitions ensure products never remain published with invalid or unavailable dependencies.

Localization

Your organization defines supported locales, with one marked as default (isDefault: true).

Product content (name, description, shortDescription) is stored per locale through content entries. When you update these fields directly on a product via POST or PATCH, you're actually updating the content for the default locale.

For additional locales, create content entries through the product contents endpoints. Each content entry is tied to a specific locale and contains that locale's version of the name, description, and short description.

If the default locale changes, existing content remains intact—it's associated with the locale itself, not with being "the default."

When retrieving products, localized content can be included through hydration. Your application decides which locale to display based on user preference or channel configuration.

Hydration

List and get endpoints support include[] parameters to embed related data in a single request, reducing round-trips for common read patterns.

Available includes: assets, attributes, attributeTerms, categories, tags, contents, metadata, relations.

Visibility rules apply during hydration:

• Product relations only include products that are published
• Soft-deleted items are excluded from all hydrated collections

Error codes

Publishing errors

Structure errors

State errors

Field validation errors