@epilot/sdk 2.20.28 → 2.20.29

package/docs/pricing.md

@@ -68,20 +68,15 @@ const { data } = await pricingClient.$calculatePricingDetails(...)
 - [`$getConditionSets`](#$getconditionsets)
 - [`$resolveConditionalEntity`](#$resolveconditionalentity)
 - [`$createConditionalVariant`](#$createconditionalvariant)
-- [`$listConditionalVariants`](#$listconditionalvariants)
-- [`$getConditionalVariantTree`](#$getconditionalvarianttree)
 - [`$getActiveConditionalVariantVersion`](#$getactiveconditionalvariantversion)
 - [`$replaceActiveConditionalVariantVersion`](#$replaceactiveconditionalvariantversion)
 - [`$patchActiveConditionalVariantVersion`](#$patchactiveconditionalvariantversion)
 - [`$deleteConditionalVariant`](#$deleteconditionalvariant)
-- [`$listConditionalVariantVersions`](#$listconditionalvariantversions)
 - [`$appendConditionalVariantVersion`](#$appendconditionalvariantversion)
 - [`$getConditionalVariantVersion`](#$getconditionalvariantversion)
 - [`$replaceConditionalVariantVersion`](#$replaceconditionalvariantversion)
 - [`$patchConditionalVariantVersion`](#$patchconditionalvariantversion)
 - [`$deleteConditionalVariantVersion`](#$deleteconditionalvariantversion)
-- [`$batchUpsertConditionalVariants`](#$batchupsertconditionalvariants)
-- [`$batchDeleteConditionalVariants`](#$batchdeleteconditionalvariants)
 
 **Schemas**
 - [`IntegrationId`](#integrationid)
@@ -92,11 +87,8 @@ const { data } = await pricingClient.$calculatePricingDetails(...)
 - [`ConditionSetCatalog`](#conditionsetcatalog)
 - [`ConditionalPricingErrorCode`](#conditionalpricingerrorcode)
 - [`ResolveConditionalEntityRequest`](#resolveconditionalentityrequest)
-- [`ResolveByContextRequest`](#resolvebycontextrequest)
-- [`ResolveByPinRequest`](#resolvebypinrequest)
 - [`ResolveContext`](#resolvecontext)
 - [`ResolveOptions`](#resolveoptions)
-- [`PinnedResolveOptions`](#pinnedresolveoptions)
 - [`ResolvedVariants`](#resolvedvariants)
 - [`ResolvedVariant`](#resolvedvariant)
 - [`CreateVariantRequest`](#createvariantrequest)
@@ -104,43 +96,16 @@ const { data } = await pricingClient.$calculatePricingDetails(...)
 - [`PinnedConditions`](#pinnedconditions)
 - [`VariantValues`](#variantvalues)
 - [`CreatedVariant`](#createdvariant)
-- [`WriteWarning`](#writewarning)
-- [`VersionMoved`](#versionmoved)
-- [`InertOverride`](#inertoverride)
-- [`InertOverrideReason`](#inertoverridereason)
+- [`VariantWriteWarning`](#variantwritewarning)
 - [`DeletedVariant`](#deletedvariant)
 - [`VariantVersion`](#variantversion)
 - [`WrittenVariantVersion`](#writtenvariantversion)
 - [`DeletedVariantVersion`](#deletedvariantversion)
+- [`VersionWriteWarning`](#versionwritewarning)
 - [`AppendVersionRequest`](#appendversionrequest)
 - [`ReplaceVersionRequest`](#replaceversionrequest)
 - [`PatchVersionRequest`](#patchversionrequest)
-- [`ListVariantsRequest`](#listvariantsrequest)
-- [`VariantTreeRequest`](#varianttreerequest)
-- [`VariantConditionFilter`](#variantconditionfilter)
-- [`VariantList`](#variantlist)
-- [`VariantListRow`](#variantlistrow)
-- [`VariantTree`](#varianttree)
-- [`VariantTreeRow`](#varianttreerow)
-- [`VariantTreeRowStatus`](#varianttreerowstatus)
-- [`VariantVersionSnapshot`](#variantversionsnapshot)
-- [`VariantVersionList`](#variantversionlist)
-- [`BatchUpsertVariantsRequest`](#batchupsertvariantsrequest)
-- [`BatchUpsertItem`](#batchupsertitem)
-- [`BatchDeleteVariantsRequest`](#batchdeletevariantsrequest)
-- [`BatchDeleteItem`](#batchdeleteitem)
-- [`BatchDeleteByVariantId`](#batchdeletebyvariantid)
-- [`BatchDeleteByConditions`](#batchdeletebyconditions)
-- [`BatchUpsertResult`](#batchupsertresult)
-- [`BatchDeleteResult`](#batchdeleteresult)
-- [`BatchUpsertOutcome`](#batchupsertoutcome)
-- [`BatchDeleteOutcome`](#batchdeleteoutcome)
-- [`BatchUpsertCounts`](#batchupsertcounts)
-- [`BatchDeleteCounts`](#batchdeletecounts)
-- [`BatchUpsertResultEntry`](#batchupsertresultentry)
-- [`BatchDeleteResultEntry`](#batchdeleteresultentry)
 - [`Error`](#error)
-- [`ReportedError`](#reportederror)
 - [`ConditionalPricingError`](#conditionalpricingerror)
 - [`Product`](#product)
 - [`Opportunity`](#opportunity)
@@ -183,6 +148,7 @@ const { data } = await pricingClient.$calculatePricingDetails(...)
 - [`ComputedPriceBreakdown`](#computedpricebreakdown)
 - [`ComputedPriceComponents`](#computedpricecomponents)
 - [`ComputePriceResult`](#computepriceresult)
+- [`ComputePriceInputs`](#computepriceinputs)
 - [`SpotMarketBiddingZone`](#spotmarketbiddingzone)
 - [`SpotMarketType`](#spotmarkettype)
 - [`SpotMarketDataFrequency`](#spotmarketdatafrequency)
@@ -1484,6 +1450,7 @@ const { data } = await client.$computePrice(
     association_id: 'string',
     billing_period: 'monthly',
     reference_date: '1970-01-01',
+    city: 'string',
     type: 'power',
     meter_type: 'classic'
   },
@@ -1515,6 +1482,17 @@ const { data } = await client.$computePrice(
     "variable_ht": {},
     "variable_nt": {}
   },
+  "inputs": {
+    "type": "power",
+    "consumptionHT": 0,
+    "consumptionNT": 0,
+    "consumptionType": "household",
+    "zipCode": "string",
+    "city": "string",
+    "providerId": "string",
+    "billingPeriod": "weekly",
+    "referenceDate": "1970-01-01"
+  },
   "_meta": {
     "signature": "string",
     "timestamp": 0
@@ -1784,65 +1762,30 @@ const { data } = await client.$productRecommendations(
       "description": "Annual internet service",
       "price_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
       "product_id": "6241487f-b7fd-428b-ab92-24ee0b37fd84",
-      "taxes": [
-        {
-          "amount": 600,
-          "tax": {
-            "active": true,
-            "description": "Without Behaviour",
-            "rate": 6,
-            "region": "DE",
-            "type": "VAT",
-            "_created_at": "2022-02-07T14:49:08.831Z",
-            "_id": "18bbbc2e-2c37-4f91-924a-07ae60d830e4",
-            "_org": "739224",
-            "_schema": "tax",
-            "_title": "Tax Without Behaviour",
-            "_updated_at": "2022-02-07T14:49:08.831Z"
-          }
-        }
-      ],
+      "taxes": [],
       "unit_amount": 10000,
       "unit_amount_net": 10000,
       "pricing_model": "per_unit",
-      "_price": {
-        "_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
-        "unit_amount": 10000,
-        "unit_amount_currency": "EUR",
-        "unit_amount_decimal": "100.00",
-        "sales_tax": "standard",
-        "is_tax_inclusive": false,
-        "price_display_in_journeys": "show_price",
-        "type": "one_time",
-        "billing_period": "weekly",
-        "billing_duration_unit": "months",
-        "notice_time_unit": "months",
-        "termination_time_unit": "months",
-        "renewal_duration_unit": "months",
-        "_schema": "price",
-        "_title": "Solar Panel Module",
-        "description": "Solar Panel Module",
-        "active": true,
-        "tax": {
-          "$relation": [
-            {
-              "entity_id": "24641e82-0690-4135-8b43-ef12a9b1c5dc"
-            }
-          ]
-        },
-        "_org": "728",
-        "_created_at": "2022-06-03T16:04:10.369Z",
-        "_updated_at": "2022-06-03T16:04:10.369Z",
-        "pricing_model": "per_unit"
-      },
-      "_product": {
-        "name": "Cool box",
-        "type": "product",
-        "_id": "73f857a4-0fbc-4aa6-983f-87c0d6d410a6",
-        "_title": "Cool box"
-      }
+      "_price": {},
+      "_product": {}
     }
-  ]
+  ],
+  "source": {
+    "item": {
+      "amount_subtotal": 10000,
+      "amount_total": 10600,
+      "currency": "EUR",
+      "description": "Annual internet service",
+      "price_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
+      "product_id": "6241487f-b7fd-428b-ab92-24ee0b37fd84",
+      "taxes": [],
+      "unit_amount": 10000,
+      "unit_amount_net": 10000,
+      "pricing_model": "per_unit",
+      "_price": {},
+      "_product": {}
+    }
+  }
 }
 ```
 
@@ -1876,17 +1819,11 @@ const { data } = await client.$getConditionSets({
       "description": "string",
       "conditions": [
         {
-          "id": "d5839b94-ba20-4225-a78e-76951d352bd6",
           "name": "postal_code",
           "label": "Postal Code",
           "type": "string",
-          "options": [
-            "private",
-            {
-              "value": "commercial",
-              "title": "Commercial customers"
-            }
-          ],
+          "options": ["private", "commercial"],
+          "allow_any": false,
           "format": "zipcode"
         }
       ]
@@ -1901,8 +1838,8 @@ const { data } = await client.$getConditionSets({
 
 ### `$resolveConditionalEntity`
 
-Resolves which of a conditional entity's variants apply, and returns each one composed: the
-base entity overlaid with the values of the version in effect at `as_of`.
+Resolves which of a conditional entity's variants apply to a situation, and returns each one
+composed: the base entity overlaid with the values of the version in effect at `as_of`.
 
 `POST /v1/conditional-pricing:resolve`
 
@@ -1920,8 +1857,7 @@ const { data } = await client.$resolveConditionalEntity(
     },
     as_of: '2027-03-15T00:00:00Z',
     options: {
-      resolve_one: false,
-      hydrate: false
+      resolve_one: false
     }
   },
 )
@@ -1940,13 +1876,7 @@ const { data } = await client.$resolveConditionalEntity(
       "_conditions": {
         "postal_code": "46045",
         "default": false
-      },
-      "_inert_overrides": [
-        {
-          "attribute": "unit_amount",
-          "reason": "ATTRIBUTE_NOT_OVERRIDABLE"
-        }
-      ]
+      }
     }
   ]
 }
@@ -1959,7 +1889,8 @@ const { data } = await client.$resolveConditionalEntity(
 ### `$createConditionalVariant`
 
 Creates one variant of a conditional entity, together with the first version carrying its
-values: a variant always has at least one version.
+values. Never two calls: a variant that existed without a version would be an entity holding
+a condition tuple
 
 `POST /v1/conditional-pricing/{slug}/entities/{entity_id}/variants`
 
@@ -2007,10 +1938,8 @@ const { data } = await client.$createConditionalVariant(
     {
       "code": "VARIANT_COUNT_APPROACHING_CAP",
       "message": "string",
-      "details": {
-        "variant_count": 0,
-        "cap": 0
-      }
+      "variant_count": 0,
+      "cap": 0
     }
   ]
 }
@@ -2020,132 +1949,6 @@ const { data } = await client.$createConditionalVariant(
 
 ---
 
-### `$listConditionalVariants`
-
-Lists a conditional entity's variants and the conditions each one pins — the browse, filter
-and search read behind the Entity UI's variant screens.
-
-`POST /v1/conditional-pricing/{slug}/entities/{entity_id}/variants:list`
-
-```ts
-const { data } = await client.$listConditionalVariants(
-  {
-    slug: 'example',
-    entity_id: 'example',
-  },
-  {
-    conditions: {
-      postal_code: '46045',
-      consumption: {
-        lt: 5000
-      }
-    },
-    search: '460',
-    sort: 'conditions.postal_code:asc',
-    from: 0,
-    size: 10,
-    cursor: 'eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0'
-  },
-)
-```
-
-<details>
-<summary>Response</summary>
-
-```json
-{
-  "hits": 8128,
-  "results": [
-    {
-      "variant_id": "var-46045",
-      "entity_id": "price-sp26d1yo",
-      "schema": "product",
-      "conditions": {
-        "postal_code": "46045",
-        "default": false
-      }
-    }
-  ],
-  "next": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
-}
-```
-
-</details>
-
----
-
-### `$getConditionalVariantTree`
-
-The variants list, each row carrying the version in effect at `as_of` — the Entity UI's main
-editing screen in one call rather than one call per row.
-
-`POST /v1/conditional-pricing/{slug}/entities/{entity_id}/variants:tree`
-
-```ts
-const { data } = await client.$getConditionalVariantTree(
-  {
-    slug: 'example',
-    entity_id: 'example',
-  },
-  {
-    conditions: {
-      postal_code: '46045',
-      consumption: {
-        lt: 5000
-      }
-    },
-    search: '460',
-    sort: 'conditions.postal_code:asc',
-    from: 0,
-    size: 10,
-    cursor: 'eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0',
-    as_of: '2027-03-15T00:00:00Z'
-  },
-)
-```
-
-<details>
-<summary>Response</summary>
-
-```json
-{
-  "hits": 8128,
-  "results": [
-    {
-      "variant_id": "var-46045",
-      "entity_id": "price-sp26d1yo",
-      "schema": "product",
-      "conditions": {
-        "postal_code": "46045",
-        "default": false
-      },
-      "status": "active",
-      "version": {
-        "variant_id": "var-46045",
-        "entity_id": "price-sp26d1yo",
-        "schema": "product",
-        "conditions": {
-          "postal_code": "46045",
-          "default": false
-        },
-        "valid_from": "2027-01-01T00:00:00.000Z",
-        "values": {
-          "unit_amount": 2499,
-          "unit_amount_decimal": "24.99"
-        },
-        "_created_at": "string",
-        "_updated_at": "string"
-      }
-    }
-  ],
-  "next": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
-}
-```
-
-</details>
-
----
-
 ### `$getActiveConditionalVariantVersion`
 
 Returns the version of this variant that is currently in effect — the one with the latest
@@ -2237,12 +2040,10 @@ const { data } = await client.$replaceActiveConditionalVariantVersion(
   "_revision": 3,
   "warnings": [
     {
-      "code": "VARIANT_COUNT_APPROACHING_CAP",
+      "code": "ACTIVE_VERSION_REPLACED",
       "message": "string",
-      "details": {
-        "variant_count": 0,
-        "cap": 0
-      }
+      "valid_from": "2026-08-01T00:00:00.000Z",
+      "active_valid_from": "2026-01-01T00:00:00.000Z"
     }
   ]
 }
@@ -2301,12 +2102,10 @@ const { data } = await client.$patchActiveConditionalVariantVersion(
   "_revision": 3,
   "warnings": [
     {
-      "code": "VARIANT_COUNT_APPROACHING_CAP",
+      "code": "ACTIVE_VERSION_REPLACED",
       "message": "string",
-      "details": {
-        "variant_count": 0,
-        "cap": 0
-      }
+      "valid_from": "2026-08-01T00:00:00.000Z",
+      "active_valid_from": "2026-01-01T00:00:00.000Z"
     }
   ]
 }
@@ -2348,55 +2147,6 @@ const { data } = await client.$deleteConditionalVariant({
 
 ---
 
-### `$listConditionalVariantVersions`
-
-Lists one variant's versions — its whole timeline, oldest first, which is what expanding a row
-of the tree loads.
-
-`GET /v1/conditional-pricing/{slug}/entities/{entity_id}/variants/{variant_id}/versions`
-
-```ts
-const { data } = await client.$listConditionalVariantVersions({
-  slug: 'example',
-  entity_id: 'example',
-  variant_id: 'example',
-  limit: 1,
-  order: 'example',
-  cursor: 'example',
-})
-```
-
-<details>
-<summary>Response</summary>
-
-```json
-{
-  "results": [
-    {
-      "variant_id": "var-46045",
-      "entity_id": "price-sp26d1yo",
-      "schema": "product",
-      "conditions": {
-        "postal_code": "46045",
-        "default": false
-      },
-      "valid_from": "2027-01-01T00:00:00.000Z",
-      "values": {
-        "unit_amount": 2499,
-        "unit_amount_decimal": "24.99"
-      },
-      "_created_at": "string",
-      "_updated_at": "string"
-    }
-  ],
-  "next": "eyJzayI6IlYjcHJpY2Utc3AyNmQxeW8jdmFyLTQ2MDQ1IzIwMjYtMDEtMDFUMDA6MDA6MDAuMDAwWiIsIm9yZGVyIjoiYXNjIn0"
-}
-```
-
-</details>
-
----
-
 ### `$appendConditionalVariantVersion`
 
 Appends a version to a variant: a new set of values taking effect at its own instant.
@@ -2445,12 +2195,10 @@ const { data } = await client.$appendConditionalVariantVersion(
   "_revision": 3,
   "warnings": [
     {
-      "code": "VARIANT_COUNT_APPROACHING_CAP",
+      "code": "ACTIVE_VERSION_REPLACED",
       "message": "string",
-      "details": {
-        "variant_count": 0,
-        "cap": 0
-      }
+      "valid_from": "2026-08-01T00:00:00.000Z",
+      "active_valid_from": "2026-01-01T00:00:00.000Z"
     }
   ]
 }
@@ -2553,12 +2301,10 @@ const { data } = await client.$replaceConditionalVariantVersion(
   "_revision": 3,
   "warnings": [
     {
-      "code": "VARIANT_COUNT_APPROACHING_CAP",
+      "code": "ACTIVE_VERSION_REPLACED",
       "message": "string",
-      "details": {
-        "variant_count": 0,
-        "cap": 0
-      }
+      "valid_from": "2026-08-01T00:00:00.000Z",
+      "active_valid_from": "2026-01-01T00:00:00.000Z"
     }
   ]
 }
@@ -2618,12 +2364,10 @@ const { data } = await client.$patchConditionalVariantVersion(
   "_revision": 3,
   "warnings": [
     {
-      "code": "VARIANT_COUNT_APPROACHING_CAP",
+      "code": "ACTIVE_VERSION_REPLACED",
       "message": "string",
-      "details": {
-        "variant_count": 0,
-        "cap": 0
-      }
+      "valid_from": "2026-08-01T00:00:00.000Z",
+      "active_valid_from": "2026-01-01T00:00:00.000Z"
     }
   ]
 }
@@ -2660,157 +2404,10 @@ const { data } = await client.$deleteConditionalVariantVersion({
   "valid_from": "2027-01-01T00:00:00.000Z",
   "warnings": [
     {
-      "code": "VARIANT_COUNT_APPROACHING_CAP",
+      "code": "ACTIVE_VERSION_REPLACED",
       "message": "string",
-      "details": {
-        "variant_count": 0,
-        "cap": 0
-      }
-    }
-  ]
-}
-```
-
-</details>
-
----
-
-### `$batchUpsertConditionalVariants`
-
-Writes up to 100 variants or versions in one call — the endpoint a bulk importer drives a
-refresh cycle through, so hundreds of thousands of keys are a stream of calls rather than a
-call per key.
-
-`POST /v1/conditional-pricing/{slug}/variants:batchUpsert`
-
-```ts
-const { data } = await client.$batchUpsertConditionalVariants(
-  {
-    slug: 'example',
-  },
-  {
-    correlation_id: 'tariff-refresh-2027-01',
-    items: [
-      {
-        entity_id: 'price-sp26d1yo',
-        conditions: {
-          postal_code: '46045'
-        },
-        default: false,
-        valid_from: '2027-01-01T00:00:00Z',
-        values: {
-          unit_amount: 2499,
-          unit_amount_decimal: '24.99'
-        }
-      }
-    ]
-  },
-)
-```
-
-<details>
-<summary>Response</summary>
-
-```json
-{
-  "correlation_id": "tariff-refresh-2027-01",
-  "counts": {
-    "variant_created": 1,
-    "version_created": 1,
-    "updated": 1,
-    "skipped": 1,
-    "error": 1
-  },
-  "results": [
-    {
-      "outcome": "variant_created",
-      "entity_id": "price-sp26d1yo",
-      "variant_id": "var-46045",
-      "valid_from": "2027-01-01T00:00:00.000Z",
-      "warnings": [
-        {
-          "code": "VARIANT_COUNT_APPROACHING_CAP",
-          "message": "string",
-          "details": {
-            "variant_count": 0,
-            "cap": 0
-          }
-        }
-      ],
-      "error": {
-        "code": "SCHEMA_NOT_FOUND",
-        "details": {
-          "schema": "price"
-        }
-      }
-    }
-  ]
-}
-```
-
-</details>
-
----
-
-### `$batchDeleteConditionalVariants`
-
-Removes up to 100 variants or versions in one call — the symmetric bulk withdrawal, so
-retiring a generation of variants, or a scheduled adjustment across many of them, is as
-cheap as creating it was.
-
-`POST /v1/conditional-pricing/{slug}/variants:batchDelete`
-
-```ts
-const { data } = await client.$batchDeleteConditionalVariants(
-  {
-    slug: 'example',
-  },
-  {
-    correlation_id: 'postal-code-cleanup-2026-09',
-    items: [
-      {
-        entity_id: 'price-sp26d1yo',
-        variant_id: 'var-46045',
-        valid_from: '2027-01-01T00:00:00Z'
-      }
-    ]
-  },
-)
-```
-
-<details>
-<summary>Response</summary>
-
-```json
-{
-  "correlation_id": "postal-code-cleanup-2026-09",
-  "counts": {
-    "deleted": 1,
-    "skipped": 1,
-    "error": 1
-  },
-  "results": [
-    {
-      "outcome": "deleted",
-      "entity_id": "price-sp26d1yo",
-      "variant_id": "var-46045",
-      "valid_from": "2027-01-01T00:00:00.000Z",
-      "warnings": [
-        {
-          "code": "VARIANT_COUNT_APPROACHING_CAP",
-          "message": "string",
-          "details": {
-            "variant_count": 0,
-            "cap": 0
-          }
-        }
-      ],
-      "error": {
-        "code": "SCHEMA_NOT_FOUND",
-        "details": {
-          "schema": "price"
-        }
-      }
+      "valid_from": "2026-08-01T00:00:00.000Z",
+      "active_valid_from": "2026-01-01T00:00:00.000Z"
     }
   ]
 }
@@ -2860,7 +2457,6 @@ verbatim.
 
 ```ts
 type ConditionDefinition = {
-  id: string // uuid
   name: string
   label: string
   type: "string" | "number" | "date" | "daterange" | "boolean" | "select" | "location"
@@ -2868,7 +2464,8 @@ type ConditionDefinition = {
     value: string
     title?: string
   }>
-  format?: "zipcode" | "zipcode_town"
+  allow_any?: boolean
+  format?: "zipcode" | "zipcode + town"
 }
 ```
 
@@ -2882,7 +2479,6 @@ type ConditionSet = {
   label: string
   description: string
   conditions: Array<{
-    id: string // uuid
     name: string
     label: string
     type: "string" | "number" | "date" | "daterange" | "boolean" | "select" | "location"
@@ -2890,7 +2486,8 @@ type ConditionSet = {
       value: { ... }
       title?: { ... }
     }>
-    format?: "zipcode" | "zipcode_town"
+    allow_any?: boolean
+    format?: "zipcode" | "zipcode + town"
   }>
 }
 ```
@@ -2904,11 +2501,11 @@ type ConditionSetCatalog = {
     label: string
     description: string
     conditions: Array<{
-      id: { ... }
       name: { ... }
       label: { ... }
       type: { ... }
       options?: { ... }
+      allow_any?: { ... }
       format?: { ... }
     }>
   }>
@@ -2920,88 +2517,34 @@ type ConditionSetCatalog = {
 Machine-readable failure mode of a conditional-pricing operation, allowing clients
 to branch on the kind of failure instead of parsing the error message.
 
-- `SCHEMA_NOT_FOUND` (404): no conditional entity type by that slug
-- `ENTITY_NOT_FOUND` (404): the schema holds no entity with that id
-- `ENTITY
+- `NOT_FOUND` (404): the addressed entity, variant or version does not exist
+- `AMBIGUOUS_RESOLUTION` (409): several variants match the given con
 
 ```ts
-type ConditionalPricingErrorCode = "SCHEMA_NOT_FOUND" | "ENTITY_NOT_FOUND" | "ENTITY_TYPE_MISMATCH" | "ENTITY_NOT_CONDITIONAL" | "VARIANT_NOT_FOUND" | "VERSION_NOT_FOUND" | "NO_MATCHES" | "NO_ACTIVE_VERSION" | "AMBIGUOUS_RESOLUTION" | "TUPLE_CONFLICT" | "VERSION_CONFLICT" | "CONDITION_UNDEFINED" | "OPERATOR_UNSUPPORTED" | "CONTEXT_FORMAT_INVALID" | "CONDITION_VALUE_INVALID" | "TOO_MANY_MATCHES" | "WRITE_CONFLICT" | "OFFSET_WINDOW_EXCEEDED" | "CURSOR_INVALID" | "VARIANT_LIMIT_REACHED" | "PIN_FORMAT_INVALID" | "VARIANT_UNPINNED" | "LAST_VERSION_UNDELETABLE"
+type ConditionalPricingErrorCode = "NOT_FOUND" | "AMBIGUOUS_RESOLUTION" | "TUPLE_CONFLICT" | "VERSION_CONFLICT" | "CONDITION_UNDEFINED" | "OPERATOR_UNSUPPORTED" | "CONTEXT_FORMAT_INVALID" | "CONDITION_VALUE_INVALID" | "TOO_MANY_MATCHES" | "WRITE_CONFLICT"
 ```
 
 ### `ResolveConditionalEntityRequest`
 
-A resolve names one conditional entity, then says which of its variants it means — one of two
-ways, and never both. `context` describes a situation and asks which variants apply to it;
-`variant_id` names one variant and skips matching entirely.
-
-A body carrying both, or neither, is a validation `400
-
 ```ts
 type ResolveConditionalEntityRequest = {
   schema: "product" | "price" | "coupon"
   entity_id: string
-  context: Record<string, unknown>
+  context?: Record<string, unknown>
   as_of?: string
   options?: {
     resolve_one?: boolean
-    hydrate?: boolean
-  }
-} | {
-  schema: "product" | "price" | "coupon"
-  entity_id: string
-  variant_id: string
-  as_of?: string
-  options?: {
-    hydrate?: boolean
   }
 }
 ```
 
-### `ResolveByContextRequest`
+### `ResolveContext`
 
-Resolve by matching a situation: which of this entity's variants apply to `context`, each
-composed with the version in effect at `as_of`.
+The situation to resolve for: a flat map keyed by condition name, as the entity's schema
+declares them. A condition left out of the map is not a wildcard — it matches only variants
+that leave that condition unpinned.
 
-
-```ts
-type ResolveByContextRequest = {
-  schema: "product" | "price" | "coupon"
-  entity_id: string
-  context: Record<string, unknown>
-  as_of?: string
-  options?: {
-    resolve_one?: boolean
-    hydrate?: boolean
-  }
-}
-```
-
-### `ResolveByPinRequest`
-
-Resolve by naming a variant: compose this one, whatever a context would have matched. What an
-order needs to show the numbers a customer agreed to, and what a contract needs to show what
-is billable now — the two differ only in whether `as_of` is supplied.
-
-
-```ts
-type ResolveByPinRequest = {
-  schema: "product" | "price" | "coupon"
-  entity_id: string
-  variant_id: string
-  as_of?: string
-  options?: {
-    hydrate?: boolean
-  }
-}
-```
-
-### `ResolveContext`
-
-The situation to resolve for: a flat map keyed by condition name, as the entity's schema
-declares them. A condition left out of the map is not a wildcard — it matches only variants
-that leave that condition unpinned.
-
-Each value is either an exact value, typed by its condition, or a single-operator 
+Each value is either an exact value, typed by its condition, or a single-operator 
 
 ```ts
 type ResolveContext = Record<string, unknown>
@@ -3009,25 +2552,9 @@ type ResolveContext = Record<string, unknown>
 
 ### `ResolveOptions`
 
-The options a context resolve accepts. A pin takes `PinnedResolveOptions` instead.
-
 ```ts
 type ResolveOptions = {
   resolve_one?: boolean
-  hydrate?: boolean
-}
-```
-
-### `PinnedResolveOptions`
-
-The options a pinned resolve accepts — `hydrate` and nothing else. `resolve_one` has nothing
-to change on this branch, where the answer is exactly one result or a 404, so a body sending
-it is a validation `400`. `hydrate` means what `ResolveOptions.hydrate` means.
-
-
-```ts
-type PinnedResolveOptions = {
-  hydrate?: boolean
 }
 ```
 
@@ -3042,10 +2569,6 @@ type ResolvedVariants = {
     _conditions: {
       default: { ... }
     }
-    _inert_overrides: Array<{
-      attribute: { ... }
-      reason: { ... }
-    }>
   }>
 }
 ```
@@ -3056,8 +2579,6 @@ The entity as this variant leaves it — every attribute of a plain entity read,
 applicable version's overrides applied — plus the discriminators saying where the numbers
 came from.
 
-With `options.hydrate`, a relation attribute holds the entities it references rather than the
-references thems
 
 ```ts
 type ResolvedVariant = {
@@ -3067,10 +2588,6 @@ type ResolvedVariant = {
   _conditions: {
     default: boolean
   }
-  _inert_overrides: Array<{
-    attribute: string
-    reason: "ATTRIBUTE_NOT_OVERRIDABLE" | "ATTRIBUTE_READONLY" | "ATTRIBUTE_HIDDEN" | "ATTRIBUTE_COMPUTED" | "ATTRIBUTE_UNDECLARED" | "TYPE_NOT_OVERRIDABLE" | "CAPABILITY_NOT_OVERRIDABLE"
-  }>
 }
 ```
 
@@ -3115,8 +2632,8 @@ type PinnedConditions = Record<string, unknown>
 The attribute values this version overrides on the base entity, keyed by attribute name.
 
 Only attributes currently declaring `overridable_attribute` are applied. Metadata fields
-(anything underscore-prefixed), readonly attributes, hidden attributes, computed attributes,
-attributes of a type no vari
+(anything underscore-prefixed), readonly attributes, hidden attributes and non-overridable
+attributes present here are ig
 
 ```ts
 type VariantValues = Record<string, unknown>
@@ -3140,831 +2657,149 @@ type CreatedVariant = {
   warnings: Array<{
     code: "VARIANT_COUNT_APPROACHING_CAP"
     message: string
-    details: {
-      variant_count: { ... }
-      cap: { ... }
-    }
-  } | {
-    code: "ACTIVE_VERSION_CHANGED"
-    message: string
-    details: {
-      valid_from: { ... }
-      active_valid_from?: { ... }
-    }
-  } | {
-    code: "SUPERSEDED_VERSION_WRITTEN"
-    message: string
-    details: {
-      valid_from: { ... }
-      active_valid_from?: { ... }
-    }
-  } | {
-    code: "ATTRIBUTES_NOT_APPLIED"
-    message: string
-    details: {
-      attributes: { ... }
-    }
-  }>
-}
-```
-
-### `WriteWarning`
-
-Something worth knowing that did not stop a write.
-
-One vocabulary for every write, so a client branches on what happened rather than on which
-endpoint it called. `code` and `message` are the only two fields every code shares; everything
-else lives in a `details` object typed per code, so narrowing 
-
-```ts
-type WriteWarning = {
-  code: "VARIANT_COUNT_APPROACHING_CAP"
-  message: string
-  details: {
     variant_count: number
     cap: number
-  }
-} | {
-  code: "ACTIVE_VERSION_CHANGED"
-  message: string
-  details: {
-    valid_from: string
-    active_valid_from?: string
-  }
-} | {
-  code: "SUPERSEDED_VERSION_WRITTEN"
-  message: string
-  details: {
-    valid_from: string
-    active_valid_from?: string
-  }
-} | {
-  code: "ATTRIBUTES_NOT_APPLIED"
-  message: string
-  details: {
-    attributes: Array<{
-      attribute: { ... }
-      reason: { ... }
-    }>
-  }
-}
-```
-
-### `VersionMoved`
-
-Which version a write moved, and which one was in effect while it did.
-
-
-```ts
-type VersionMoved = {
-  valid_from: string
-  active_valid_from?: string
-}
-```
-
-### `InertOverride`
-
-One override that did not apply, and why.
-
-The same entry on both sides of the feature: a write reports the attributes in its body it did
-not store, and a resolved payload reports the stored overrides composition did not apply. Those
-are the same fact observed at two moments, so a client learns one 
-
-```ts
-type InertOverride = {
-  attribute: string
-  reason: "ATTRIBUTE_NOT_OVERRIDABLE" | "ATTRIBUTE_READONLY" | "ATTRIBUTE_HIDDEN" | "ATTRIBUTE_COMPUTED" | "ATTRIBUTE_UNDECLARED" | "TYPE_NOT_OVERRIDABLE" | "CAPABILITY_NOT_OVERRIDABLE"
-}
-```
-
-### `InertOverrideReason`
-
-Why one override did not apply.
-
-- `ATTRIBUTE_NOT_OVERRIDABLE`: the entity's schema declares the attribute but has not granted
-  it `overridable_attribute`. Granting the flag is an ordinary schema edit, which makes this
-  the reason most often worth acting on.
-- `ATTRIBUTE_READONLY`: the attribute i
-
-```ts
-type InertOverrideReason = "ATTRIBUTE_NOT_OVERRIDABLE" | "ATTRIBUTE_READONLY" | "ATTRIBUTE_HIDDEN" | "ATTRIBUTE_COMPUTED" | "ATTRIBUTE_UNDECLARED" | "TYPE_NOT_OVERRIDABLE" | "CAPABILITY_NOT_OVERRIDABLE"
-```
-
-### `DeletedVariant`
-
-```ts
-type DeletedVariant = {
-  variant_id: string
-  entity_id: string
-  schema: "product" | "price" | "coupon"
-  tuple_released: boolean
-  versions_deleted: number
-}
-```
-
-### `VariantVersion`
-
-One version of one variant: the attribute overrides it carries, the instant it takes effect,
-and the variant it belongs to.
-
-These are the version's **own** overrides, not the base entity overlaid with them — this is
-what an editing screen loads and saves, and what it edits is the overrides. Composi
-
-```ts
-type VariantVersion = {
-  variant_id: string
-  entity_id: string
-  schema: "product" | "price" | "coupon"
-  conditions: {
-    default: boolean
-  }
-  valid_from: string
-  values: Record<string, unknown>
-  _created_at: string
-  _updated_at: string
-  _revision: number
-}
-```
-
-### `WrittenVariantVersion`
-
-A version as a write left it, together with anything the write moved.
-
-
-```ts
-type WrittenVariantVersion = {
-  variant_id: string
-  entity_id: string
-  schema: "product" | "price" | "coupon"
-  conditions: {
-    default: boolean
-  }
-  valid_from: string
-  values: Record<string, unknown>
-  _created_at: string
-  _updated_at: string
-  _revision: number
-  warnings: Array<{
-    code: "VARIANT_COUNT_APPROACHING_CAP"
-    message: string
-    details: {
-      variant_count: { ... }
-      cap: { ... }
-    }
-  } | {
-    code: "ACTIVE_VERSION_CHANGED"
-    message: string
-    details: {
-      valid_from: { ... }
-      active_valid_from?: { ... }
-    }
-  } | {
-    code: "SUPERSEDED_VERSION_WRITTEN"
-    message: string
-    details: {
-      valid_from: { ... }
-      active_valid_from?: { ... }
-    }
-  } | {
-    code: "ATTRIBUTES_NOT_APPLIED"
-    message: string
-    details: {
-      attributes: { ... }
-    }
   }>
 }
 ```
 
-### `DeletedVariantVersion`
+### `VariantWriteWarning`
 
 ```ts
-type DeletedVariantVersion = {
-  variant_id: string
-  entity_id: string
-  schema: "product" | "price" | "coupon"
-  valid_from: string
-  warnings: Array<{
-    code: "VARIANT_COUNT_APPROACHING_CAP"
-    message: string
-    details: {
-      variant_count: { ... }
-      cap: { ... }
-    }
-  } | {
-    code: "ACTIVE_VERSION_CHANGED"
-    message: string
-    details: {
-      valid_from: { ... }
-      active_valid_from?: { ... }
-    }
-  } | {
-    code: "SUPERSEDED_VERSION_WRITTEN"
-    message: string
-    details: {
-      valid_from: { ... }
-      active_valid_from?: { ... }
-    }
-  } | {
-    code: "ATTRIBUTES_NOT_APPLIED"
-    message: string
-    details: {
-      attributes: { ... }
-    }
-  }>
-}
-```
-
-### `AppendVersionRequest`
-
-```ts
-type AppendVersionRequest = {
-  valid_from?: string
-  values: Record<string, unknown>
-  conditions?: Record<string, unknown>
-}
-```
-
-### `ReplaceVersionRequest`
-
-```ts
-type ReplaceVersionRequest = {
-  values: Record<string, unknown>
-  _revision: number
-  valid_from?: string
-  conditions?: Record<string, unknown>
-}
-```
-
-### `PatchVersionRequest`
-
-```ts
-type PatchVersionRequest = {
-  values: Record<string, unknown>
-  _revision: number
-  valid_from?: string
-  conditions?: Record<string, unknown>
-}
-```
-
-### `ListVariantsRequest`
-
-How to narrow and page a variant listing. Every property is optional, so `{}` is a valid body
-and asks for the first ten variants of the entity in `variant_id` order — the body itself is
-required, and an omitted one is a request-validation `400` rather than an unnarrowed page.
-
-`conditions` and `sea
-
-```ts
-type ListVariantsRequest = {
-  conditions?: Record<string, unknown>
-  search?: string
-  sort?: string
-  from?: number
-  size?: number
-  cursor?: string
-}
-```
-
-### `VariantTreeRequest`
-
-The variants list's request plus `as_of`, the instant each row's version is selected at.
-`size` is clamped at 100 here; every other shared property means what it means on the list.
-
-
-```ts
-type VariantTreeRequest = {
-  conditions?: Record<string, unknown>
-  search?: string
-  sort?: string
-  from?: number
-  size?: number
-  cursor?: string
-  as_of?: string
-}
-```
-
-### `VariantConditionFilter`
-
-Which pins a variant must carry to be listed: a flat map keyed by condition name, as the
-entity's schema declares them. A condition left out of the map is not filtered on at all.
-
-Each value is either an exact value, typed by its condition, or a single-operator predicate
-object — the same seven a re
-
-```ts
-type VariantConditionFilter = Record<string, unknown>
-```
-
-### `VariantList`
-
-```ts
-type VariantList = {
-  hits: number
-  results: Array<{
-    variant_id: string
-    entity_id: string
-    schema: "product" | "price" | "coupon"
-    conditions: {
-      default: { ... }
-    }
-  }>
-  next?: string
-}
-```
-
-### `VariantListRow`
-
-One variant as a listing reports it: which variant it is and what it pins.
-
-No `_revision` — a write re-reads its version through that version's own `GET` — and no
-`_inert_overrides`, since a listing reports what is stored and only `:resolve` honours the
-schema.
-
-
-```ts
-type VariantListRow = {
-  variant_id: string
-  entity_id: string
-  schema: "product" | "price" | "coupon"
-  conditions: {
-    default: boolean
-  }
-}
-```
-
-### `VariantTree`
-
-```ts
-type VariantTree = {
-  hits: number
-  results: Array<{
-    variant_id: string
-    entity_id: string
-    schema: "product" | "price" | "coupon"
-    conditions: {
-      default: { ... }
-    }
-    status: "active" | "scheduled"
-    version: {
-      variant_id: { ... }
-      entity_id: { ... }
-      schema: { ... }
-      conditions: { ... }
-      valid_from: { ... }
-      values: { ... }
-      _created_at: { ... }
-      _updated_at: { ... }
-    }
-  }>
-  next?: string
-}
-```
-
-### `VariantTreeRow`
-
-A listing row plus the one version the tree view shows for it, and the status saying which
-version that is.
-
-
-```ts
-type VariantTreeRow = {
-  variant_id: string
-  entity_id: string
-  schema: "product" | "price" | "coupon"
-  conditions: {
-    default: boolean
-  }
-  status: "active" | "scheduled"
-  version: {
-    variant_id: string
-    entity_id: string
-    schema: "product" | "price" | "coupon"
-    conditions: {
-      default: { ... }
-    }
-    valid_from: string
-    values: Record<string, unknown>
-    _created_at: string
-    _updated_at: string
-  }
-}
-```
-
-### `VariantTreeRowStatus`
-
-Whether a tree row's version is the one in effect at `as_of`, or one still ahead of it.
-
-Exactly two values, and every row has one: a variant always has at least one version, so
-either a version is in effect at `as_of` or every version of that variant is still to come.
-
-- `active`: `version` is the 
-
-```ts
-type VariantTreeRowStatus = "active" | "scheduled"
-```
-
-### `VariantVersionSnapshot`
-
-One version of one variant as a listing reports it: `VariantVersion` without `_revision`.
-
-The revision is missing on purpose. An editing screen re-reads the one version it is about to
-write through that version's own `GET`, which is strongly consistent, and writes with the
-revision it gets back.
-
-E
-
-```ts
-type VariantVersionSnapshot = {
-  variant_id: string
-  entity_id: string
-  schema: "product" | "price" | "coupon"
-  conditions: {
-    default: boolean
-  }
-  valid_from: string
-  values: Record<string, unknown>
-  _created_at: string
-  _updated_at: string
-}
-```
-
-### `VariantVersionList`
-
-```ts
-type VariantVersionList = {
-  results: Array<{
-    variant_id: string
-    entity_id: string
-    schema: "product" | "price" | "coupon"
-    conditions: {
-      default: { ... }
-    }
-    valid_from: string
-    values: Record<string, unknown>
-    _created_at: string
-    _updated_at: string
-  }>
-  next?: string
-}
-```
-
-### `BatchUpsertVariantsRequest`
-
-A batch of variant writes under one schema, each item naming the entity it writes to.
-
-
-```ts
-type BatchUpsertVariantsRequest = {
-  correlation_id?: string
-  items: Array<{
-    entity_id: string
-    conditions?: Record<string, unknown>
-    default?: boolean
-    valid_from?: string
-    values: Record<string, unknown>
-  }>
-}
-```
-
-### `BatchUpsertItem`
-
-One variant write: the entity it belongs to, the situation it applies to, and the values it
-carries — the single-item create's body plus `entity_id`. The two differ on `conditions`: on
-a create an existing tuple is `TUPLE_CONFLICT`, and here it is a version appended to the
-variant already holding it
-
-```ts
-type BatchUpsertItem = {
-  entity_id: string
-  conditions?: Record<string, unknown>
-  default?: boolean
-  valid_from?: string
-  values: Record<string, unknown>
-}
-```
-
-### `BatchDeleteVariantsRequest`
-
-A batch of variant and version deletes under one schema, each item naming the entity it
-removes from.
-
-
-```ts
-type BatchDeleteVariantsRequest = {
-  correlation_id?: string
-  items: Array<{
-    entity_id: string
-    variant_id: string
-    valid_from?: string
-  } | {
-    entity_id: string
-    conditions?: Record<string, unknown>
-    default?: boolean
-    valid_from?: string
-  }>
-}
-```
-
-### `BatchDeleteItem`
-
-One delete: the variant, addressed by id or by the condition tuple it pins, and optionally
-the one version of it to remove.
-
-Exactly one of the two forms. An item carrying both a `variant_id` and `conditions` matches
-neither branch and is an envelope `400`, since the request validator rejects the bo
-
-```ts
-type BatchDeleteItem = {
-  entity_id: string
-  variant_id: string
-  valid_from?: string
-} | {
-  entity_id: string
-  conditions?: Record<string, unknown>
-  default?: boolean
-  valid_from?: string
-}
-```
-
-### `BatchDeleteByVariantId`
-
-A delete addressing its variant by id — the form a cleanup pass uses after the schema has
-drifted, since a tuple naming a condition the schema no longer declares addresses nothing.
-
-
-```ts
-type BatchDeleteByVariantId = {
-  entity_id: string
-  variant_id: string
-  valid_from?: string
+type VariantWriteWarning = {
+  code: "VARIANT_COUNT_APPROACHING_CAP"
+  message: string
+  variant_count: number
+  cap: number
 }
 ```
 
-### `BatchDeleteByConditions`
-
-A delete addressing its variant by the situation it applies to — the form an importer uses
-when it knows the source rows rather than the ids they produced.
-
-`conditions` is optional because the entity's fallback variant pins nothing: an item
-addressing it sends `default: true` and no `conditions`, e
+### `DeletedVariant`
 
 ```ts
-type BatchDeleteByConditions = {
+type DeletedVariant = {
+  variant_id: string
   entity_id: string
-  conditions?: Record<string, unknown>
-  default?: boolean
-  valid_from?: string
+  schema: "product" | "price" | "coupon"
+  tuple_released: boolean
+  versions_deleted: number
 }
 ```
 
-### `BatchUpsertResult`
+### `VariantVersion`
 
-What a batch upsert did: one entry per item, in request order, and a count per outcome.
+One version of one variant: the attribute overrides it carries, the instant it takes effect,
+and the variant it belongs to.
 
+These are the version's **own** overrides, not the base entity overlaid with them — this is
+what an editing screen loads and saves, and what it edits is the overrides. Composi
 
 ```ts
-type BatchUpsertResult = {
-  correlation_id?: string
-  counts: {
-    variant_created: number
-    version_created: number
-    updated: number
-    skipped: number
-    error: number
+type VariantVersion = {
+  variant_id: string
+  entity_id: string
+  schema: "product" | "price" | "coupon"
+  conditions: {
+    default: boolean
   }
-  results: Array<{
-    outcome: "variant_created" | "version_created" | "updated" | "skipped" | "error"
-    entity_id: string
-    variant_id?: string
-    valid_from?: string
-    warnings: Array<{
-      code: { ... }
-      message: { ... }
-      details: { ... }
-    } | {
-      code: { ... }
-      message: { ... }
-      details: { ... }
-    } | {
-      code: { ... }
-      message: { ... }
-      details: { ... }
-    } | {
-      code: { ... }
-      message: { ... }
-      details: { ... }
-    }>
-    error?: {
-      message: { ... }
-      status?: { ... }
-      cause?: { ... }
-      error?: { ... }
-    }
-  }>
+  valid_from: string
+  values: Record<string, unknown>
+  _created_at: string
+  _updated_at: string
+  _revision: number
 }
 ```
 
-### `BatchDeleteResult`
+### `WrittenVariantVersion`
 
-What a batch delete did: one entry per item, in request order, and a count per outcome.
+A version as a write left it, together with anything the write moved.
 
 
 ```ts
-type BatchDeleteResult = {
-  correlation_id?: string
-  counts: {
-    deleted: number
-    skipped: number
-    error: number
+type WrittenVariantVersion = {
+  variant_id: string
+  entity_id: string
+  schema: "product" | "price" | "coupon"
+  conditions: {
+    default: boolean
   }
-  results: Array<{
-    outcome: "deleted" | "skipped" | "error"
-    entity_id: string
-    variant_id?: string
-    valid_from?: string
-    warnings: Array<{
-      code: { ... }
-      message: { ... }
-      details: { ... }
-    } | {
-      code: { ... }
-      message: { ... }
-      details: { ... }
-    } | {
-      code: { ... }
-      message: { ... }
-      details: { ... }
-    } | {
-      code: { ... }
-      message: { ... }
-      details: { ... }
-    }>
-    error?: {
-      message: { ... }
-      status?: { ... }
-      cause?: { ... }
-      error?: { ... }
-    }
+  valid_from: string
+  values: Record<string, unknown>
+  _created_at: string
+  _updated_at: string
+  _revision: number
+  warnings: Array<{
+    code: "ACTIVE_VERSION_REPLACED" | "SUPERSEDED_VERSION_WRITTEN"
+    message: string
+    valid_from: string
+    active_valid_from?: string
   }>
 }
 ```
 
-### `BatchUpsertOutcome`
-
-What one upsert item did, derived from what was stored rather than from a mode the caller
-declared.
-
-- `variant_created`: the condition tuple was unknown, so a variant and its first version were
-  created. The entry's `variant_id` is the id an order or contract pins.
-- `version_created`: the tuple w
-
-```ts
-type BatchUpsertOutcome = "variant_created" | "version_created" | "updated" | "skipped" | "error"
-```
-
-### `BatchDeleteOutcome`
-
-What one delete item did.
-
-- `deleted`: the variant, or the one version the item named, is gone.
-- `skipped`: the item addressed nothing — **the variant or the version**, never the entity. An
-  entity that cannot answer the item is an `error` carrying `ENTITY_NOT_FOUND`,
-  `ENTITY_TYPE_MISMATCH` or 
+### `DeletedVariantVersion`
 
 ```ts
-type BatchDeleteOutcome = "deleted" | "skipped" | "error"
+type DeletedVariantVersion = {
+  variant_id: string
+  entity_id: string
+  schema: "product" | "price" | "coupon"
+  valid_from: string
+  warnings: Array<{
+    code: "ACTIVE_VERSION_REPLACED" | "SUPERSEDED_VERSION_WRITTEN"
+    message: string
+    valid_from: string
+    active_valid_from?: string
+  }>
+}
 ```
 
-### `BatchUpsertCounts`
+### `VersionWriteWarning`
 
-How many items reached each outcome. Keyed by exactly the values of `BatchUpsertOutcome`, all
-of them present, so a logger reads a count without `?? 0`.
-
-**They sum to the length of `results`.** There is no `total`.
+Something a version write moved. A version write is never refused for being late — backdating a
+version, and editing or deleting one that has already been superseded, are both accepted — so
+what a caller gets instead is a warning naming exactly what changed. One write can carry both
+codes.
 
 
 ```ts
-type BatchUpsertCounts = {
-  variant_created: number
-  version_created: number
-  updated: number
-  skipped: number
-  error: number
+type VersionWriteWarning = {
+  code: "ACTIVE_VERSION_REPLACED" | "SUPERSEDED_VERSION_WRITTEN"
+  message: string
+  valid_from: string
+  active_valid_from?: string
 }
 ```
 
-### `BatchDeleteCounts`
-
-How many items reached each outcome. Keyed by exactly the values of `BatchDeleteOutcome`, all
-of them present, and summing to the length of `results`. No `total`.
-
+### `AppendVersionRequest`
 
 ```ts
-type BatchDeleteCounts = {
-  deleted: number
-  skipped: number
-  error: number
+type AppendVersionRequest = {
+  valid_from?: string
+  values: Record<string, unknown>
+  conditions?: Record<string, unknown>
 }
 ```
 
-### `BatchUpsertResultEntry`
-
-What one upsert item did, and anything worth knowing about it.
-
-**It carries nothing else.** Position in `results` is the contract, so no entry carries an
-index; nothing the caller sent is echoed back beyond `entity_id`; and there is no `_revision`
-— an editing screen re-reads the version it is abou
+### `ReplaceVersionRequest`
 
 ```ts
-type BatchUpsertResultEntry = {
-  outcome: "variant_created" | "version_created" | "updated" | "skipped" | "error"
-  entity_id: string
-  variant_id?: string
+type ReplaceVersionRequest = {
+  values: Record<string, unknown>
+  _revision: number
   valid_from?: string
-  warnings: Array<{
-    code: "VARIANT_COUNT_APPROACHING_CAP"
-    message: string
-    details: {
-      variant_count: { ... }
-      cap: { ... }
-    }
-  } | {
-    code: "ACTIVE_VERSION_CHANGED"
-    message: string
-    details: {
-      valid_from: { ... }
-      active_valid_from?: { ... }
-    }
-  } | {
-    code: "SUPERSEDED_VERSION_WRITTEN"
-    message: string
-    details: {
-      valid_from: { ... }
-      active_valid_from?: { ... }
-    }
-  } | {
-    code: "ATTRIBUTES_NOT_APPLIED"
-    message: string
-    details: {
-      attributes: { ... }
-    }
-  }>
-  error?: {
-    message: string
-    status?: number
-    cause?: string
-    error?: string | Record<string, unknown>[]
-  }
+  conditions?: Record<string, unknown>
 }
 ```
 
-### `BatchDeleteResultEntry`
-
-What one delete item did, and anything worth knowing about it.
-
-The same six properties as a batch upsert entry, and it carries nothing else.
-
+### `PatchVersionRequest`
 
 ```ts
-type BatchDeleteResultEntry = {
-  outcome: "deleted" | "skipped" | "error"
-  entity_id: string
-  variant_id?: string
+type PatchVersionRequest = {
+  values: Record<string, unknown>
+  _revision: number
   valid_from?: string
-  warnings: Array<{
-    code: "VARIANT_COUNT_APPROACHING_CAP"
-    message: string
-    details: {
-      variant_count: { ... }
-      cap: { ... }
-    }
-  } | {
-    code: "ACTIVE_VERSION_CHANGED"
-    message: string
-    details: {
-      valid_from: { ... }
-      active_valid_from?: { ... }
-    }
-  } | {
-    code: "SUPERSEDED_VERSION_WRITTEN"
-    message: string
-    details: {
-      valid_from: { ... }
-      active_valid_from?: { ... }
-    }
-  } | {
-    code: "ATTRIBUTES_NOT_APPLIED"
-    message: string
-    details: {
-      attributes: { ... }
-    }
-  }>
-  error?: {
-    message: string
-    status?: number
-    cause?: string
-    error?: string | Record<string, unknown>[]
-  }
+  conditions?: Record<string, unknown>
 }
 ```
 
@@ -3978,32 +2813,21 @@ type Error = {
 }
 ```
 
-### `ReportedError`
-
-The `error` field of an error response: the message, or — where the request itself failed
-validation before any handler ran — the validation errors themselves, which those 400s put
-here in place of a string.
-
-A conditional-pricing operation answers a body its schema rejects with the list, and
-everyt
-
-```ts
-type ReportedError = string | Record<string, unknown>[]
-```
-
 ### `ConditionalPricingError`
 
-An error from a conditional-pricing operation, carrying a machine-readable `code` from the
-conditional-pricing vocabulary plus the structured data that code explains, so a client can
-branch on the kind of failure rather than parse the message.
-Referenced only by the operations that emit these codes;
+An error from a conditional-pricing operation, carrying a machine-readable `code`
+from the conditional-pricing vocabulary plus any structured data about the failure,
+so a client can branch on the kind of failure rather than parse the message.
+Referenced only by the operations that emit these codes; 
 
 ```ts
 type ConditionalPricingError = {
   message: string
   status?: number
   cause?: string
-  error?: string | Record<string, unknown>[]
+  error?: string
+  code?: "NOT_FOUND" | "AMBIGUOUS_RESOLUTION" | "TUPLE_CONFLICT" | "VERSION_CONFLICT" | "CONDITION_UNDEFINED" | "OPERATOR_UNSUPPORTED" | "CONTEXT_FORMAT_INVALID" | "CONDITION_VALUE_INVALID" | "TOO_MANY_MATCHES" | "WRITE_CONFLICT"
+  details?: Record<string, unknown>
 }
 ```
 
@@ -4078,7 +2902,6 @@ type Product = {
       _tags?: { ... }
     }>
   }
-  is_conditional?: boolean
   _availability_files?: Array<{
     _id: string
     filename: string
@@ -4272,7 +3095,6 @@ type Order = {
       product_images?: { ... }
       product_downloads?: { ... }
       price_options?: { ... }
-      is_conditional?: { ... }
       _availability_files?: { ... }
       _id?: { ... }
       _title?: { ... }
@@ -4283,6 +3105,7 @@ type Order = {
   } | {
     metadata?: Array<{
       key?: { ... }
+      value?: { ... }
   // ...
 }
 ```
@@ -4485,6 +3308,17 @@ type ExternalFeeMetadata = {
       unit_amount_decimal?: { ... }
     }>
   }
+  inputs?: {
+    type?: "power" | "gas"
+    consumptionHT?: number
+    consumptionNT?: number
+    consumptionType?: "household" | "heating_pump" | "night_storage_heating" | "night_storage_heating_common_meter"
+    zipCode?: string
+    city?: string
+    providerId?: string
+    billingPeriod?: "weekly" | "monthly" | "every_quarter" | "every_6_months" | "yearly" | "one_time"
+    referenceDate?: string // date
+  }
   _meta?: {
     signature: string
     timestamp: number
@@ -4654,7 +3488,6 @@ type CatalogSearchResult = {
     price_options?: {
       $relation?: { ... }
     }
-    is_conditional?: boolean
     _availability_files?: Array<{
       _id: { ... }
       filename: { ... }
@@ -4699,7 +3532,6 @@ type CatalogSearchResult = {
     fixed_value_currency?: string
     cashback_period?: "0" | "12"
     active?: boolean
-    is_conditional?: boolean
     requires_promo_code?: boolean
   }>
 }
@@ -4841,6 +3673,7 @@ type ComputePriceParamsBase = {
   association_id?: string
   billing_period?: "weekly" | "monthly" | "every_quarter" | "every_6_months" | "yearly" | "one_time"
   reference_date?: string // date
+  city?: string
 }
 ```
 
@@ -4856,6 +3689,7 @@ type ComputePriceParamsPower = {
   association_id?: string
   billing_period?: "weekly" | "monthly" | "every_quarter" | "every_6_months" | "yearly" | "one_time"
   reference_date?: string // date
+  city?: string
   type: "power"
   meter_type?: "classic" | "smart" | "digital"
 }
@@ -4873,6 +3707,7 @@ type ComputePriceParamsGas = {
   association_id?: string
   billing_period?: "weekly" | "monthly" | "every_quarter" | "every_6_months" | "yearly" | "one_time"
   reference_date?: string // date
+  city?: string
   type: "gas"
   concession_type?: "standard" | "special"
 }
@@ -4916,6 +3751,7 @@ type ComputePriceParams = {
   association_id?: string
   billing_period?: "weekly" | "monthly" | "every_quarter" | "every_6_months" | "yearly" | "one_time"
   reference_date?: string // date
+  city?: string
   type: "power"
   meter_type?: "classic" | "smart" | "digital"
 } | {
@@ -4927,6 +3763,7 @@ type ComputePriceParams = {
   association_id?: string
   billing_period?: "weekly" | "monthly" | "every_quarter" | "every_6_months" | "yearly" | "one_time"
   reference_date?: string // date
+  city?: string
   type: "gas"
   concession_type?: "standard" | "special"
 }
@@ -5054,6 +3891,17 @@ type ComputePriceResult = {
       unit_amount_decimal?: { ... }
     }>
   }
+  inputs?: {
+    type?: "power" | "gas"
+    consumptionHT?: number
+    consumptionNT?: number
+    consumptionType?: "household" | "heating_pump" | "night_storage_heating" | "night_storage_heating_common_meter"
+    zipCode?: string
+    city?: string
+    providerId?: string
+    billingPeriod?: "weekly" | "monthly" | "every_quarter" | "every_6_months" | "yearly" | "one_time"
+    referenceDate?: string // date
+  }
   _meta?: {
     signature: string
     timestamp: number
@@ -5061,6 +3909,24 @@ type ComputePriceResult = {
 }
 ```
 
+### `ComputePriceInputs`
+
+Echo of the request parameters used to compute the price, in the caller-facing shape.
+
+```ts
+type ComputePriceInputs = {
+  type?: "power" | "gas"
+  consumptionHT?: number
+  consumptionNT?: number
+  consumptionType?: "household" | "heating_pump" | "night_storage_heating" | "night_storage_heating_common_meter"
+  zipCode?: string
+  city?: string
+  providerId?: string
+  billingPeriod?: "weekly" | "monthly" | "every_quarter" | "every_6_months" | "yearly" | "one_time"
+  referenceDate?: string // date
+}
+```
+
 ### `SpotMarketBiddingZone`
 
 The bidding zone for a spot market price.
@@ -5505,6 +4371,7 @@ type CartDto = {
       currency: { ... }
       billing_period: { ... }
       breakdown: { ... }
+      inputs?: { ... }
       _meta?: { ... }
     }
     external_location_metadata?: {
@@ -5516,7 +4383,6 @@ type CartDto = {
     }
     external_price_metadata?: {
       market: { ... }
-      bidding_zone: { ... }
   // ...
 }
 ```
@@ -5828,7 +4694,6 @@ type BasePriceItemCommon = {
     price_options?: {
       $relation?: { ... }
     }
-    is_conditional?: boolean
     _availability_files?: Array<{
       _id: { ... }
       filename: { ... }
@@ -5881,6 +4746,17 @@ type PriceItemDtoUnion = {
       variable_ht?: { ... }
       variable_nt?: { ... }
     }
+    inputs?: {
+      type?: { ... }
+      consumptionHT?: { ... }
+      consumptionNT?: { ... }
+      consumptionType?: { ... }
+      zipCode?: { ... }
+      city?: { ... }
+      providerId?: { ... }
+      billingPeriod?: { ... }
+      referenceDate?: { ... }
+    }
     _meta?: {
       signature: { ... }
       timestamp: { ... }
@@ -5942,17 +4818,6 @@ type PriceItemDtoUnion = {
     amount_total?: number
     unit_amount_gross?: number
     unit_amount_net?: number
-    amount_tax?: number
-    total_details?: {
-      amount_shipping?: { ... }
-      amount_tax?: { ... }
-      breakdown?: { ... }
-    }
-    currency?: string
-    redeemed_promos?: Array<{
-      code: { ... }
-      coupons: { ... }
-    }>
   // ...
 }
 ```
@@ -5990,6 +4855,17 @@ type PriceItemsDto = Array<{
       variable_ht?: { ... }
       variable_nt?: { ... }
     }
+    inputs?: {
+      type?: { ... }
+      consumptionHT?: { ... }
+      consumptionNT?: { ... }
+      consumptionType?: { ... }
+      zipCode?: { ... }
+      city?: { ... }
+      providerId?: { ... }
+      billingPeriod?: { ... }
+      referenceDate?: { ... }
+    }
     _meta?: {
       signature: { ... }
       timestamp: { ... }
@@ -6051,17 +4927,6 @@ type PriceItemsDto = Array<{
     amount_total?: number
     unit_amount_gross?: number
     unit_amount_net?: number
-    amount_tax?: number
-    total_details?: {
-      amount_shipping?: { ... }
-      amount_tax?: { ... }
-      breakdown?: { ... }
-    }
-    currency?: string
-    redeemed_promos?: Array<{
-      code: { ... }
-      coupons: { ... }
-    }>
   // ...
 }
 ```
@@ -6134,7 +4999,6 @@ type BasePriceItemDto = {
     price_options?: {
       $relation?: { ... }
     }
-    is_conditional?: boolean
     _availability_files?: Array<{
       _id: { ... }
       filename: { ... }
@@ -6189,6 +5053,17 @@ type PriceItemDto = {
       variable_ht?: { ... }
       variable_nt?: { ... }
     }
+    inputs?: {
+      type?: { ... }
+      consumptionHT?: { ... }
+      consumptionNT?: { ... }
+      consumptionType?: { ... }
+      zipCode?: { ... }
+      city?: { ... }
+      providerId?: { ... }
+      billingPeriod?: { ... }
+      referenceDate?: { ... }
+    }
     _meta?: {
       signature: { ... }
       timestamp: { ... }
@@ -6250,17 +5125,6 @@ type PriceItemDto = {
     amount_total?: number
     unit_amount_gross?: number
     unit_amount_net?: number
-    amount_tax?: number
-    total_details?: {
-      amount_shipping?: { ... }
-      amount_tax?: { ... }
-      breakdown?: { ... }
-    }
-    currency?: string
-    redeemed_promos?: Array<{
-      code: { ... }
-      coupons: { ... }
-    }>
   // ...
 }
 ```
@@ -6298,6 +5162,17 @@ type CompositePriceItemDto = {
       variable_ht?: { ... }
       variable_nt?: { ... }
     }
+    inputs?: {
+      type?: { ... }
+      consumptionHT?: { ... }
+      consumptionNT?: { ... }
+      consumptionType?: { ... }
+      zipCode?: { ... }
+      city?: { ... }
+      providerId?: { ... }
+      billingPeriod?: { ... }
+      referenceDate?: { ... }
+    }
     _meta?: {
       signature: { ... }
       timestamp: { ... }
@@ -6359,17 +5234,6 @@ type CompositePriceItemDto = {
     amount_total?: number
     unit_amount_gross?: number
     unit_amount_net?: number
-    amount_tax?: number
-    total_details?: {
-      amount_shipping?: { ... }
-      amount_tax?: { ... }
-      breakdown?: { ... }
-    }
-    currency?: string
-    redeemed_promos?: Array<{
-      code: { ... }
-      coupons: { ... }
-    }>
   // ...
 }
 ```
@@ -6501,6 +5365,7 @@ type OrderPayload = {
       currency: { ... }
       billing_period: { ... }
       breakdown: { ... }
+      inputs?: { ... }
       _meta?: { ... }
     }
     external_location_metadata?: {
@@ -6568,7 +5433,6 @@ type OrderPayload = {
       fixed_value_currency?: { ... }
       cashback_period?: { ... }
       active?: { ... }
-      is_conditional?: { ... }
       requires_promo_code?: { ... }
     }>
     type?: "one_time" | "recurring"
@@ -6648,7 +5512,6 @@ type PriceItems = Array<{
     price_options?: {
       $relation?: { ... }
     }
-    is_conditional?: boolean
     _availability_files?: Array<{
       _id: { ... }
       filename: { ... }
@@ -6685,6 +5548,7 @@ type PriceItems = Array<{
     value?: number
     metadata?: Record<string, string>
   }>
+  is_tax_inclusive?: boolean
   // ...
 }
 ```
@@ -6757,7 +5621,6 @@ type CompositePriceItem = {
     price_options?: {
       $relation?: { ... }
     }
-    is_conditional?: boolean
     _availability_files?: Array<{
       _id: { ... }
       filename: { ... }
@@ -6847,7 +5710,6 @@ type BasePriceItem = {
     price_options?: {
       $relation?: { ... }
     }
-    is_conditional?: boolean
     _availability_files?: Array<{
       _id: { ... }
       filename: { ... }
@@ -6997,7 +5859,6 @@ type PriceItem = {
     price_options?: {
       $relation?: { ... }
     }
-    is_conditional?: boolean
     _availability_files?: Array<{
       _id: { ... }
       filename: { ... }
@@ -7214,7 +6075,6 @@ type PricingDetails = {
       product_images?: { ... }
       product_downloads?: { ... }
       price_options?: { ... }
-      is_conditional?: { ... }
       _availability_files?: { ... }
       _id?: { ... }
       _title?: { ... }
@@ -7252,7 +6112,6 @@ type PricingDetails = {
       product_images?: { ... }
       product_downloads?: { ... }
       price_options?: { ... }
-      is_conditional?: { ... }
       _availability_files?: { ... }
       _id?: { ... }
       _title?: { ... }
@@ -7283,6 +6142,8 @@ type PricingDetails = {
       _id: { ... }
       _title: { ... }
       _org: { ... }
+      _schema: { ... }
+      _tags?: { ... }
   // ...
 }
 ```
@@ -7311,7 +6172,6 @@ type PromoCodeValidationResponse = {
     fixed_value_currency?: string
     cashback_period?: "0" | "12"
     active?: boolean
-    is_conditional?: boolean
     requires_promo_code?: boolean
   }>
 }
@@ -7353,7 +6213,6 @@ type PricingDetailsResponse = {
       product_images?: { ... }
       product_downloads?: { ... }
       price_options?: { ... }
-      is_conditional?: { ... }
       _availability_files?: { ... }
       _id?: { ... }
       _title?: { ... }
@@ -7391,7 +6250,6 @@ type PricingDetailsResponse = {
       product_images?: { ... }
       product_downloads?: { ... }
       price_options?: { ... }
-      is_conditional?: { ... }
       _availability_files?: { ... }
       _id?: { ... }
       _title?: { ... }
@@ -7422,6 +6280,8 @@ type PricingDetailsResponse = {
       _id: { ... }
       _title: { ... }
       _org: { ... }
+      _schema: { ... }
+      _tags?: { ... }
   // ...
 }
 ```
@@ -7644,7 +6504,6 @@ type BaseCouponCommon = {
   fixed_value_currency?: string
   cashback_period?: "0" | "12"
   active?: boolean
-  is_conditional?: boolean
   requires_promo_code?: boolean
 }
 ```
@@ -7672,7 +6531,6 @@ type CouponWithoutPromoCodes = {
   fixed_value_currency?: string
   cashback_period?: "0" | "12"
   active?: boolean
-  is_conditional?: boolean
   requires_promo_code?: boolean
 }
 ```
@@ -7700,7 +6558,6 @@ type Coupon = {
   fixed_value_currency?: string
   cashback_period?: "0" | "12"
   active?: boolean
-  is_conditional?: boolean
   requires_promo_code?: boolean
 }
 ```
@@ -7726,7 +6583,6 @@ type CouponItem = {
   fixed_value_currency?: string
   cashback_period?: "0" | "12"
   active?: boolean
-  is_conditional?: boolean
   requires_promo_code?: boolean
 }
 ```
@@ -7765,7 +6621,6 @@ type RedeemedPromo = {
     fixed_value_currency?: string
     cashback_period?: "0" | "12"
     active?: boolean
-    is_conditional?: boolean
     requires_promo_code?: boolean
   }>
 }
@@ -8235,6 +7090,31 @@ type ProductRecommendationResponse = {
     _created_at: string // date-time
     _updated_at: string // date-time
   }>
+  source?: {
+    item?: {
+      metadata?: { ... }
+      quantity?: { ... }
+      product_id?: { ... }
+      price_id?: { ... }
+      description?: { ... }
+      product_description?: { ... }
+      product_name?: { ... }
+      price_mappings?: { ... }
+      is_tax_inclusive?: { ... }
+      _product?: { ... }
+    } | {
+      metadata?: { ... }
+      quantity?: { ... }
+      product_id?: { ... }
+      price_id?: { ... }
+      description?: { ... }
+      product_description?: { ... }
+      product_name?: { ... }
+      price_mappings?: { ... }
+      is_tax_inclusive?: { ... }
+      _product?: { ... }
+    }
+  }
 }
 ```