RAG Metadata: What WooCommerce Developers Should Index

In a WooCommerce retrieval-augmented generation system, the text inside a document is only part of the retrieval signal. Metadata determines whether the system can filter, prioritize, and explain the results it returns. A product description may be relevant to a customer’s question, but it should not be retrieved if the product is out of stock, belongs to the wrong store, applies to a different market, or is no longer published.

For WooCommerce agencies, the metadata model should be designed alongside the content model. Indexing every available WordPress field creates noise and increases synchronization work. Indexing too little makes it difficult to enforce business rules at retrieval time. The goal is to capture metadata that supports filtering, ranking, permissions, freshness, and source traceability.

What metadata does in a WooCommerce RAG system

Metadata is structured information attached to an indexed document or chunk. It is normally stored beside the searchable text in a vector database, search engine, or hybrid retrieval system.

For example, a product document might contain the following metadata:

{
  "source_type": "product",
  "source_id": 4821,
  "post_status": "publish",
  "catalog_visibility": "visible",
  "product_type": "variable",
  "category_ids": ["18", "42"],
  "brand": "Acme",
  "language": "en-US",
  "currency": "USD",
  "stock_status": "instock",
  "price_min": 29.99,
  "price_max": 59.99,
  "updated_at": "2025-02-14T10:30:00Z"
}

The embedding helps identify semantic similarity. The metadata lets the application apply rules such as “only retrieve published products in the customer’s language and currency” or “exclude products that are not available for this sales channel.”

Core identity metadata

Every indexed WooCommerce record should have stable identity fields. These fields are essential for synchronization, deduplication, debugging, and linking retrieved content back to WordPress.

source_type: Identifies the record, such as product, product_variation, category, attribute, shipping_method, refund_policy, or documentation_page.
source_id: Stores the WordPress post ID, term ID, or another stable WooCommerce identifier.
parent_id: Connects a variation to its parent product or a child document to its source page.
site_id or store_id: Separates tenants when an agency operates a multi-site or multi-store index.
canonical_url: Provides a link to the authoritative source.
source_system: Identifies whether the record came from WooCommerce, WordPress, an ERP, a help desk, or another integration.
document_version: Helps track re-indexing and schema changes.

Do not use a product name as the primary identifier. Names can change, may not be unique, and can create duplicate records during updates.

Publication and visibility metadata

WooCommerce data contains several visibility controls that should not be collapsed into a single “active” flag without preserving the original values. Index at least the relevant fields below:

post_status: Usually publish, draft, pending, private, or trash.
catalog_visibility: Common values include visible, catalog, search, and hidden.
is_featured: Useful for ranking merchandising or recommendation answers.
is_virtual and is_downloadable: Important when answering fulfillment, delivery, or access questions.
menu_order: Useful only when the storefront uses manually ordered content.
published_at and updated_at: Support freshness filtering and incremental synchronization.

A retrieval pipeline should normally exclude non-published products before generation. It may also need to distinguish products that are purchasable from products that are merely searchable, especially when an assistant is allowed to answer catalog questions but not make unavailable-product recommendations.

Taxonomy and classification metadata

Taxonomies are among the most valuable filters in a WooCommerce index. Store both machine-readable identifiers and human-readable labels.

category_ids and category_slugs
tag_ids and tag_slugs
brand_id and brand_name when brands are implemented as a taxonomy or plugin entity
attribute names and normalized attribute values
collection, season, department, and audience where the store uses custom taxonomies

For example, preserve both pa_size: "large" and a normalized value such as size_code: "L" if the storefront or ERP uses standardized codes. Human labels improve interpretability, while normalized values make filters reliable across languages and spelling variations.

Commercial metadata

Product answers often depend on commercial conditions rather than descriptive text. Index the values that your application is permitted to expose and that can be kept current.

sku: Useful for exact product lookup and support workflows.
price_min and price_max: Particularly important for variable products.
regular_price and sale_price: Use carefully when prices vary by customer role, location, currency, or pricing plugin.
currency: Never assume that a stored numeric price has a universal currency.
tax_status and tax_class: Relevant when the assistant explains displayed pricing or tax treatment.
stock_status and stock_quantity: Index only when the data is sufficiently fresh and the application is authorized to expose it.
backorders_allowed and purchasable: Useful for availability answers.
sale_start and sale_end: Support time-sensitive promotions.

A vector index should not become the authoritative source for live price or inventory. For high-risk answers, retrieve the product context from the index and then validate current price, stock, and purchasing rules through WooCommerce or the store’s commerce service before responding.

Variation metadata

Variable products require special handling. Indexing only the parent product can cause the assistant to claim that every combination is available when only some variations exist.

For variations, index:

variation_id and parent_product_id
variation SKU
attribute combinations, such as color=blue and size=large
variation price and currency
variation stock status
variation image URL, when visual selection matters
variation purchasability and backorder state

Keep the parent product as a separate document when it contains shared descriptions, specifications, and care instructions. Link the parent and variation records with parent_id rather than copying every parent field into every variation chunk. This reduces duplication and makes updates less expensive.

Locale, market, and channel metadata

Agencies frequently operate stores with multilingual content, regional catalogs, wholesale pricing, or multiple sales channels. Retrieval must be scoped to the context of the request.

language and locale
country or market
currency
storefront or sales_channel
customer_role or price_group, when permitted
included_countries and excluded_countries
tax_region, when relevant to the answer

