An Algolia record should be shaped around the way shoppers search, filter, sort, and select products—not around the entire WooCommerce product payload. A strong record is deliberately small, stable, and explicit about the values that matter to the search experience.
Start with one clear indexing unit
Decide whether an Algolia hit represents a product, a variation, or another sellable unit before writing the feed. For most WooCommerce stores, a product-level record is the best default when shoppers select size or color on the product page. A variation-level record is more appropriate when each variation has its own stock status, price, image, URL, or search relevance.
Use a stable objectID. It should not change when a product title, price, or taxonomy changes. A WooCommerce product ID is suitable for product-level records; a variation ID is suitable for variation-level records.
{"objectID":"product_4821","type":"product"}Do not generate the identifier from the product name or URL. Renaming a product should update an existing record rather than create a new one.
Separate display data from search data
Include the fields required to render a result without another request whenever possible. This usually includes the name, URL, primary image, price, sale price, currency, stock state, brand, categories, and a short description. Keep the record focused: large long descriptions, page-builder markup, related-product arrays, and unused WooCommerce metadata increase indexing and response costs without improving relevance.
Use explicit field names that match the front-end contract. Avoid ambiguous fields such as value or data; names such as price, brand, in_stock, and thumbnail_url make the record easier to maintain.
{"objectID":"product_4821","name":"Waterproof Hiking Jacket","url":"https://shop.example.com/product/waterproof-hiking-jacket/","thumbnail_url":"https://cdn.example.com/jacket.jpg","price":129.95,"currency":"USD","in_stock":true,"brand":"North Ridge","categories":["Men","Outdoor Clothing","Jackets"]}Make searchable content intentional
Algolia searches the attributes configured in searchableAttributes. Do not add every record field to that setting. Searchable attributes should reflect shopper language and business priorities, such as product name, brand, SKU, model number, and selected taxonomy labels.
A product name normally deserves the highest priority, followed by brand and then supporting terms. If you need a catch-all field for editorial synonyms or merchandising copy, create a dedicated field such as search_text rather than indexing raw HTML or every custom field.
{"name":"Waterproof Hiking Jacket","brand":"North Ridge","sku":"NR-JKT-4821","search_text":"rain shell waterproof breathable trekking outdoor jacket"}Configure the corresponding index settings deliberately:
{"searchableAttributes":["name","brand","categories","sku","search_text"]}When a field should match only as a complete phrase or exact value, do not assume that putting it in search_text will produce the desired behavior. Use Algolia settings, query-time options, or a dedicated exact-match field where appropriate.
Use the right data types for filtering and sorting
Facets and numeric filters depend on predictable types. Store prices, ratings, weights, dimensions, and timestamps as numbers. Store filter labels such as brand, color, gender, and availability as strings. Store multi-valued taxonomies as arrays of strings.
{"price":129.95,"rating":4.7,"stock_quantity":18,"brand":"North Ridge","colors":["Black","Blue"],"in_stock":true,"categories":["Outdoor Clothing","Jackets"]}Declare fields used for filtering in attributesForFaceting. Use <code;searchable(…) only when users need to search within facet values, such as a long brand list.
{"attributesForFaceting":["brand","searchable(categories)","filterOnly(in_stock)","price"]}Use filterOnly for operational fields that must be filterable but do not need facet counts. This can reduce facet-processing overhead. Keep the representation consistent: do not index one product’s price as a number and another product’s price as a formatted string such as "$129.95".
Model WooCommerce taxonomies for shopper behavior
WooCommerce category paths are useful for display, but shoppers often need both the leaf category and its ancestors. Store a flat array of category labels for filtering and a separate path for breadcrumbs or navigation.
{"categories":["Men","Outdoor Clothing","Jackets"],"category_paths":["Men > Outdoor Clothing > Jackets"]}For attributes such as color, size, material, and fit, normalize values during the feed process. Decide whether values are customer-facing labels or internal slugs, and use that decision consistently. If the interface displays “Dark Blue” but filtering uses an unrelated internal code, the record should contain both a filter value and a display value with an agreed naming convention.
{"color":"blue","color_label":"Blue","sizes":["S","M","L"],"materials":["Recycled polyester"]}Handle variations without duplicating confusing hits
Variation indexing requires a clear search result strategy. If every size and color becomes a separate hit, users may see many nearly identical results. If the parent product is indexed instead, aggregate variation data so filters do not claim availability that the product cannot satisfy.
For a product-level record, useful variation fields include available colors, available sizes, minimum price, maximum price, and an aggregate stock flag. For a variation-level index, include the variation attributes in the searchable or filterable fields and provide a URL that selects the variation when the storefront supports it.
{"objectID":"variation_4821_993","parent_product_id":4821,"name":"Waterproof Hiking Jacket — Blue / Medium","color":"Blue","size":"M","price":129.95,"in_stock":true,"url":"https://shop.example.com/product/waterproof-hiking-jacket/?attribute_color=blue&attribute_size=m"}Whichever model you choose, test filters such as “Blue,” “Medium,” and “in stock” against real inventory. A record model that looks correct in JSON can still produce inaccurate results if stock is aggregated incorrectly.
Keep ranking signals separate from presentation
Fields such as popularity, sales_count, margin_band, or merchandising_score can support custom ranking or promotions, but they should not automatically be searchable. Keep them as numeric or controlled-value attributes and configure ranking deliberately.
{"popularity":842,"merchandising_score":75,"is_featured":true,"published_at":1719792000}Do not use a formatted price, localized title, or HTML description as a ranking signal. Those values are for display or text matching, not numerical ordering.
Represent missing values consistently
Choose a policy for missing data. Omitting an optional attribute is usually preferable to indexing empty strings, placeholder text, or misleading defaults. For booleans and numeric fields that drive filters or sorting, provide a deliberate value for every record or exclude those records from the affected feature.
For example, use false for is_featured when the field is always part of the business rule, but do not set an unknown product rating to 0 if zero is a meaningful rating. An unknown rating may be better represented by an omitted field and handled explicitly in the interface.
Protect the record contract in the indexing pipeline
Define the record schema in code and validate it before sending batches to Algolia. Validate the presence and type of objectID, the URL format, image availability, numeric fields, taxonomy arrays, and stock logic. Add tests for products with no brand, no image, multiple variations, scheduled publication, sale pricing, and deleted or private WooCommerce status.
Use partial updates only when the update semantics are understood. A price or stock update can often be sent as a partial update, while a taxonomy or variation change may require rebuilding the complete record. When a product is deleted, unpublished, or made non-searchable, remove its record instead of leaving a stale hit that points to a 404 page.
Review records with real queries
Inspect representative records in the Algolia dashboard and test the queries used by the storefront. Check exact SKU searches, misspelled product names, brand filtering, price ranges, category navigation, out-of-stock handling, and products with multiple variations. The correct record is not the one with the most fields; it is the one that gives the configured index enough precise data to return and render the right product.