Multivariate Time Series with Covariates: Prices, Promotions and Calendars

Why covariate classes matter more than column counts

Covariate-aware models treat each input class differently, so a dataset that does not label columns by class cannot be used correctly. The Temporal Fusion Transformer paper frames multi-horizon forecasting around exactly three input types: static time-invariant covariates, known future inputs, and exogenous series observed only historically [1]. Its static covariate encoders turn metadata such as a store's format into context vectors that condition the temporal layers [1].

Open-source libraries encode the same split in their APIs. Darts accepts past_covariates, future_covariates and static covariates attached to the target TimeSeries, and which covariate types are supported varies by model [2]. If a supplier delivers one wide table with 40 numeric columns and no class labels, your engineers will have to reverse-engineer which columns were knowable at forecast time, and that guess is where most leakage starts.

The three classes in practice:

• Past-only observed: foot traffic, realized weather, web sessions, competitor shelf prices scraped or observed after the fact, inventory on hand, sensor readings. Usable only up to the forecast origin.
• Known-future: holiday and fiscal calendars, day-of-week, planned promotion flags and depth, scheduled list prices, store opening hours, maintenance windows, contracted volumes. Usable across the full horizon, but only in the version that existed at the origin.
• Static: store square footage, channel, region, SKU category, asset model number, customer segment. Constant per series, or slowly changing with effective dates.

Why real covariate-aligned series are a separate need from pretraining corpora

Most large real-world corpora assembled for time series foundation models are dominated by univariate point series, so aligned covariates are a distinct data requirement. Google's TimesFM, for example, was pretrained on a large corpus mixing real series such as search-interest and pageview data with synthetic series [3]. Benchmarks such as GIFT-Eval cover 23 datasets across seven domains and 10 frequencies with both univariate and multivariate inputs [5]. That is broad coverage, but public benchmark series rarely carry planned-versus-actual business covariates such as versioned promotion calendars.

Before assuming a given foundation model handles covariates well, check its paper for how covariate support was trained and evaluated. Fine-tuning foundation forecasters on domain data is an active research direction [4], and covariates are the main channel through which domain signal (a promotion lift curve, a price elasticity, a holiday shift) reaches the model. For the broader pretraining question, see time-series foundation model pretraining data.

The plan-versus-actual problem in known-future covariates

A known-future covariate is only valid if it is stored as it was planned at the forecast origin, not as it was eventually executed. Promotions get cancelled, extended or deepened; price changes slip by a week; a store's reopening date moves. If the training data carries the realized promotion calendar while production inference will see the planned one, the model learns a cleaner relationship than it will ever get in deployment.

The fix is a versioned plan table. Each planned value needs a plan_version_id or known_as_of timestamp, an effective_start and effective_end, and ideally a link to the realized value so you can measure plan drift. This is the time series case of the general point-in-time correct training data problem: you need as-of joins against the plan snapshot that existed when each forecast would have been made.

Typical systems of record for these plans include promotion planning modules in retail merchandising suites, price books in ERP and CPQ systems, maintenance schedules in CMMS tools, and workforce or capacity plans in spreadsheets. Spreadsheet-held plans are the riskiest because they are usually overwritten in place with no version history.

Alignment failures that silently corrupt covariate data

Alignment errors between target and covariates rarely throw errors; they shift signal by a period and quietly degrade accuracy. The common failure modes:

• Timezone mismatch. Point-of-sale targets in local store time joined to promotion calendars stored in UTC move evening promotions into the next day. Require an explicit IANA timezone per series and per covariate source.
• Aggregation level mismatch. Weekly promotion flags joined to daily sales repeat the flag across all seven days, even when the promotion ran Thursday to Sunday. Require the native grain of each covariate and the rule used to resample it.
• Week definition drift. Retail 4-4-5 fiscal weeks, ISO weeks and Sunday-start weeks disagree at year boundaries. A calendar table with explicit week keys prevents off-by-one-week holiday features.
• Hierarchy mismatch. Prices set at the SKU-region level joined to SKU-store targets need a documented mapping and an effective-dated store-to-region table.
• Late-arriving actuals. Past-only covariates such as returns or adjusted traffic counts are often restated days later. Know whether you received first-reported or restated values.
• Static attributes that are not static. Store remodels, format changes and category reassignments make "static" covariates slowly changing. Without effective dates, the model attributes a remodel's sales jump to some other input.

