--- title: "Compare energy products for a month" method: POST path: "/v1/comparisons" tags: ["Comparison"] --- # Compare energy products for a month `POST /v1/comparisons` Simulates every applicable Product Version offered in the requested month for the supplied Supply Point and Consumption Profile, and returns them ranked cheapest-first per energy type. Describe the connection under `supplyPoint` (location, metering, residential) and the usage under `consumption` — supply a `consumption.electricity` and/or `consumption.gas` object to choose what to compare. `applicability` narrows to the Product Versions a household can use (before simulation). Call `GET /v1/serviceable-locations` first to discover valid postal codes/cities and which energy types each supports. See the `422` response for the location and validation errors this can return. ## Request body - object - `yearMonth` string, required — Year and month in YYYY-MM format (e.g. 2026-02) - `supplyPoint` object, required — The household's grid hookup the comparison prices against: its location, how it is metered, and whether it is residential. - `postalCode` string, required — 4-digit Belgian postal code. Determines the Distribution Network Operator and region; required for distribution cost calculation. - `city` string, required — City (gemeente). Together with postalCode it identifies the Serviceable Location, disambiguating postal codes that span several cities; required for distribution cost calculation. - `residential` boolean — Whether the supply point is residential. Defaults to true. Affects some distribution costs. - `meterType` 'Digital' | 'Analog' — The electricity meter: 'Digital' (smart) or 'Analog'. Required when comparing electricity (i.e. when a consumption.electricity object is supplied); omit for a gas-only comparison. - `tariffType` 'enkelvoudig' | 'tweevoudig' — The electricity metering/billing structure: 'enkelvoudig' (single rate) or 'tweevoudig' (day/night). Required when comparing electricity; omit for a gas-only comparison. 'nachtmeter' is not offered. - `consumption` object, required — Consumption figures per Energy Type. Provide electricity, gas, or both — each present object selects that Energy Type for comparison. - `electricity` object — Electricity Consumption Profile. Present this object to compare electricity. Required figures depend on supplyPoint.tariffType and supplyPoint.meterType. - `totalConsumption` number, nullable — Total annual electricity consumption in kWh. Required when supplyPoint.tariffType is 'enkelvoudig'. - `dayConsumption` number, nullable — Day-register consumption in kWh per year (the day rate of a tweevoudig meter). Required when supplyPoint.tariffType is 'tweevoudig'. - `nightConsumption` number, nullable — Night-register consumption in kWh per year (the night rate of a tweevoudig meter). Required when supplyPoint.tariffType is 'tweevoudig'. - `peakConsumption` number, nullable — Piekverbruik (piekvermogen) — the maximum amount of power drawn from the grid at a single moment, measured over a 15-minute quarter-hour, in kW. In Flanders the average monthly peak largely determines the capacity tariff (a significant part of the distribution network cost). Required when supplyPoint.meterType is 'Digital' (digital meters carry a capacity tariff). - `injection` number, nullable — Total annual injection in kWh (from solar panels). Omit or null if no solar panels. - `gas` object — Gas Consumption Profile. Present this object to compare gas. - `totalConsumption` number, required — Total annual gas consumption in kWh. - `productVersionIds` string[], nullable — Optional allow-list: restrict the comparison to these specific Product Version ids. - `applicability` object — Household eligibility. Removes Product Versions the household cannot use, before simulation. Tri-state fields (omit ≠ false). - `hasSolarPanels` boolean, nullable — Whether the household already has solar panels. true → self-consumption tariffs are excluded as redundant (some products, e.g. EnergyVision, include installation of solar panels and you then pay a separate rate for what you self-consume — pointless if you already have panels). false → tariffs reserved for solar owners are excluded. Omit/null to keep both eligible. - `hasElectricVehicle` boolean, nullable — Whether the household owns an electric vehicle. false → EV-only tariffs are excluded (only applicable with an EV). Omit/null or true keeps them eligible. - `interestedInSolarInstallation` boolean, nullable — Whether the household would consider installing solar panels. false → tariffs that bundle a solar-panel installation are excluded (irrelevant if not considering installation). Omit/null or true keeps them eligible. ## Response `200` Default Response - ComparisonResult - `electricity` object[], required — Electricity Product Versions, ranked cheapest-first. - `productDetails` object, required - `merchant` Merchant, required — Energy merchant offering electricity and/or gas products - `id` string, uuid, required — Unique identifier (UUID) for the merchant - `canonicalName` string, required — Stable identifier derived from the merchant's display name (camelCase, e.g. "engie" or "boltEnergie"). Unique per merchant. - `displayName` string, required — The merchant's display name - `website` string, uri, nullable, required — Merchant website URL - `hasNativeApp` boolean, nullable, required — Whether the merchant offers a native mobile app - `cooperative` boolean, nullable, required — Whether the merchant is a cooperative - `automatedSwitch` boolean, required — Whether Vwala can switch to this merchant automatically via an API integration (i.e. the merchant is an integration partner), rather than a manual or redirect submission. - `vregServicecheckRating` integer, nullable, required — VREG servicecheck rating, from 1 to 5 stars. - `vregComplaintsPerThousand` number, nullable, required — VREG complaints per 1000 customers. - `country` string, required — ISO 3166-1 alpha-2 country code (e.g. BE) - `product` Product, required — An energy product, gas or electricity, offered by a merchant. - `id` string, required - `productName` string, required - `energyType` 'ELECTRICITY' | 'GAS', required - `priceModel` 'FIXED' | 'VARIABLE' | 'DYNAMIC', required - `subType` string, nullable, required - `serviceArea` object, required - `country` string, required — ISO 3166-1 alpha-2 country code (e.g. BE) - `region` 'Flanders', required - `characteristics` object, required - `directDebitOnly` boolean, nullable, required - `emailInvoiceOnly` boolean, nullable, required - `onlineServiceOnly` boolean, nullable, required - `greenEnergy` boolean, nullable, required - `greenEnergyAndLocal` boolean, nullable, required - `contractDuration` '1 year' | '2 years' | '3 years' | '4 years' | '5 years' | '10 years' | 'UNDETERMINED', nullable, required - `priceCertaintyPeriod` 'none' | '1 month' | '2 months' | '3 months' | '4 months' | '5 months' | '6 months' | '7 months' | '8 months' | '9 months' | '10 months' | '11 months' | '1 year' | '2 years' | '3 years' | '4 years' | '5 years' | '10 years', nullable, required - `onlyForClientWithSolar` boolean, nullable, required - `onlyForClientWithEV` boolean, nullable, required - `includesSolarPanels` boolean, nullable, required - `includesChargingStation` boolean, nullable, required - `groupPurchase` boolean, nullable, required - `cooperative` boolean, nullable, required - `conditions` object[], required — Special conditions / fine print (Bijzondere voorwaarden) attached to the product. - `title` string, required - `description` string, nullable, required - `merchant` Merchant, required — Energy merchant offering electricity and/or gas products - `id` string, uuid, required — Unique identifier (UUID) for the merchant - `canonicalName` string, required — Stable identifier derived from the merchant's display name (camelCase, e.g. "engie" or "boltEnergie"). Unique per merchant. - `displayName` string, required — The merchant's display name - `website` string, uri, nullable, required — Merchant website URL - `hasNativeApp` boolean, nullable, required — Whether the merchant offers a native mobile app - `cooperative` boolean, nullable, required — Whether the merchant is a cooperative - `automatedSwitch` boolean, required — Whether Vwala can switch to this merchant automatically via an API integration (i.e. the merchant is an integration partner), rather than a manual or redirect submission. - `vregServicecheckRating` integer, nullable, required — VREG servicecheck rating, from 1 to 5 stars. - `vregComplaintsPerThousand` number, nullable, required — VREG complaints per 1000 customers. - `country` string, required — ISO 3166-1 alpha-2 country code (e.g. BE) - `version` object, required - `id` string, required - `versionDate` string, required - `tariffCardUrl` string, nullable, required - `hasVwalaDiscount` boolean, required — Whether this version carries at least one Vwala-specific discount. - `costBreakdown` object, required - `energyCost` object, required - `costCategories` object[], required - `key` string, required - `lineItems` object[], required - `key` string, required - `unitPrice` object, required - … - `quantity` object, required - … - `total` object, required - … - `total` object, required - `value` object, required - … - `unit` string, nullable - `grandTotal` object, required - `value` object, required - `exclVat` number, nullable - `inclVat` number, nullable - `unit` string, nullable - `injectionFee` object, nullable, required - `costCategories` object[], required - `key` string, required - `lineItems` object[], required - `key` string, required - `unitPrice` object, required - … - `quantity` object, required - … - `total` object, required - … - `total` object, required - `value` object, required - … - `unit` string, nullable - `grandTotal` object, required - `value` object, required - `exclVat` number, nullable - `inclVat` number, nullable - `unit` string, nullable - `discounts` object, nullable - `lineItems` object[], required - `name` string - `description` string, nullable - `valueType` string, required - `originalValue` number, required - `calculatedAmountYearly` number, required - `appliesTo` string, required - `timing` string, required - `timingMonths` number, nullable, required - `totals` object, required - `yearly` number, required - `monthly` number, required - `totals` object, required - `monthly` object, required - `flat` number, nullable, required - `withInjectionSubtracted` number, nullable, required - `withDiscountsApplied` number, nullable, required - `withInjectionAndDiscountsApplied` number, nullable, required - `yearly` object, required - `flat` number, nullable, required - `withInjectionSubtracted` number, nullable, required - `withDiscountsApplied` number, nullable, required - `withInjectionAndDiscountsApplied` number, nullable, required - `gas` object[], required — Gas Product Versions, ranked cheapest-first. - `productDetails` object, required - `merchant` Merchant, required — Energy merchant offering electricity and/or gas products - `id` string, uuid, required — Unique identifier (UUID) for the merchant - `canonicalName` string, required — Stable identifier derived from the merchant's display name (camelCase, e.g. "engie" or "boltEnergie"). Unique per merchant. - `displayName` string, required — The merchant's display name - `website` string, uri, nullable, required — Merchant website URL - `hasNativeApp` boolean, nullable, required — Whether the merchant offers a native mobile app - `cooperative` boolean, nullable, required — Whether the merchant is a cooperative - `automatedSwitch` boolean, required — Whether Vwala can switch to this merchant automatically via an API integration (i.e. the merchant is an integration partner), rather than a manual or redirect submission. - `vregServicecheckRating` integer, nullable, required — VREG servicecheck rating, from 1 to 5 stars. - `vregComplaintsPerThousand` number, nullable, required — VREG complaints per 1000 customers. - `country` string, required — ISO 3166-1 alpha-2 country code (e.g. BE) - `product` Product, required — An energy product, gas or electricity, offered by a merchant. - `id` string, required - `productName` string, required - `energyType` 'ELECTRICITY' | 'GAS', required - `priceModel` 'FIXED' | 'VARIABLE' | 'DYNAMIC', required - `subType` string, nullable, required - `serviceArea` object, required - `country` string, required — ISO 3166-1 alpha-2 country code (e.g. BE) - `region` 'Flanders', required - `characteristics` object, required - `directDebitOnly` boolean, nullable, required - `emailInvoiceOnly` boolean, nullable, required - `onlineServiceOnly` boolean, nullable, required - `greenEnergy` boolean, nullable, required - `greenEnergyAndLocal` boolean, nullable, required - `contractDuration` '1 year' | '2 years' | '3 years' | '4 years' | '5 years' | '10 years' | 'UNDETERMINED', nullable, required - `priceCertaintyPeriod` 'none' | '1 month' | '2 months' | '3 months' | '4 months' | '5 months' | '6 months' | '7 months' | '8 months' | '9 months' | '10 months' | '11 months' | '1 year' | '2 years' | '3 years' | '4 years' | '5 years' | '10 years', nullable, required - `onlyForClientWithSolar` boolean, nullable, required - `onlyForClientWithEV` boolean, nullable, required - `includesSolarPanels` boolean, nullable, required - `includesChargingStation` boolean, nullable, required - `groupPurchase` boolean, nullable, required - `cooperative` boolean, nullable, required - `conditions` object[], required — Special conditions / fine print (Bijzondere voorwaarden) attached to the product. - `title` string, required - `description` string, nullable, required - `merchant` Merchant, required — Energy merchant offering electricity and/or gas products - `id` string, uuid, required — Unique identifier (UUID) for the merchant - `canonicalName` string, required — Stable identifier derived from the merchant's display name (camelCase, e.g. "engie" or "boltEnergie"). Unique per merchant. - `displayName` string, required — The merchant's display name - `website` string, uri, nullable, required — Merchant website URL - `hasNativeApp` boolean, nullable, required — Whether the merchant offers a native mobile app - `cooperative` boolean, nullable, required — Whether the merchant is a cooperative - `automatedSwitch` boolean, required — Whether Vwala can switch to this merchant automatically via an API integration (i.e. the merchant is an integration partner), rather than a manual or redirect submission. - `vregServicecheckRating` integer, nullable, required — VREG servicecheck rating, from 1 to 5 stars. - `vregComplaintsPerThousand` number, nullable, required — VREG complaints per 1000 customers. - `country` string, required — ISO 3166-1 alpha-2 country code (e.g. BE) - `version` object, required - `id` string, required - `versionDate` string, required - `tariffCardUrl` string, nullable, required - `hasVwalaDiscount` boolean, required — Whether this version carries at least one Vwala-specific discount. - `costBreakdown` object, required - `energyCost` object, required - `costCategories` object[], required - `key` string, required - `lineItems` object[], required - `key` string, required - `unitPrice` object, required - … - `quantity` object, required - … - `total` object, required - … - `total` object, required - `value` object, required - … - `unit` string, nullable - `grandTotal` object, required - `value` object, required - `exclVat` number, nullable - `inclVat` number, nullable - `unit` string, nullable - `injectionFee` object, nullable, required - `costCategories` object[], required - `key` string, required - `lineItems` object[], required - `key` string, required - `unitPrice` object, required - … - `quantity` object, required - … - `total` object, required - … - `total` object, required - `value` object, required - … - `unit` string, nullable - `grandTotal` object, required - `value` object, required - `exclVat` number, nullable - `inclVat` number, nullable - `unit` string, nullable - `discounts` object, nullable - `lineItems` object[], required - `name` string - `description` string, nullable - `valueType` string, required - `originalValue` number, required - `calculatedAmountYearly` number, required - `appliesTo` string, required - `timing` string, required - `timingMonths` number, nullable, required - `totals` object, required - `yearly` number, required - `monthly` number, required - `totals` object, required - `monthly` object, required - `flat` number, nullable, required - `withInjectionSubtracted` number, nullable, required - `withDiscountsApplied` number, nullable, required - `withInjectionAndDiscountsApplied` number, nullable, required - `yearly` object, required - `flat` number, nullable, required - `withInjectionSubtracted` number, nullable, required - `withDiscountsApplied` number, nullable, required - `withInjectionAndDiscountsApplied` number, nullable, required ## Other responses - `400` — Default Response - `422` — Default Response --- [API](https://skmtc.dev/vwala/apis/energy-platform-api.md) · [All operations](https://skmtc.dev/vwala/apis/energy-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vwala/energy-platform-api/revisions/86688c4fea92/schema)