Introduction
Quicklizard is a pricing platform: it turns what you sell, at what prices, how customers respond, and what competitors charge into the price recommendations, rules, and analytics your team uses every day. To do that, it needs a clear, continuous picture of your business. This guide explains what data Quicklizard needs, how to deliver it, and why each part matters - for pricing teams, analysts, and the IT colleagues who build the integration alike.
You don’t need everything on day one. A small set of mandatory fields gets you live; the rest sharpens accuracy and unlocks more of the platform over time. Throughout, fields are marked Prio 1 (mandatory), Prio 2 (should have), or Prio 3 (could have). For every field-level detail, validation rule, and JSON example, the full REST API documentation is the authoritative reference.
What data is needed
Quicklizard is a pricing intelligence platform. It analyzes what you sell, at what prices, how your customers respond to price changes, and what your competitors are doing - contrasted with internal cost, inventory levels and set into context of overall market developments and trends. Then produces the price recommendations and pricing analytics your team works with every day.
To do that well, the platform needs continuous visibility into your business. Each of the four data feeds plays a distinct role:
The quality of every output - every recommendation, every dashboard, every report - depends directly on how complete, fresh, and accurate these four feeds are.
Every field in the data tables carries a priority so you can sequence the integration sensibly:
Please find a detailed description of the four data feeds and an exact definition of each data field and its priority in the Data Tables & Samples tab.
How data is exchanged
Quicklizard supports several ways to get data in:
- Most customers use the REST API for ongoing data and a file transfer for the initial history load.
- Kafka and BigQuery are available for enterprise customers with the volume or infrastructure to justify them.
Delivery happens in two phases:
- One-time historical data loading for model training and to have everything ready by day one (optional).
- Ongoing steady-state delivery according to the required frequency (from almost real-time to daily, weekly, monthly, or even less frequent).
The complete overview of the delivery methods and the difference between one-time historical load and ongoing steady-state delivery frequency can be found in the Delivery & Frequency tab.
Why more data is better
The data you send drives everything Quicklizard produces, in two layers. First, the live application surfaces all the information your team uses every day: e.g., sales-performance and competitive-position dashboards, the pricing UI, and KPI reporting. Second, the AI/ML models that turn that same data into price recommendations. The quality of every output - dashboard signal and recommendation precision alike - is directly proportional to how complete and fresh the data is.
On top of that, Quicklizard runs several AI/ML models - each needs a minimum amount of history before it produces output, which is why we ask for a full historical backfill up front:
- Article Segmentation
- Price / Cross Elasticity
- Competitor Sensitivity
- X-Product Intelligence
- Seasonality & special events
- Simulation & Forecasting
The exact data prerequisites of each model can be found in the Core AI Models tab.
Data tables & sample data
The complete field list for each feed, with data type, definition, an example value, and priority. This mirrors the downloadable workbook exactly.
⬇ Download the full spec & samples (XLSX)
1 mandatory2 should have3 could have
Field names below are the business-friendly names used in
this guide. A few differ from the actual REST API field names
- e.g. product_name → label,
url → permalink,
product_image_url → image - and
catalog attributes such as brand, category levels, RRP, MAP
and VAT are sent as entries in the products
attributes[] array rather than as flat fields.
The
REST API documentation
is the authoritative reference for exact names and payload
shapes.
1. Product Master Data
List of all SKUs incl. relevant attributes (brand, supplier, etc.) and categorization (tree). Delivered via the ProductsCreate/Update endpoints.
| Variable | Data type | Definition & details | Example | Prio |
|---|---|---|---|---|
| Product classifiers | ||||
| client_key | String | The key of your system | CL001 | 1 |
| channel | String | Channel key (for omnichannel clients only) | Online-1 | 1 |
| product_id | String | Product ID | QL001 | 1 |
| shelf_price | Dec(10,2) | The current shelf price in the store | 50.99 | 1 |
| cost | Dec(10,2) | Product cost excl. tax - enables catalog-level profit calculations | 20.42 | 2 |
| url | String | URL to own webshop | http://www... | 3 |
| product_image_url | String | URL of product image | http://www... | 3 |
| Product characteristics | ||||
| product_name | String | Product name / title | Mini Adult | 1 |
| brand | String | SKU brand (e.g., Royal Canin) | Royal Canin | 3 |
| supplier | String | SKU supplier (e.g., wholesaler) | RC UK | 3 |
| manufacturer | String | SKU producer (e.g., Mars) | Mars | 3 |
| Category tree - used for grouping & model similarity-borrowing | ||||
| category_lvl_1 | String | Hierarchical category 1 (needed for product grouping) | Dog | 2 |
| category_lvl_2 | String | Hierarchical category 2 | Food | 2 |
| category_lvl_3 | String | Hierarchical category 3 | Dry | 2 |
| category_lvl_4 | String | Hierarchical category 4 | Special | 3 |
| category_lvl_5 | String | Hierarchical category 5 (deepest level, if available) | Puppy | 3 |
| Key attributes | ||||
| listing_date | date | When this SKU was first listed in the shop | 01.01.2019 | 3 |
| RRP/MSRP | Dec(10,2) | Recommended retail price | 50.99 | 3 |
| MAP | Dec(10,2) | Minimum advertised price | 40 | 3 |
| vat | % | Default VAT % for this SKU (0–100), used as fallback if not sent per record | 19 | 2 |
| product_family_id | String | Identifier for products of the same family | 122jan3b11 | 3 |
| Custom Attributes - best practices by vertical | ||||
| measurement_unit | String | For price-per-unit calculation and pack-size architecture (e.g., grocery, drugstore) | ml | 2 |
| pack_size | Dec(10,2) | Content quantity per pack, paired with measurement_unit (grocery, DIY, drugstore) | 500 | 2 |
| units_per_pack | integer | Number of sales units in a multipack (grocery, beverages) | 6 | 2 |
| color | String | Product color (fashion, furniture, DIY) | Navy | 2 |
| size | String | Product size / dimension (fashion, footwear) | 42 | 2 |
| material | String | Primary material (fashion, furniture) | Cotton | 2 |
| gender | String | Target gender (fashion, cosmetics) | Unisex | 2 |
| season | String | Seasonal collection tag (fashion, sports) | SS25 | 2 |
| Attributes… | String | Any further attributes to be discussed | 3 | |
2. Behavioral Data
Daily cost information, inventory levels and web analytics (online only). One record per product per day.
| Variable | Data type | Definition & details | Example | Prio |
|---|---|---|---|---|
| Behavioral classifiers | ||||
| date | date | Date of the day for which the data applies: %Y-%m-%d | 2023-06-27 | 1 |
| client_key | String | The key of your system | CL001 | 1 |
| channel | String | Channel key (for omnichannel clients only) | Online-1 | 1 |
| product_id | String | Product ID | QL001 | 1 |
| Web Analytics - online only | ||||
| avg_basket_position | dec(10,2) | Avg. position of item in basket that day (e.g., 1.3) | 1.3 | 2 |
| avg_traffic_cost | dec(10,2) | Paid traffic (SEA & PCE) cost / sale at product_id level that day | 4.56 | 3 |
| avg_traffic_share_seo | % | Traffic share coming from SEO (organic search) that day | 26% | 3 |
| avg_traffic_share_sea | % | Traffic share coming from SEA (paid search) that day | 34% | 3 |
| avg_traffic_share_pce | % | Traffic share coming from Price Comparison Engines that day | 40% | 3 |
| avg_conversion_rate | % | Avg. conversion rate (online only) | 3.5% | 2 |
| total_views_per_day | integer | Number of session views on this SKU for the day | 150 | 2 |
| Inventory data | ||||
| inventory | integer | Inventory level at the end of the day (0 is valid - signals genuine out-of-stock) | 90 | 1 |
| Cost data | ||||
| cost1_avg_per_unit | dec(10,2) | Avg. cost 1 of the SKU for that day (e.g., current purchase price) | 10.5 | 1 |
| cost2_avg_per_unit | dec(10,2) | Avg. cost 2 of the SKU for that day (e.g., logistic cost) | 2.4 | 2 |
| Shelf price & VAT - for historical loads & no-sale days | ||||
| avg_shelf_price_incl_vat | dec(10,2) | Avg. shelf price incl. VAT that day - lets the platform see the listed price even on days with no sales or when a price changed. Omit rather than send 0. | 59.99 | 2 |
| avg_vat | % | Avg. VAT % for the SKU that day (0–100). Omit if not applicable - do not send 0. | 19 | 2 |
3. Sales Data - Option A: Transaction level (preferred)
Transaction data gives the most precise pricing optimization and customer-behavior analysis. One row per transaction line.
| Variable | Data type | Definition & details | Example | Prio |
|---|---|---|---|---|
| Transaction classifiers | ||||
| transaction_id | String | Unique identifier of the transaction | 241120-3122 | 1 |
| transaction_line_id | integer | In case the same SKU appears twice in one transaction | 3 | 1 |
| transaction_timestamp | datetime | Date & time of the transaction: %Y-%m-%dT%H:%M:%SZ | 2023-06-27T15:45:30Z | 1 |
| client_key | String | The key of your system | CL001 | 1 |
| channel | String | Channel key (for omnichannel clients only) | Online-1 | 1 |
| product_id | String | Product ID (SKU) | QL001 | 1 |
| Sales information | ||||
| units_sold | integer | # units purchased in the transaction. Must be a positive integer. | 2 | 1 |
| shelf_price_incl_vat | dec(10,2) | Regular shelf price per unit incl. VAT (before promos) | 20.50 | 1 |
| transaction_price_incl_vat | dec(10,2) | Actual price per unit incl. VAT in the transaction | 20.50 | 1 |
| vat | % | e.g., 19% or 7% (sometimes different per category) | 19% | 1 |
| profit1_per_unit_excl_vat | dec(10,2) | Profit 1 per unit excl. VAT (e.g., price − VAT − purchase price) | 9.20 | 1 |
| profit2_per_unit_excl_vat | dec(10,2) | Profit 2 per unit excl. VAT (e.g., profit 1 − logistic cost) | 7.50 | 2 |
| promo_id | String | If empty, no promotion; if filled, promo was active | promo13341 | 2 |
| Web Analytics - online only | ||||
| transaction_basket_position | integer | Position of item in basket (e.g., first in basket) | 1 | 2 |
| Customer information | ||||
| customer_anonymous_id | String | Unique anonymous customer identifier to trace behavior over time | ID-anon-1223jdh21 | 2 |
| membership_flag | boolean | Yes: part of membership/loyalty program | TRUE | 2 |
3. Sales Data - Option B: Daily aggregation (fall-back)
Use only when transaction-level data isn’t feasible. One row per product per day.
| Variable | Data type | Definition & details | Example | Prio |
|---|---|---|---|---|
| Sales classifiers | ||||
| date | date | Date of the day for which the data applies: %Y-%m-%d | 2023-06-27 | 1 |
| client_key | String | The key of your system | CL001 | 1 |
| channel | String | Channel key (for omnichannel clients only) | Online-1 | 1 |
| product_id | String | Product ID (SKU) | QL001 | 1 |
| Sales information | ||||
| avg_shelf_price_incl_vat | dec(10,2) | Avg. regular shelf price per unit incl. VAT that day (before promos) | 13.58 | 1 |
| avg_transaction_price_incl_vat | dec(10,2) | Avg. actual price per unit incl. VAT that day | 13.2 | 1 |
| avg_vat | % | e.g., 19% or 7% (sometimes different per category) | 19% | 1 |
| total_units_sold_per_day | integer | Number of units sold that day. Must be a positive integer. | 50 | 1 |
| total_profit1_per_day_excl_vat | dec(10,2) | Total abs. profit 1 excl. VAT of that SKU that day | 230 | 1 |
| total_profit2_per_day_excl_vat | dec(10,2) | Total abs. profit 2 excl. VAT of that SKU that day | 150 | 2 |
| total_transactions_per_day | integer | Total number of orders containing this SKU that day - enables avg. basket/order size | 28 | 2 |
4. Competitor Data
Competitor prices per product at the highest available frequency.
| Variable | Data type | Definition & details | Example | Prio |
|---|---|---|---|---|
| Competitor classifiers | ||||
| product_id | String | Product ID (SKU) | QL001 | 1 |
| competitor_name | String | Competitor name / banner (e.g., zooplus.de) | Amazon | 1 |
| competitor_pce | String | Direct crawl: empty. Via Price Comparison Engine: e.g., google-shopping | Google Shopping | 2 |
| competitor_link | String | Link to competitor website PDP | http://www.amazon.de | 2 |
| competitor_timestamp | datetime | Date & time of price activation: %Y-%m-%dT%H:%M:%S | 2023-06-27T15:45:30 | 1 |
| Competitor prices | ||||
| competitor_price | dec(10,2) | Competitor price for the product | 47.53 | 1 |
| competitor_currency | String | e.g., € or $ | € | 1 |
| Comp offer context | ||||
| competitor_availability | enum | Stock status: IS (in stock), OOS (out of stock), EOL (end of life), ODC (off-channel/discontinued), NA (not available) | IS | 2 |
| match_type | enum | Competitors 2.0: "exact" (verified same product) or "similar" (category/heuristic match) | exact | 2 |
| competitor_delivery_fee | Dec(10,2) | Competitor’s delivery fee | 4.50 | 3 |
| competitor_mov | Dec(10,2) | Competitor’s minimum order value | 50.00 | 3 |
| competitor_fst | Dec(10,2) | Competitor’s free shipping threshold | 80.00 | 3 |
| kca_attributes | list | Competitors 2.0: up to 5 Key Competitor Attributes (e.g., size, color, variant) that must match for an offer to count as comparable | size, color | 3 |
Delivery methods
Quicklizard supports several ways to get data in. Most customers use the REST API for ongoing data and a file transfer for the initial history load. Kafka and BigQuery are available for enterprise customers with the volume or infrastructure to justify them.
The primary channel for ongoing data. Up to 200 records
per call, authenticated with a Bearer token; analytics
POSTs carry a qts UTC-seconds timestamp.
See the
JSON templates & API docs.
File upload (CSV) to a dedicated path or bucket your CSM provisions. Ideal for the one-time historical backfill and for large batch loads.
Streaming ingestion for high-volume, near-real-time transaction and competitor feeds. Your Solution Architect configures the topics and schema during onboarding.
Direct dataset integration for customers already operating on Google Cloud, avoiding a separate export pipeline. Arranged with your Solution Architect.
One-time historical load
Before go-live, send as much history as you have - ideally the depths in the table below. This backfill is what lets the models produce useful output from day one instead of accumulating data for months first. It’s usually delivered as files over SFTP/S3 rather than through the API.
| Feed | History to load |
|---|---|
| Product Master Data | Current snapshot |
| Behavioral Data | Last 2 years |
| Sales Data | Last 2 years |
| Competitor Data | Last 2 years |
Steady-state delivery frequency
Once live, each feed has its own natural cadence. Transaction-level sales data usually only needs to be sent once per day - it doesn’t have to be real-time. Just remember the longer the delay (e.g., a daily aggregation two days behind), the slower you react to recent changes such as competitor price moves.
| Feed | Ongoing cadence |
|---|---|
| Product Master Data | Weekly / monthly, or on change |
| Behavioral Data | Daily / weekly |
| Sales Data (transaction) | Daily (ad-hoc) |
| Sales Data (daily aggregation) | Daily |
| Competitor Data | Daily / ad-hoc |
Integration rules - what to do
These rules aren’t in the API spec but cause most onboarding issues if missed.
product_id everywhere.
Globally unique, immutable after creation, identical
across all four feeds. Any mismatch and the platform
can’t correlate the data.
transaction_line_id.
When the same SKU appears more than once in a single
transaction, each occurrence needs a distinct line
ID under the shared transaction_id.
Without it, repeated-SKU lines collide and unit counts
are under-recorded.
behavioral_data for every active product, every day
- even on days the product didn’t sell. This is how
the platform tells “low demand” from “out of stock.”
19 for 19%, never 0.19.
Applies to vat, avg_vat,
and the vat product attribute.
transactional_data OR
daily_summary for each product and date
range. Never both - mixing causes double-counting.
2024-10-21T15:04:05Z) on transactional_data,
products, and competitor prices. Future dates are
rejected.
Generic attributes - Admin Center mapping
The catalog attributes brand,
category_lvl_1, category_lvl_2,
category_lvl_3, category_lvl_4,
and category_lvl_5 are sent as
generic attributes in the attributes[]
array of the Products API. For Quicklizard to interpret
them - for grouping, filtering, or dashboard display
- they must be mapped from your attribute names to Quicklizard’s
semantic slots in
Admin Center → Display Settings configuration
(formerly “QL_Mapping” in the legacy Configurator). Your
Solution Architect configures this during onboarding.
If attributes arrive via the API but don’t appear in
dashboards, the mapping is the first place to check.
What we don’t accept - common mistakes
units_sold
to reverse a transaction. Use the corresponding
/delete endpoint instead.
competitor_prices: [] as a default.
With force_override=“yes” it will delete
all competitor prices for that product. Send it deliberately
only when you intend to clear competitor data.
999, -1, 555)
in place of real data. A value that stays constant
across many days (for example, the same inventory
number every day) is automatically detected and that
signal is disabled - so a placeholder doesn’t just
add noise, it silently switches the field off. If
you don’t have a real value, omit the field rather
than filling it with a sentinel.
Data freshness - the hard cliffs
Quicklizard’s models degrade gracefully up to a point. Past these thresholds, specific outputs stop functioning until fresh data arrives.
| Days since last data | Status | What happens |
|---|---|---|
| 0 – 7 days | Safe | All outputs running at full performance. |
| 8 – 13 days | Caution | Models still running on older data. One more missed delivery and you cross the 14-day cliff. |
| 14+ days | Forecasts gone | Demand forecasts drop to zero for affected products. Recovery resumes once fresh data is received. |
| 30+ days | Elasticity gone | Products removed from the pricing models entirely. Full recovery takes several days of fresh data. |
A silent overnight-job failure that nobody notices for a few days is the most common cause of crossing the 14-day cliff. Treat the export pipeline like production infrastructure: alert on failure, alert on stale outputs.
Core AI models & their data requirements
Quicklizard’s pricing suite is built from a range of AI models. Each model needs a minimum amount of data before it produces output - which is why we ask for a full historical backfill up front. Below a model’s threshold, the rest of the platform still works; that model simply switches on once enough data has accumulated.
Data readiness at a glance
These are survival thresholds - below them a model still returns a simplified fallback rather than nothing. The ideal thresholds are where each model runs at full capability, which is why the one-time historical load matters.
Article Segmentation
Assigns each SKU a pricing role using a multi-attribute scoring model (up to ~20 metrics, from transactional to behavioral data). Products are classified as KVIs (Key Value Indicators - shape price image, priced competitively), Sales Drivers (complete the basket, priced for sales maximization), and Profit Generators (less price-sensitive, carry margin to refinance investment in KVIs).
Must: 20+ daily records in the last 210 days, with at least 1 record in the last 30 days. Ideal: 6 months of history with transaction-level data; 200+ active products (and 90+ labelled) for full ML segmentation. Helps: cost, conversions, views, competitor prices, elasticity.
Price Elasticity
Estimates the net impact of a price change on demand, isolating the price effect from confounding factors such as stock, trends, seasonality, promotions, competitor prices, and psychological price points. Used to simulate price changes, pick SKUs for promotion, and set profit- or revenue-maximizing prices. A fallback ladder (SKU → cluster → propagated → default) guarantees a value even where sales history is thin.
Must: 30 days of history with genuine price changes (price coefficient of variation ≥ 0.03) and avg 0.3+ units/day - a product with a constant price for 120 days is excluded. Ideal: 1+ year, enabling seasonal deconfounding and more stable estimates. Helps: transaction price, competitor prices, inventory, category.
Competitor Sensitivity
Identifies the set of competitors that actually matter from your shoppers’ point of view, using a multivariate regression that isolates the effect of competitor price changes on your sales from the effect of your own prices. Lets you match relevant competitors and ignore the rest to protect margin. Scored 0 (no impact) to 1 (high impact).
Must: 30 days of product history with sales in the last 60 days, plus a per-day competitor price map. Ideal: 1+ year with competitor data on 40%+ of days per competitor pair - sparse competitor coverage is the top reason this model returns no result. Helps: transaction price, inventory.
X-Product Intelligence
Clusters products by their relationships - substitutes (alternatives for the same need, used to measure cannibalization and cross-elasticity), complements (bought together, used to find bundles and halo effects), and behavioral-alikes (similar purchase profiles, used to fill data gaps and seed defaults for new listings in other models). Built from basket data, co-purchase patterns, switching behavior, product metadata, and text embeddings.
Must: transaction-level basket data (not daily aggregates) with a basket/transaction ID, 7 days minimum, and 50+ baskets per product. Ideal: 1+ year and 500+ baskets/day for robust co-occurrence statistics. Helps: descriptive product labels, brand, and a clean category hierarchy - these directly drive match quality.
Seasonality
Detects seasonal SKUs and patterns - non-seasonal (flat year-round), seasonal (recurring peaks), and on/off (only sold in-season) - using time-series decomposition and Fourier analysis. Supports seasonal pricing strategies, promotion selection, season-start pricing, and cleaner elasticity estimates by separating price effects from seasonal trends.
Must: 1 year of weekly sales history and a sale within the last 4 weeks. Ideal: 2+ years for a product’s own year-over-year curve (below that it borrows a category/channel curve). Helps: brand and category, used for the group-level fallback curves.
Demand Forecast
Forecasts demand (units, revenue, and profit) for the coming weeks using a gradient-boosted decision-tree model (CatBoost). Key features include price, promotions, competition, sales and volatility, inventory, seasonality, holidays, and product characteristics. Used for goal assurance, stock-coverage planning, business planning, and as the baseline for impact simulation.
Must: 6 weeks of daily sales history, with a data point in the last 2 weeks and 60%+ week completeness. Ideal: 20+ weeks averaging 2+ units/week, which unlocks the full ML pipeline (below that, simpler average-based forecasts). Helps: inventory (a zero-inventory product gets a zero forecast), competitor prices, brand, category.
What-If Analysis / Simulation
Simulates the expected impact of different pricing strategies - keeping the current price, accepting the recommendation, or moving to a revenue- or profit-maximizing price - on units, revenue, and profit. Combines the demand forecast (baseline) with price elasticity to project the effect of a price change going forward, at both product and pricing-group level.
Builds on: the Demand Forecast (baseline) and Price Elasticity - so it becomes available once those two models are producing results for the product. No additional feed of its own.
A/B Testing
Tests how different pricing strategies perform against each other - SKUs assigned randomly or intentionally, from a simple treatment-vs-control split up to several groups - with live monitoring of conversion rate, units, revenue, and profit. Lets you prove impact before rolling a strategy out more widely, comparing results at group and SKU level during the test and for up to 90 days after.
Runs on the pricing and sales data already flowing for the strategies under test; no additional feed beyond the four core feeds is required.
Inventory Management
Adjusts prices to manage stock: pricing up to slow sell-out and stretch stock reach when out-of-stock risk is high, and pricing down to accelerate sell-out when overstocked. Works from a stock-coverage measure (inventory ÷ expected demand over the replenishment window) compared against the sales forecast, using elasticity to size the price move.
Must: accurate daily inventory. Builds on: the Demand Forecast and Price Elasticity to size price moves against stock coverage. Helps: competitor prices.
Clearance / Markdown
Plans an optimal price path per SKU to clear stock by a target date, optimizing for profit or revenue within guardrails (max discount, cadence, move limits, rounding, freeze periods) and reacting automatically to actual sales and stock. Used for end-of-season sell-through and end-of-life clearance aligned to replacement launches. Builds on the Demand Forecast, Elasticity, and Seasonality models.
Must: accurate, current daily inventory (the plan optimizes toward an inventory target, so it’s only as good as the inventory data), about 2 weeks of recent sales and price history, and the clearance parameters (start/target dates, goal, stock target, price floor/ceiling). Cost & VAT are required when optimizing for profit. Builds on: Elasticity, Demand Forecast and Seasonality - it runs per clearance event rather than training on history.
Revenue Maximizer & Profit Optimizer
Sets the price that mathematically maximizes a chosen business goal - highest revenue, highest profit, or a user-defined balance between the two - and continuously re-adjusts it. Especially useful for Sales Drivers and Profit Generators, private label, and SKUs without competitor prices. An optional goal-seek add-on targets category-level KPIs over time within guardrails.
Builds on: Price Elasticity, Seasonality and the Demand Forecast - the models above must be running for the product.
Comments
0 comments
Please sign in to leave a comment.