Do not rely on language detection alone when translated products have separate records. Use the language or translation-group identifiers supplied by the multilingual implementation so that a query in French does not retrieve an unrelated English record simply because the embedding is semantically close.

Content and chunk metadata

A single WooCommerce product can produce multiple chunks: description, short description, specifications, delivery information, warranty terms, and frequently asked questions. Each chunk should retain enough context to be useful while remaining traceable.

Recommended chunk fields include:

document_id: Stable identifier for the logical product or page.
chunk_id: Unique identifier for the indexed chunk.
content_type: Such as description, specification, policy, review, or FAQ.
section: Human-readable section name.
chunk_index and chunk_count: Useful for diagnostics and controlled reconstruction.
token_count: Helps monitor chunk sizing and retrieval costs.
content_hash: Allows the synchronizer to skip unchanged content.

Include the product name and key identity information in the chunk text or in a consistently available metadata field. A specification chunk containing only “Water resistant” is difficult to interpret when retrieved without its product context.

Operational and freshness metadata

WooCommerce content changes frequently through admin edits, imports, scheduled promotions, stock updates, and integrations. Operational metadata makes the index maintainable.

indexed_at: Records when the index received the document.
source_updated_at: Records the source system’s last modification time.
sync_state: For example, active, pending, failed, or deleted.
content_hash: Detects whether re-embedding is necessary.
embedding_model: Identifies which model produced the vector.
schema_version: Supports safe migration of metadata formats.
expires_at: Useful for temporary campaigns, shipping estimates, and other time-bound content.

Use webhooks or action-based synchronization where possible, and retain a periodic reconciliation job. Events can be missed, integrations can fail, and bulk imports can update records without following the same path as an ordinary product edit.

Permissions and sensitive data

Never index customer, order, or internal operational data without defining access boundaries first. A support assistant may need order status, but that information should be isolated by customer and authorization context.

Useful access metadata can include:

visibility_scope: Such as public, authenticated, staff, or tenant-only.
allowed_roles: Used for wholesale or staff documentation.
tenant_id: Required for multi-tenant systems.
customer_scope: A restricted identifier for customer-specific records, never a substitute for runtime authorization.
contains_personal_data: Supports retention and deletion workflows.
retention_until: Enables policy-based removal.

Metadata filters are not a complete security boundary. Enforce authorization in the application and database layers, and treat retrieved text as sensitive if the source data is sensitive.

Metadata for support and order workflows

For support use cases, index knowledge-base content separately from live order data. Order records can include fields such as order ID, customer reference, status, payment state, fulfillment state, shipping country, and created or updated timestamps. However, the assistant should query current order information from an authorized transactional system whenever possible.

Support articles should have metadata such as product applicability, platform version, plugin version, audience, language, publication status, and effective date. Version metadata is especially important when an agency supports multiple WooCommerce installations with different extensions or checkout implementations.

A practical metadata schema

The following example separates universal fields from product-specific fields while keeping the structure simple enough for a hybrid search implementation:

{
  "document_id": "woocommerce:product:4821",
  "chunk_id": "woocommerce:product:4821:specifications:0",
  "source_type": "product",
  "source_id": 4821,
  "parent_id": null,
  "site_id": "store-uk",
  "post_status": "publish",
  "catalog_visibility": "visible",
  "language": "en-GB",
  "currency": "GBP",
  "category_ids": ["18", "42"],
  "attribute_values": {"pa_size": ["M", "L"], "pa_color": ["blue"]},
  "stock_status": "instock",
  "content_type": "specification",
  "source_updated_at": "2025-02-14T10:30:00Z",
  "content_hash": "sha256:...",
  "schema_version": 2
}

The exact field names should match the search technology and application conventions. Consistency is more important than choosing a particular naming style.

Common indexing mistakes

Indexing raw post meta without a contract: Plugin-specific fields can be inconsistent, duplicated, or impossible to interpret later.
Storing prices without currency or customer context: Numeric values alone are not reliable commercial facts.
Ignoring deletion and unpublishing: A product removed from WooCommerce must also be removed or disabled in the retrieval index.
Mixing tenants in one index without mandatory filters: Similar products from different stores can leak into the wrong response.
Embedding volatile inventory as permanent prose: Stock and price should be validated at request time when accuracy matters.
Using only human-readable names: Stable IDs are necessary for updates and joins.
Failing to preserve provenance: Every answerable chunk should be traceable to a URL, record ID, and source timestamp.

Implementation checklist for agencies

Define the supported use cases before selecting fields. Product discovery, presales, support, and internal search need different metadata.
Create a versioned metadata contract for products, variations, taxonomies, pages, and support records.
Separate stable descriptive metadata from volatile values such as stock, price, and delivery estimates.
Apply tenant, language, market, and permission filters before or during retrieval.
Store stable source IDs, canonical URLs, timestamps, and content hashes on every document.
Build deletion, unpublishing, and taxonomy-change handling into synchronization from the beginning.
Test retrieval with real WooCommerce edge cases, including hidden products, variable products, translated catalogs, backorders, and customer-specific pricing.
Log the metadata filters and source documents used for each response so production issues can be diagnosed.

Well-designed metadata makes a WooCommerce RAG system more accurate without requiring every rule to be encoded in the embedding. It gives retrieval a reliable way to distinguish the right product, market, language, customer context, and freshness window before the language model receives the content.

Table of contents :