🚀 New Feature: Metadata Overrides
We’re excited to announce a new capability that makes it much easier to manage time-sensitive changes in your catalog: Metadata Overrides.
Until now, if you wanted an attribute like price to change at a specific time (for example, to match the start of a sale at exactly 9pm ET), you had to carefully time your ingestion and indexing. That was always a hassle, especially when marketing campaigns needed precise alignment with communications.
With Metadata Overrides, you can plan ahead. You simply ingest future values in advance (e.g. price_october_campaign) and then configure them to automatically override the main field (price) at the exact date and time you choose. During that window, Constructor will serve the override value in all relevant APIs (Search, Browse, Autosuggest), and once the window ends, it will automatically fall back to the original field.
💡 How it helps
- No more late-night ingestions: Set it once, and the switch happens at the exact time you want.
- Perfect campaign alignment: Prices, badges, and other metadata can flip in sync with marketing messages.
- Reliable rules: Filtering, sorting and searchandizing rules will respect the override values, so everything behaves as if the new value was the original.
🧩 How to use it
Ingest your future fields in advance
- Add additional fields in your feed that hold future values (e.g. price_october_campaign, promo_price_q4, black_friday_visibility).
- These should mirror the structure of your main fields and be in the same metadata section.
{
"id": "coffee_machine",
"facets": {
"price": 10,
"price_october_campaign": 5
}
}
Configure override rules
- Use the Metadata Override APIs to tell Constructor when to swap fields.
- Example: from Oct 1st 9pm UTC until Oct 7th 11:59pm UTC, use price_october_campaign instead of price.
{
"field_name": "price",
"field_path_in_metadata": "facets.price",
"rules": [
{
"start_time": "2025-10-01T21:00:00Z",
"end_time": "2025-10-07T23:59:59Z",
"replaced_field_name": "price_october_campaign",
"replaced_field_path_in_metadata": "facets.price_october_campaign"
}
]
}
Constructor takes care of the rest
- During the configured window, all API responses will return the override value.
- Once the window expires, the original value is automatically restored.
🔗 API Reference
- Summary page Metadata Overrides
- GET Metadata Overrides
- POST Metadata Override
- PATCH Metadata Override
- DELETE Metadata Override
ℹ️ Limitations / Information to note
- Supports Search, Browse and Autosuggest for now, Recommendation support is coming soon.
- Up to 5 override rules per catalog key.
- Only one active override per field per time window.
- Overrideable fields need to be ingested and configured at least a week before the campaign start date.
- If an override field is missing for an item, the system will return the original field value.
- Start & end time values must be formatted as an ISO date & time string, with a timezone UTC offset at the end (yyyy-MM-dd hh:mm:ss.SSS±hh:mm). An entry with a missing timezone specification is assumed to be UTC.
✅ What to do next
- Start including override fields (e.g. price_october_campaign, promo_price_q4, etc.) in your feeds now.
- Configure rules via the new Metadata Overrides APIs.
Once configured, you can test results using the `now` parameter. It allows you to override the desired time with a specific timestamp.
For example, to search for "cookies" and see the results as if the query was being executed on May first at one minute past midnight:
- https://ac.cnstrc.com/search/cookies?key=[API key]&now=1651388460
- The now parameter requires a Unix epoch timestamp
- This query requires an API token in addition to an API key
- Setting a now parameter can only be set to future times
- Rules will come into effect automatically at the exact times you need.
👉 This feature removes the headache of timing ingestions and gives you reliable control over campaign/sales related changes.
