Metadata overrides

Metadata overrides give retailers reliable control over campaign or sales related product changes. With metadata overrides, retailers can provide additional fields in their catalog during ingestion (e.g. a price_october_campaign field) and then configure the values in a new field to override the values in a main field (e.g. price) during a given time window. During that window, Constructor will serve the override field value in place of the main field value in all relevant APIs. Once the window ends, the value will automatically return to the original field value.

API endpoints

• Retrieve metadata override rules
• Create metadata override rule
• Update metadata override
• Delete metadata override

Limitations / Information to note

• Up to 5 override rules per index.
• Only one active override rule per field per time window.
• Fields that can be overridden must be ingested and configured at least a week before the campaign start date.
• If an override field is missing for an item, Constructor will return the original field value.
• The start and end time of the override rule 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 is assumed to be UTC.

How to use it

• Include override fields (e.g. price_october_campaign) in your feed that hold future values at least a week in advance.

{
  "id": "coffee_machine",
  "facets": {
    "price": 10,
    "price_october_campaign": 5
  }
}

• Configure rules via the new metadata overrides APIs.

{
  "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"
    }
  ]
}

• Once configured, you can test the rule using the now query string parameter when requesting results. This parameter allows you to override the current time with a specific time in the future. For example, to search for "cookies" and see the results as if the query was executing at one minute past midnight (00:01:00) on December 1, 2029, use the following URL: https://ac.cnstrc.com/search/cookies?key=[API key]&now=1885615260. Note that the now query parameter takes a Unix epoch timestamp as input and requires an API token in addition to an API key. It can only be set to future times.