Leakage through covariates known only in hindsight

The most damaging covariate leakage comes from fields that look like inputs but were only available after the target period. Leakage occurs whenever features unavailable at prediction time enter training. In forecasting, the classic cases are realized promotion lift, end-of-period inventory, "was on display" flags filled in by field audits weeks later, and markdown prices set in response to slow sales.

Markdown prices are particularly subtle: they are caused by the target (weak sales), so using realized price as a known-future covariate encodes the outcome. A buyer audit should classify every candidate covariate by the earliest timestamp at which it was knowable and drop or lag anything knowable only after the forecast origin. The target leakage audit for tabular data covers the general procedure.

Illustrative record layout for a covariate-aligned delivery

A deliverable covariate dataset is easiest to validate as separate long-format tables keyed on series ID and timestamp, with a manifest declaring each column's class. Parquet with explicit timestamp types avoids most CSV date-parsing errors. Documenting the layout in a machine-readable format such as Croissant, a schema.org-based JSON-LD vocabulary for dataset resources and record structure, lets your loaders check it automatically [6].

Illustrative example: invented to show structure; it does not describe an available dataset.

Buyer checklist before licensing covariate-aligned series

Buyers should resolve alignment, versioning and rights questions before any data moves, because each is expensive to fix afterward.

Illustrative example: invented to show structure; it does not describe an available dataset.

1. Does every column carry a declared class (target, past-only, known-future, static)?
2. Are planned values stored with known_as_of or plan version, not overwritten by actuals?
3. Is there a realized counterpart for each planned covariate, so plan drift can be measured?
4. Is each source's timezone and native grain documented, with resampling rules?
5. Which fiscal or ISO week convention does the calendar use?
6. Are static attributes effective-dated?
7. Were past-only covariates delivered as first-reported or restated?
8. Which fields are causally downstream of the target (markdowns, replenishment orders)?
9. Is there enough history to cover several promotion cycles and holiday shifts per series? See how much tabular data you need.
10. Can a held-out tail be reserved for evaluation, with covariates frozen at the origin? See held-out business time series for evaluation.
11. Does the license cover the covariate tables as well as the targets, including any third-party data such as licensed weather feeds?

Domains beyond retail where covariates carry the signal

Covariate structure is domain-agnostic, and the same three classes appear well outside retail demand. In energy and utilities, load series pair with weather actuals (past-only), weather forecasts and tariff schedules (known-future) and meter or feeder attributes (static). In contact centers, call volume pairs with marketing send schedules and billing cycles as known-future inputs. In industrial operations, sensor series pair with planned maintenance windows and production schedules; the sensor and IoT data licensing page covers that category, and paired time series and text data covers operator notes aligned to telemetry.

For retail-specific order histories, see sales and order histories for demand forecasting; this page focuses on the covariate alignment layer that sits on top of any domain.

How SourceX approaches covariate-aligned operational data

SourceX sources operational datasets from US companies on request and manages the commercial process, including licensing and ongoing purchases. Data is not held in stock, so buyers describe the series and covariates they need, and SourceX looks for US businesses that hold that data; a request does not guarantee a match, and every release is approved by the supplying company. Each dataset is rights-reviewed for ownership and consents and delivered under a license defining records, uses, term and delivery, with personal details such as names and account numbers removed or replaced before delivery. You can start by describing your target series, covariate classes and grain on the SourceX buyers page.

Request covariate-aligned time series data

SourceX serves AI teams wherever they are based and works through Find, Assess, Agree, Transact and Manage, with nothing contracted until a supplier agrees. Pricing and allowed uses are agreed per deal in a license. To describe the targets, past-only, known-future and static covariates you need, go to https://sourcex.si/buyers.

For related guidance, see the tabular, time-series and transactional data buyer's guide and the AI data hub.