@epilot/pricing-client 3.61.0 → 3.62.0

package/dist/openapi.json

@@ -595,11 +595,11 @@
             }
           },
           "400": {
-            "description": "Invalid payload",
+            "description": "`CATALOG_REFERENCE_MISSING`, `CATALOG_REFERENCE_UNRESOLVABLE`: see\n`CatalogReferenceErrorCode`. References are not verified on this authenticated route.\nOther refusals carry no `code`.\n",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Error"
+                  "$ref": "#/components/schemas/CatalogReferenceError"
                 }
               }
             }
@@ -855,11 +855,11 @@
             }
           },
           "400": {
-            "description": "Invalid payload",
+            "description": "`CATALOG_REFERENCE_MISSING`, `CATALOG_REFERENCE_UNRESOLVABLE`: see\n`CatalogReferenceErrorCode`. References are not verified on this authenticated route.\nOther refusals carry no `code`.\n",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Error"
+                  "$ref": "#/components/schemas/CatalogReferenceError"
                 }
               }
             }
@@ -984,11 +984,11 @@
             }
           },
           "400": {
-            "description": "Invalid payload",
+            "description": "`CATALOG_REFERENCE_MISSING`, `CATALOG_REFERENCE_UNRESOLVABLE`: see\n`CatalogReferenceErrorCode`. References are not verified on this authenticated route.\nOther refusals carry no `code`.\n",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Error"
+                  "$ref": "#/components/schemas/CatalogReferenceError"
                 }
               }
             }
@@ -1053,11 +1053,11 @@
             }
           },
           "400": {
-            "description": "Invalid payload",
+            "description": "`CATALOG_REFERENCE_MISSING`, `CATALOG_REFERENCE_SIGNATURE_INVALID`,\n`CATALOG_REFERENCE_UNRESOLVABLE`: see `CatalogReferenceErrorCode`. Every reference must\nverify on this public route. Other refusals carry no `code`.\n",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Error"
+                  "$ref": "#/components/schemas/CatalogReferenceError"
                 }
               }
             }
@@ -1174,6 +1174,211 @@
         }
       }
     },
+    "/v2/public/catalog": {
+      "post": {
+        "description": "Returns the products and prices a journey block shows as catalog pairs, each member resolved\nfor its own entity type's context at `as_of`. A pair carries the product, one of its prices, the coupons that apply,\nand a signed `catalog_reference`. Line items carry that reference to checkout unchanged, and\ncheckout prices from it.\n\nConditional entities resolve as on `POST /v1/conditional-pricing:resolve`. An organization\nthat has not opted in gets base entities, not an error. A member matching several variants\nyields one pair per variant, and an entry without `price_id` yields one pair per price of\nthe product. Members that match nothing or are inactive are left out. Ids that find no\nentity, or an entity of another type than the entry asked for, are reported in `warnings`.\n",
+        "operationId": "$resolveCatalog",
+        "summary": "$resolveCatalog",
+        "security": [
+          {
+            "EpilotPublicAuth": []
+          }
+        ],
+        "tags": [
+          "Catalog API"
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ResolveCatalogRequest"
+              },
+              "examples": {
+                "A block of three tiles at a delivery address": {
+                  "summary": "Two priced entries and one that lets the product name its prices",
+                  "value": {
+                    "entries": [
+                      {
+                        "product_id": "product-pv-2027",
+                        "price_id": "price-sp26d1yo"
+                      },
+                      {
+                        "product_id": "product-heatpump-2027",
+                        "price_id": "price-retired"
+                      },
+                      {
+                        "product_id": "product-wallbox-2027"
+                      }
+                    ],
+                    "context": {
+                      "product": {
+                        "postal_code": "46045",
+                        "channel": "direct"
+                      },
+                      "price": {
+                        "postal_code": "46045"
+                      }
+                    },
+                    "as_of": "2026-12-20T10:15:00Z"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The pairs to show, unordered, and the entries whose ids found nothing or the wrong\ntype. `warnings` is always present and empty in the ordinary case.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ResolveCatalogResult"
+                },
+                "examples": {
+                  "A resolved price beside a classic product, and an entry that found nothing": {
+                    "summary": "The product served as stored, the price resolved to its variant, the reference signed, and a retired price reported rather than refused",
+                    "value": {
+                      "pairs": [
+                        {
+                          "product": {
+                            "_id": "product-pv-2027",
+                            "_schema": "product",
+                            "_title": "Solar Panel with Battery Storage",
+                            "name": "Solar Panel with Battery Storage",
+                            "active": true,
+                            "is_conditional": false,
+                            "price_options": [
+                              {
+                                "_id": "price-sp26d1yo",
+                                "_schema": "price",
+                                "_title": "Solar Panel Module",
+                                "active": true,
+                                "is_conditional": true,
+                                "is_composite_price": false,
+                                "type": "one_time",
+                                "pricing_model": "per_unit",
+                                "$relation": {
+                                  "entity_id": "price-sp26d1yo",
+                                  "attribute": "price_options"
+                                }
+                              }
+                            ]
+                          },
+                          "price": {
+                            "_id": "price-sp26d1yo",
+                            "_schema": "price",
+                            "_title": "Solar Panel Module",
+                            "_variant_id": "var-46045",
+                            "_version_valid_from": "2027-01-01T00:00:00.000Z",
+                            "_conditions": {
+                              "postal_code": "46045",
+                              "default": false
+                            },
+                            "_inert_overrides": [],
+                            "active": true,
+                            "is_conditional": true,
+                            "is_composite_price": false,
+                            "type": "one_time",
+                            "pricing_model": "per_unit",
+                            "unit_amount": 2499,
+                            "unit_amount_decimal": "24.99",
+                            "unit_amount_currency": "EUR"
+                          },
+                          "coupons": [
+                            {
+                              "_id": "0f8c4852-23fa-4a64-a2f3-88702335f094",
+                              "_schema": "coupon",
+                              "_org": "739224",
+                              "_title": "Winter discount",
+                              "_created_at": "2026-10-01T09:00:00.000Z",
+                              "_updated_at": "2026-10-01T09:00:00.000Z",
+                              "name": "Winter discount",
+                              "type": "percentage",
+                              "category": "discount",
+                              "percentage_value": "10",
+                              "active": true,
+                              "prices": {
+                                "$relation": [
+                                  {
+                                    "entity_id": "price-sp26d1yo",
+                                    "_schema": "price"
+                                  }
+                                ]
+                              }
+                            }
+                          ],
+                          "catalog_reference": {
+                            "product": {
+                              "id": "product-pv-2027"
+                            },
+                            "price": {
+                              "id": "price-sp26d1yo",
+                              "variant": "var-46045"
+                            },
+                            "coupons": [
+                              {
+                                "id": "0f8c4852-23fa-4a64-a2f3-88702335f094"
+                              }
+                            ],
+                            "as_of": "2026-12-20T10:15:00.000Z",
+                            "_meta": {
+                              "timestamp": 1797000000000,
+                              "signature": "c3ab8ff137"
+                            }
+                          }
+                        }
+                      ],
+                      "warnings": [
+                        {
+                          "code": "CATALOG_ENTRY_NOT_FOUND",
+                          "message": "The entry names a price that does not exist",
+                          "details": {
+                            "product_id": "product-heatpump-2027",
+                            "price_id": "price-retired",
+                            "missing": "price"
+                          }
+                        },
+                        {
+                          "code": "CATALOG_ENTRY_TYPE_MISMATCH",
+                          "message": "The entry's price id names a product",
+                          "details": {
+                            "product_id": "product-heatpump-2027",
+                            "price_id": "product-tariff-2027",
+                            "mismatched": "price",
+                            "actual_schema": "product"
+                          }
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`CONDITION_UNDEFINED`, `OPERATOR_UNSUPPORTED`, `CONTEXT_FORMAT_INVALID`,\n`DEFAULT_MARKER_RESERVED`: an entity type's context is refused against that type's schema\nas the authenticated resolve refuses it.\n\n`TOO_MANY_MATCHES`: a member matches more variants than the authenticated resolve's cap\nof 100. The whole request is refused rather than serving a truncated block.\n\n`VALID_FROM_INVALID`: `as_of` is not an instant this operation can read.\n\nA body with no entries, more than 100, an entry without `product_id`, or a context keyed\nby anything but `product`, `price` or `coupon` fails validation and carries no `code`.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConditionalPricingError"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "`CONDITION_UNREADABLE`: a schema this request touches declares a condition in a way this\ndeploy cannot read. The whole request is refused rather than serving prices without\ntheir products.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConditionalPricingError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/public/validate-promo-codes": {
       "post": {
         "description": "Validate a list of promo codes against a list of coupons",
@@ -5929,7 +6134,9 @@
       },
       "ResolveContext": {
         "type": "object",
-        "additionalProperties": true,
+        "additionalProperties": {
+          "$ref": "#/components/schemas/ContextConditionValue"
+        },
         "description": "The situation to resolve for: a flat map keyed by condition name. A condition left out\nmatches only variants that leave it unpinned; an empty map therefore returns the `default`\nvariant.\n\nEach value is an exact value, typed by its condition, or a single-operator predicate:\n\n- `{ \"lt\": v }`, `{ \"lte\": v }`, `{ \"gt\": v }`, `{ \"gte\": v }` — order, against a `number`\n  or `date` condition\n- `{ \"in\": [...] }` — membership, against a `string`, `select` or `number` condition\n- `{ \"between\": \"2026-03-01\" }` — `daterange` containment, which a plain date also means\n- `{ \"exists\": true }` — pinned to any value; `{ \"exists\": false }` — left unpinned\n\nAn `in` list carries at most 50,000 values. A `string` or `select` matches exactly and\ncase-sensitively. A `location` of format\n`postal_code` is the postal code itself; one of format `postal_code_city` is an object carrying\n`postal_code` and `city`, named as an entity address names them, whose city is compared\ncase- and whitespace-insensitively.\n\n`default` and names beginning with `_` are reserved and cannot be supplied.\n",
         "example": {
           "postal_code": "46045",
@@ -6053,7 +6260,9 @@
       },
       "VariantConditions": {
         "type": "object",
-        "additionalProperties": true,
+        "additionalProperties": {
+          "$ref": "#/components/schemas/PinnedConditionValue"
+        },
         "required": [
           "default"
         ],
@@ -6070,120 +6279,312 @@
       },
       "PinnedConditions": {
         "type": "object",
-        "additionalProperties": true,
+        "additionalProperties": {
+          "$ref": "#/components/schemas/PinnedConditionValue"
+        },
         "description": "The situation this variant applies to: a flat map keyed by condition name. A condition left\nout is a wildcard, which is what makes adding a condition to a schema non-breaking for\nexisting variants.\n\nExact values only; predicates belong to reads. Values are stored canonicalized for their\ntype: a `date` becomes millisecond-precision UTC, a `daterange` an object carrying `from`\nand `until` where an empty string is an open end, a `location` of format `postal_code` the\npostal code itself and one of format `postal_code_city` an object carrying `postal_code` and\n`city`.\n\n`default` and names beginning with `_` are reserved; use the request's `default` flag.\n",
         "example": {
           "postal_code": "46045"
         }
       },
-      "VariantValues": {
+      "PinnedConditionValue": {
+        "description": "One condition's exact value. Which of these shapes a condition takes is set by its type in the\nentity's schema, and a value of another shape is refused with `PIN_FORMAT_INVALID`.\n",
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "number"
+          },
+          {
+            "type": "boolean"
+          },
+          {
+            "$ref": "#/components/schemas/ConditionDateRange"
+          },
+          {
+            "$ref": "#/components/schemas/PostalCodeCity"
+          }
+        ]
+      },
+      "ConditionDateRange": {
         "type": "object",
-        "additionalProperties": true,
-        "description": "The values this version overrides on the base entity, keyed by entity field name.\n\nA field is overridable if its attribute declares `overridable_attribute` — which readonly,\nhidden, computed and metadata fields, and types no variant may override, cannot be given —\nor if a capability declaring `overridable_attribute` names it in `managed_fields`, which\nexcludes only readonly and metadata fields.\n\nFields that are not overridable are reported in the write's `warnings` rather than rejected,\nand keep whatever value they already had. An append seeds them from the version in effect at\nits own `valid_from`.\n\nA composite price's `price_components` is an ordinary overridable relation attribute,\nreferencing component entities rather than variants or versions.\n",
-        "example": {
-          "unit_amount": 2499,
-          "unit_amount_decimal": "24.99"
+        "additionalProperties": false,
+        "description": "The value of a `daterange` condition. A bound that is absent, `null` or an empty string is an\nopen end; stored, an open end is an empty string.\n",
+        "properties": {
+          "from": {
+            "type": "string",
+            "nullable": true,
+            "example": "2026-01-01"
+          },
+          "until": {
+            "type": "string",
+            "nullable": true,
+            "example": "2027-01-01"
+          }
         }
       },
-      "CreatedVariant": {
+      "PostalCodeCity": {
         "type": "object",
+        "additionalProperties": false,
+        "description": "The value of a `location` condition of format `postal_code_city`, its parts named as an entity\naddress names them.\n",
         "required": [
-          "variant_id",
-          "entity_id",
-          "schema",
-          "conditions",
-          "valid_from",
-          "values",
-          "_created_at",
-          "_updated_at",
-          "_revision",
-          "warnings"
+          "postal_code",
+          "city"
         ],
         "properties": {
-          "variant_id": {
-            "type": "string",
-            "description": "Server-generated. The durable key orders and contracts pin.",
-            "example": "var-46045"
-          },
-          "entity_id": {
+          "postal_code": {
             "type": "string",
-            "example": "price-sp26d1yo"
-          },
-          "schema": {
-            "$ref": "#/components/schemas/ConditionalEntitySlug"
-          },
-          "conditions": {
-            "allOf": [
-              {
-                "$ref": "#/components/schemas/VariantConditions"
-              }
-            ],
-            "description": "The situation this variant applies to, plus the boolean `default` discriminator."
+            "minLength": 1,
+            "example": "50667"
           },
-          "valid_from": {
+          "city": {
             "type": "string",
-            "description": "When the first version takes effect, canonicalized to millisecond-precision UTC.",
-            "example": "2027-01-01T00:00:00.000Z"
-          },
-          "values": {
-            "$ref": "#/components/schemas/VariantValues"
+            "minLength": 1,
+            "example": "Köln"
+          }
+        }
+      },
+      "ContextConditionValue": {
+        "description": "One condition's value in a resolve context or listing filter: an exact value, or a predicate.\nWhich of these a condition takes is set by its type in the entity's schema, and a value of\nanother shape is refused with `CONTEXT_FORMAT_INVALID`, or `OPERATOR_UNSUPPORTED` for a\npredicate its type does not support.\n",
+        "anyOf": [
+          {
+            "type": "string"
           },
-          "_created_at": {
-            "type": "string",
-            "description": "When the first version was created.",
-            "readOnly": true
+          {
+            "type": "number"
           },
-          "_updated_at": {
-            "type": "string",
-            "description": "When the first version was last written.",
-            "readOnly": true
+          {
+            "type": "boolean"
           },
-          "_revision": {
-            "type": "number",
-            "description": "The revision a later write to this version must carry.",
-            "readOnly": true
+          {
+            "$ref": "#/components/schemas/PostalCodeCity"
           },
-          "warnings": {
-            "type": "array",
-            "description": "Things worth knowing that did not stop the write. Always present, and empty in the ordinary case.",
-            "items": {
-              "$ref": "#/components/schemas/WriteWarning"
-            }
+          {
+            "$ref": "#/components/schemas/ConditionPredicate"
           }
-        }
+        ]
       },
-      "WriteWarning": {
-        "description": "Something worth knowing that did not stop a write. One vocabulary for every write; `details`\nis typed per `code`, and a write raises each code at most once.\n",
+      "ConditionPredicate": {
+        "description": "A single-operator predicate.",
         "oneOf": [
           {
             "type": "object",
             "additionalProperties": false,
-            "description": "This entity is nearing the number of variants it may hold.",
             "required": [
-              "code",
-              "message",
-              "details"
+              "lt"
             ],
             "properties": {
-              "code": {
-                "type": "string",
-                "enum": [
-                  "VARIANT_COUNT_APPROACHING_CAP"
-                ]
-              },
-              "message": {
-                "type": "string"
-              },
-              "details": {
-                "type": "object",
-                "additionalProperties": false,
-                "required": [
-                  "variant_count",
-                  "cap"
-                ],
-                "properties": {
-                  "variant_count": {
-                    "type": "number",
+              "lt": {
+                "$ref": "#/components/schemas/OrderedConditionOperand"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "lte"
+            ],
+            "properties": {
+              "lte": {
+                "$ref": "#/components/schemas/OrderedConditionOperand"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "gt"
+            ],
+            "properties": {
+              "gt": {
+                "$ref": "#/components/schemas/OrderedConditionOperand"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "gte"
+            ],
+            "properties": {
+              "gte": {
+                "$ref": "#/components/schemas/OrderedConditionOperand"
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "in"
+            ],
+            "properties": {
+              "in": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "number"
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "between"
+            ],
+            "properties": {
+              "between": {
+                "type": "string",
+                "description": "The instant a `daterange` condition's range must contain."
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "exists"
+            ],
+            "properties": {
+              "exists": {
+                "type": "boolean"
+              }
+            }
+          }
+        ]
+      },
+      "OrderedConditionOperand": {
+        "description": "A number, or a date as an RFC 3339 date or date-time.",
+        "anyOf": [
+          {
+            "type": "number"
+          },
+          {
+            "type": "string"
+          }
+        ]
+      },
+      "VariantValues": {
+        "type": "object",
+        "additionalProperties": true,
+        "description": "The values this version overrides on the base entity, keyed by entity field name.\n\nA field is overridable if its attribute declares `overridable_attribute` — which readonly,\nhidden, computed and metadata fields, and types no variant may override, cannot be given —\nor if a capability declaring `overridable_attribute` names it in `managed_fields`, which\nexcludes only readonly and metadata fields.\n\nFields that are not overridable are reported in the write's `warnings` rather than rejected,\nand keep whatever value they already had. An append seeds them from the version in effect at\nits own `valid_from`.\n\nA composite price's `price_components` is an ordinary overridable relation attribute,\nreferencing component entities rather than variants or versions.\n",
+        "example": {
+          "unit_amount": 2499,
+          "unit_amount_decimal": "24.99"
+        }
+      },
+      "CreatedVariant": {
+        "type": "object",
+        "required": [
+          "variant_id",
+          "entity_id",
+          "schema",
+          "conditions",
+          "valid_from",
+          "values",
+          "_created_at",
+          "_updated_at",
+          "_revision",
+          "warnings"
+        ],
+        "properties": {
+          "variant_id": {
+            "type": "string",
+            "description": "Server-generated. The durable key orders and contracts pin.",
+            "example": "var-46045"
+          },
+          "entity_id": {
+            "type": "string",
+            "example": "price-sp26d1yo"
+          },
+          "schema": {
+            "$ref": "#/components/schemas/ConditionalEntitySlug"
+          },
+          "conditions": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/VariantConditions"
+              }
+            ],
+            "description": "The situation this variant applies to, plus the boolean `default` discriminator."
+          },
+          "valid_from": {
+            "type": "string",
+            "description": "When the first version takes effect, canonicalized to millisecond-precision UTC.",
+            "example": "2027-01-01T00:00:00.000Z"
+          },
+          "values": {
+            "$ref": "#/components/schemas/VariantValues"
+          },
+          "_created_at": {
+            "type": "string",
+            "description": "When the first version was created.",
+            "readOnly": true
+          },
+          "_updated_at": {
+            "type": "string",
+            "description": "When the first version was last written.",
+            "readOnly": true
+          },
+          "_revision": {
+            "type": "number",
+            "description": "The revision a later write to this version must carry.",
+            "readOnly": true
+          },
+          "warnings": {
+            "type": "array",
+            "description": "Things worth knowing that did not stop the write. Always present, and empty in the ordinary case.",
+            "items": {
+              "$ref": "#/components/schemas/WriteWarning"
+            }
+          }
+        }
+      },
+      "WriteWarning": {
+        "description": "Something worth knowing that did not stop a write. One vocabulary for every write; `details`\nis typed per `code`, and a write raises each code at most once.\n",
+        "oneOf": [
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "This entity is nearing the number of variants it may hold.",
+            "required": [
+              "code",
+              "message",
+              "details"
+            ],
+            "properties": {
+              "code": {
+                "type": "string",
+                "enum": [
+                  "VARIANT_COUNT_APPROACHING_CAP"
+                ]
+              },
+              "message": {
+                "type": "string"
+              },
+              "details": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "variant_count",
+                  "cap"
+                ],
+                "properties": {
+                  "variant_count": {
+                    "type": "number",
                     "description": "Variants this entity holds, including the one just written."
                   },
                   "cap": {
@@ -6702,7 +7103,9 @@
       },
       "VariantConditionFilter": {
         "type": "object",
-        "additionalProperties": true,
+        "additionalProperties": {
+          "$ref": "#/components/schemas/ContextConditionValue"
+        },
         "description": "Which pins a variant must carry to be listed: a flat map keyed by condition name, taking the\nsame exact values and predicates a resolve context does. A condition left out is not\nfiltered on. An `in` list carries at most 50,000 values.\n\nA variant matches only where it pins the condition — unlike `:resolve`, where an unpinned\ncondition matches any value. `{ \"exists\": false }` selects the variants that leave it\nunpinned.\n\n`default` is accepted as an exact boolean and takes no predicate: `true` selects the\nentity's fallback variant, `false` every variant that is not it. Names beginning with `_`\nare reserved.\n",
         "example": {
           "postal_code": "46045",
@@ -7300,6 +7703,26 @@
           }
         }
       },
+      "RefusedLineItem": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "The line item a checkout refusal is about, named as the item names itself.",
+        "required": [
+          "price_id"
+        ],
+        "properties": {
+          "price_id": {
+            "type": "string",
+            "description": "The item's price id.",
+            "example": "price-sp26d1yo"
+          },
+          "product_id": {
+            "type": "string",
+            "description": "The item's product id, when the item names one.",
+            "example": "product-pv-2027"
+          }
+        }
+      },
       "ReportedError": {
         "description": "The `error` field of an error response: the message, or — where the request failed\nvalidation before any handler ran — the validation errors themselves.\n",
         "oneOf": [
@@ -8635,84 +9058,150 @@
           }
         ]
       },
-      "Product": {
-        "type": "object",
-        "description": "The product entity",
-        "readOnly": true,
-        "additionalProperties": true,
-        "example": {
-          "type": "product",
-          "_schema": "product",
-          "_title": "Solar Panel with Battery Storage",
-          "name": "Solar Panel with Battery Storage",
-          "code": "SOLAR-BATT",
-          "active": true,
-          "description": "Solar Panel with battery solution, optimized for max efficiency. ",
-          "feature": [
-            {
-              "_tags": [],
-              "feature": "Eco-Panels"
-            },
-            {
-              "_tags": [],
-              "feature": "Remote Management Platform"
-            },
-            {
-              "_tags": [],
-              "feature": "Battery Remote Control"
-            },
-            {
-              "_tags": [],
-              "feature": "Mobile App"
-            }
-          ],
-          "cross_sellable_products": {
-            "$relation": [
-              {
-                "entity_id": "068d0713-a650-4668-9ed2-eca7be31e337",
-                "_schema": "product",
-                "_tags": []
-              },
-              {
-                "entity_id": "c8402ee7-fba9-4f3d-bffd-6803ca655782",
-                "_tags": []
-              }
-            ]
+      "CatalogReferenceErrorCode": {
+        "type": "string",
+        "description": "Why an order operation refused a catalog reference. Other refusals carry no `code`.\n\n- `CATALOG_REFERENCE_MISSING` (400): a line item whose product or price is conditional carries no `catalog_reference`, or one with no variant for that member\n- `CATALOG_REFERENCE_SIGNATURE_INVALID` (400): a `catalog_reference` on a public checkout is unsigned, or its signature does not verify\n- `CATALOG_REFERENCE_UNRESOLVABLE` (400): a member of a `catalog_reference` cannot be resolved at its `as_of` — its entity or variant no longer exists, the variant has no version in effect, or the entity's schema no longer lets the variant be read\n",
+        "enum": [
+          "CATALOG_REFERENCE_MISSING",
+          "CATALOG_REFERENCE_SIGNATURE_INVALID",
+          "CATALOG_REFERENCE_UNRESOLVABLE"
+        ]
+      },
+      "CatalogReferenceError": {
+        "description": "An error from an order operation that prices line items. A catalog-reference refusal carries\n`code` and `details`, typed per code. Every other refusal carries neither.\n",
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/Error"
           },
-          "product_images": {
-            "$relation": [
-              {
-                "entity_id": "37bdeaaa-65fe-403e-9894-65b01cd277f1"
-              },
-              {
-                "entity_id": "56dde657-795c-41bb-bf53-98fd586b7e6e"
+          {
+            "type": "object",
+            "properties": {
+              "error": {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/ReportedError"
+                  }
+                ],
+                "description": "What went wrong. The same string as `message`, except on a request-validation\nfailure, which puts the list of validation errors here instead.\n"
               }
-            ]
+            }
           },
-          "product_downloads": {
-            "$relation": [
+          {
+            "oneOf": [
               {
-                "entity_id": "64211361-8759-414b-81c0-afbf24f83aa9"
-              }
-            ]
-          },
-          "_id": "a7f4771a-6368-4d77-bb01-71f1e4902de5",
-          "_org": "728",
-          "_created_at": "2022-06-03T15: 52: 27.512Z",
-          "_updated_at": "2022-06-03T16: 05: 15.029Z",
-          "price_options": {
-            "$relation": [
+                "type": "object",
+                "description": "A conditional line item carries no `catalog_reference`, or one with no variant for\nthat member. Send the pair's reference unchanged.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "CATALOG_REFERENCE_MISSING"
+                    ]
+                  },
+                  "details": {
+                    "$ref": "#/components/schemas/RefusedLineItem"
+                  }
+                }
+              },
               {
-                "entity_id": "9c36c23b-1574-4193-beff-b1b5e1124bc7",
-                "_tags": []
+                "type": "object",
+                "description": "The `catalog_reference` of a line item on a public checkout carries no `_meta`, or a\nsignature that does not verify against the reference. The reference was altered or\ndid not come from the catalog; fetch the pair again and send it unchanged.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "CATALOG_REFERENCE_SIGNATURE_INVALID"
+                    ]
+                  },
+                  "details": {
+                    "$ref": "#/components/schemas/RefusedLineItem"
+                  }
+                }
               },
               {
-                "entity_id": "146aa2cc-f267-4d5e-bda4-cbe2669b7741",
-                "_tags": []
+                "type": "object",
+                "description": "A member of the `catalog_reference` cannot be resolved at the reference's `as_of`:\nits entity or variant no longer exists, the variant has no version in effect at that\ninstant, or the entity's schema no longer lets the variant be read. Fetch the pair\nagain; the catalog answers with what is offered now.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "CATALOG_REFERENCE_UNRESOLVABLE"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "schema",
+                      "entity_id",
+                      "variant_id",
+                      "as_of"
+                    ],
+                    "properties": {
+                      "schema": {
+                        "$ref": "#/components/schemas/ConditionalEntitySlug"
+                      },
+                      "entity_id": {
+                        "type": "string",
+                        "description": "The entity the reference addressed.",
+                        "example": "price-sp26d1yo"
+                      },
+                      "variant_id": {
+                        "type": "string",
+                        "description": "The variant the reference addressed.",
+                        "example": "var-46045"
+                      },
+                      "as_of": {
+                        "type": "string",
+                        "description": "The instant the reference names.",
+                        "example": "2026-12-20T10:15:00.000Z"
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "A refusal without a `code`, such as a request validation failure or a price that\ndoes not exist.\n",
+                "additionalProperties": false,
+                "required": [
+                  "message"
+                ],
+                "properties": {
+                  "message": {
+                    "type": "string"
+                  },
+                  "status": {
+                    "type": "number"
+                  },
+                  "cause": {
+                    "type": "string"
+                  },
+                  "error": {
+                    "$ref": "#/components/schemas/ReportedError"
+                  }
+                }
               }
             ]
           }
-        },
+        ]
+      },
+      "BaseProduct": {
+        "type": "object",
+        "description": "The product's own attributes — everything but the two relations whose shape depends on\nwhether the product was hydrated, which `Product` and `HydratedProduct` add.\n",
+        "additionalProperties": true,
         "properties": {
           "description": {
             "type": "string",
@@ -8759,18 +9248,6 @@
               }
             }
           },
-          "cross_sellable_products": {
-            "type": "object",
-            "description": "Stores references to products that can be cross sold with the current product.",
-            "properties": {
-              "$relation": {
-                "type": "array",
-                "items": {
-                  "$ref": "#/components/schemas/EntityRelation"
-                }
-              }
-            }
-          },
           "product_images": {
             "description": "Stores references to a set of file images of the product",
             "oneOf": [
@@ -8815,20 +9292,8 @@
               }
             ]
           },
-          "price_options": {
-            "type": "object",
-            "description": "A set of [prices](/api/pricing#tag/simple_price_schema) or [composite prices](/api/pricing#tag/dynamic_price_schema) for the current product.",
-            "properties": {
-              "$relation": {
-                "type": "array",
-                "items": {
-                  "$ref": "#/components/schemas/EntityRelation"
-                }
-              }
-            }
-          },
           "is_conditional": {
-            "description": "The flag for entities whose values vary by context. Resolve the values that apply with\n`POST /v1/conditional-pricing:resolve`.\n",
+            "description": "The flag for entities whose values vary by context. Resolve the values that apply with\n`POST /v1/conditional-pricing:resolve`, or from a journey with `POST /v2/public/catalog`.\n",
             "type": "boolean"
           },
           "_availability_files": {
@@ -8862,99 +9327,243 @@
           }
         }
       },
-      "Opportunity": {
+      "Product": {
         "type": "object",
-        "description": "The opportunity entity",
+        "description": "The product entity, its relations as stored.",
+        "readOnly": true,
         "additionalProperties": true,
         "example": {
-          "opportunity_number": "OP 2022/335790",
-          "source": {
-            "title": "manual"
-          },
-          "source_type": "manual",
-          "_schema": "opportunity",
-          "_title": "16 Module Solar Pack Lead",
-          "opportunity_title": "16 Module Solar Pack Lead",
-          "due_date": "2022-06-30T15:18:00.000Z",
-          "assignee": [
+          "type": "product",
+          "_schema": "product",
+          "_title": "Solar Panel with Battery Storage",
+          "name": "Solar Panel with Battery Storage",
+          "code": "SOLAR-BATT",
+          "active": true,
+          "description": "Solar Panel with battery solution, optimized for max efficiency. ",
+          "feature": [
             {
-              "id": "10002563",
-              "email": "j.pinho@epilot.cloud",
-              "display_name": "j.pinho@epilot.cloud",
-              "token": "9e1758a3-2a32-4a5f-b034-a8ab883f8fb9",
-              "image_uri": "https://dummy-image.jpg",
-              "organization_id": "728",
-              "department": "Engineering",
-              "preferred_language": "en",
-              "status": "Active",
-              "phone": "+49123456789",
-              "email_notification_setting": {
-                "added_participant_opportunity": true,
-                "assigned_opportunity": true,
-                "assigned_task": true,
-                "comment_opportunity": true,
-                "deleted_task": true,
-                "escalated_task": true,
-                "message_receive_opportunity": true,
-                "message_send_opportunity": true,
-                "created_task": true,
-                "created_opportunity_manual": true,
-                "created_opportunity_auto": true,
-                "deleted_opportunity": true
-              },
-              "is_signature_enabled": true,
-              "created_at": "2021-05-18T06:30:25.36046"
+              "_tags": [],
+              "feature": "Eco-Panels"
+            },
+            {
+              "_tags": [],
+              "feature": "Remote Management Platform"
+            },
+            {
+              "_tags": [],
+              "feature": "Battery Remote Control"
+            },
+            {
+              "_tags": [],
+              "feature": "Mobile App"
             }
           ],
-          "description": "Lead generated automatically via journey automation.",
-          "customer": {
+          "cross_sellable_products": {
             "$relation": [
               {
-                "entity_id": "69bf4355-9c1e-498a-b87e-6c873668194d",
+                "entity_id": "068d0713-a650-4668-9ed2-eca7be31e337",
+                "_schema": "product",
                 "_tags": []
               },
               {
-                "entity_id": "8625e2e4-978e-4d16-b3d2-0d05fb4091f0",
+                "entity_id": "c8402ee7-fba9-4f3d-bffd-6803ca655782",
                 "_tags": []
               }
             ]
           },
-          "dates": [
-            {
-              "_tags": [
-                "Installation Date"
-              ],
-              "dates": "",
-              "value": "2022-06-30T15:21:00.000Z"
-            }
-          ],
-          "items": {
+          "product_images": {
             "$relation": [
               {
-                "entity_id": "ff5fcdaf-9e36-4292-97f0-6a4e3f82a8f3"
-              },
-              {
-                "entity_id": "ec10b7cf-95ce-4f6b-a266-c566c7734b96"
+                "entity_id": "37bdeaaa-65fe-403e-9894-65b01cd277f1"
               },
               {
-                "entity_id": "c3745dfe-4a46-4c22-8bf3-6159303474e4"
+                "entity_id": "56dde657-795c-41bb-bf53-98fd586b7e6e"
               }
             ]
           },
-          "billing_address": {
-            "$relation_ref": [
+          "product_downloads": {
+            "$relation": [
               {
-                "entity_id": "69bf4355-9c1e-498a-b87e-6c873668194d",
-                "path": "address.2"
+                "entity_id": "64211361-8759-414b-81c0-afbf24f83aa9"
               }
             ]
           },
-          "delivery_address": {
-            "$relation_ref": [
+          "_id": "a7f4771a-6368-4d77-bb01-71f1e4902de5",
+          "_org": "728",
+          "_created_at": "2022-06-03T15: 52: 27.512Z",
+          "_updated_at": "2022-06-03T16: 05: 15.029Z",
+          "price_options": {
+            "$relation": [
               {
-                "entity_id": "69bf4355-9c1e-498a-b87e-6c873668194d",
-                "path": "address.24"
-              }
+                "entity_id": "9c36c23b-1574-4193-beff-b1b5e1124bc7",
+                "_tags": []
+              },
+              {
+                "entity_id": "146aa2cc-f267-4d5e-bda4-cbe2669b7741",
+                "_tags": []
+              }
+            ]
+          }
+        },
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseProduct"
+          }
+        ],
+        "properties": {
+          "cross_sellable_products": {
+            "type": "object",
+            "description": "Stores references to products that can be cross sold with the current product.",
+            "properties": {
+              "$relation": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/EntityRelation"
+                }
+              }
+            }
+          },
+          "price_options": {
+            "type": "object",
+            "description": "A set of [prices](/api/pricing#tag/simple_price_schema) or [composite prices](/api/pricing#tag/dynamic_price_schema) for the current product.",
+            "properties": {
+              "$relation": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/EntityRelation"
+                }
+              }
+            }
+          }
+        }
+      },
+      "HydratedProduct": {
+        "type": "object",
+        "description": "The product entity hydrated one level deep, as the v2 public catalog serves it: each\nrelation holds the entities it referenced, sanitised, with their own relations as stored.\n",
+        "readOnly": true,
+        "additionalProperties": true,
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/BaseProduct"
+          }
+        ],
+        "properties": {
+          "cross_sellable_products": {
+            "type": "array",
+            "description": "The products that can be cross sold with the current product.",
+            "items": {
+              "$ref": "#/components/schemas/Product"
+            }
+          },
+          "price_options": {
+            "type": "array",
+            "description": "The [prices](/api/pricing#tag/simple_price_schema) and [composite\nprices](/api/pricing#tag/dynamic_price_schema) of the current product, each as stored.\nA conditional one is its base entity: the pair's `price` is the resolved one.\n",
+            "items": {
+              "anyOf": [
+                {
+                  "$ref": "#/components/schemas/Price"
+                },
+                {
+                  "$ref": "#/components/schemas/CompositePrice"
+                }
+              ]
+            }
+          }
+        }
+      },
+      "Opportunity": {
+        "type": "object",
+        "description": "The opportunity entity",
+        "additionalProperties": true,
+        "example": {
+          "opportunity_number": "OP 2022/335790",
+          "source": {
+            "title": "manual"
+          },
+          "source_type": "manual",
+          "_schema": "opportunity",
+          "_title": "16 Module Solar Pack Lead",
+          "opportunity_title": "16 Module Solar Pack Lead",
+          "due_date": "2022-06-30T15:18:00.000Z",
+          "assignee": [
+            {
+              "id": "10002563",
+              "email": "j.pinho@epilot.cloud",
+              "display_name": "j.pinho@epilot.cloud",
+              "token": "9e1758a3-2a32-4a5f-b034-a8ab883f8fb9",
+              "image_uri": "https://dummy-image.jpg",
+              "organization_id": "728",
+              "department": "Engineering",
+              "preferred_language": "en",
+              "status": "Active",
+              "phone": "+49123456789",
+              "email_notification_setting": {
+                "added_participant_opportunity": true,
+                "assigned_opportunity": true,
+                "assigned_task": true,
+                "comment_opportunity": true,
+                "deleted_task": true,
+                "escalated_task": true,
+                "message_receive_opportunity": true,
+                "message_send_opportunity": true,
+                "created_task": true,
+                "created_opportunity_manual": true,
+                "created_opportunity_auto": true,
+                "deleted_opportunity": true
+              },
+              "is_signature_enabled": true,
+              "created_at": "2021-05-18T06:30:25.36046"
+            }
+          ],
+          "description": "Lead generated automatically via journey automation.",
+          "customer": {
+            "$relation": [
+              {
+                "entity_id": "69bf4355-9c1e-498a-b87e-6c873668194d",
+                "_tags": []
+              },
+              {
+                "entity_id": "8625e2e4-978e-4d16-b3d2-0d05fb4091f0",
+                "_tags": []
+              }
+            ]
+          },
+          "dates": [
+            {
+              "_tags": [
+                "Installation Date"
+              ],
+              "dates": "",
+              "value": "2022-06-30T15:21:00.000Z"
+            }
+          ],
+          "items": {
+            "$relation": [
+              {
+                "entity_id": "ff5fcdaf-9e36-4292-97f0-6a4e3f82a8f3"
+              },
+              {
+                "entity_id": "ec10b7cf-95ce-4f6b-a266-c566c7734b96"
+              },
+              {
+                "entity_id": "c3745dfe-4a46-4c22-8bf3-6159303474e4"
+              }
+            ]
+          },
+          "billing_address": {
+            "$relation_ref": [
+              {
+                "entity_id": "69bf4355-9c1e-498a-b87e-6c873668194d",
+                "path": "address.2"
+              }
+            ]
+          },
+          "delivery_address": {
+            "$relation_ref": [
+              {
+                "entity_id": "69bf4355-9c1e-498a-b87e-6c873668194d",
+                "path": "address.24"
+              }
             ]
           },
           "address": {
@@ -9990,7 +10599,7 @@
             ]
           },
           "is_conditional": {
-            "description": "The flag for entities whose values vary by context. Resolve the values that apply with\n`POST /v1/conditional-pricing:resolve`.\n",
+            "description": "The flag for entities whose values vary by context. Resolve the values that apply with\n`POST /v1/conditional-pricing:resolve`, or from a journey with `POST /v2/public/catalog`.\n",
             "type": "boolean"
           },
           "pricing_model": {
@@ -10314,7 +10923,7 @@
             ]
           },
           "is_conditional": {
-            "description": "The flag for entities whose values vary by context. Resolve the values that apply with\n`POST /v1/conditional-pricing:resolve`.\n",
+            "description": "The flag for entities whose values vary by context. Resolve the values that apply with\n`POST /v1/conditional-pricing:resolve`, or from a journey with `POST /v2/public/catalog`.\n",
             "type": "boolean"
           },
           "_created_at": {
@@ -10683,155 +11292,557 @@
           }
         }
       },
-      "ExternalPriceMetadata": {
-        "allOf": [
-          {
-            "$ref": "#/components/schemas/AverageMarketPriceResult"
-          }
-        ],
+      "ExternalPriceMetadata": {
+        "allOf": [
+          {
+            "$ref": "#/components/schemas/AverageMarketPriceResult"
+          }
+        ],
+        "type": "object",
+        "properties": {
+          "inputs": {
+            "type": "object",
+            "additionalProperties": true
+          }
+        }
+      },
+      "ExternalFeeMappings": {
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/ExternalFeeMapping"
+        },
+        "example": [
+          {
+            "price_id": "589B011B-F8D9-4F8E-AD71-BACE4B543C0F",
+            "frequency_unit": "weekly",
+            "amount_total": 1000,
+            "amount_total_decimal": "10.00"
+          }
+        ]
+      },
+      "ExternalFeeMapping": {
+        "type": "object",
+        "properties": {
+          "price_id": {
+            "type": "string"
+          },
+          "frequency_unit": {
+            "type": "string",
+            "enum": [
+              "weekly",
+              "monthly",
+              "every_quarter",
+              "every_6_months",
+              "yearly",
+              "one_time"
+            ]
+          },
+          "amount_total": {
+            "type": "number"
+          },
+          "amount_total_decimal": {
+            "type": "string"
+          }
+        },
+        "example": {
+          "price_id": "589B011B-F8D9-4F8E-AD71-BACE4B543C0F",
+          "frequency_unit": "weekly",
+          "amount_total": 1000,
+          "amount_total_decimal": "10.00"
+        }
+      },
+      "CatalogSearch": {
+        "description": "A catalog search payload",
+        "type": "object",
+        "properties": {
+          "q": {
+            "description": "The query to perform using lucene query syntax.",
+            "type": "string"
+          },
+          "sort": {
+            "description": "The sort expression to sort the results.",
+            "type": "string"
+          },
+          "from": {
+            "description": "The index from which to query, used for pagination purposes. Defaults to 0",
+            "type": "number"
+          },
+          "size": {
+            "description": "The max size of the response, defaults to 2000.",
+            "type": "number"
+          },
+          "hydrate": {
+            "type": "boolean",
+            "description": "When true, enables entity hydration to resolve nested $relation references in-place.",
+            "default": false
+          },
+          "fields": {
+            "$ref": "#/components/schemas/CatalogFieldsParam"
+          },
+          "availability": {
+            "$ref": "#/components/schemas/AvailabilityFilters"
+          }
+        },
+        "example": {
+          "q": "_id:1233432 OR _id:123432454 OR _id:23445433",
+          "sort": "description ASC",
+          "from": 0,
+          "size": 200
+        },
+        "required": [
+          "q"
+        ]
+      },
+      "CatalogFieldsParam": {
+        "type": "array",
+        "description": "List of entity fields to include or exclude from the results.\n",
+        "items": {
+          "type": "string"
+        },
+        "example": [
+          "!_files",
+          "!**.versions"
+        ]
+      },
+      "CatalogSearchResult": {
+        "description": "The query result payload",
+        "type": "object",
+        "properties": {
+          "hits": {
+            "type": "number",
+            "description": "The number of results returned."
+          },
+          "results": {
+            "type": "array",
+            "items": {
+              "anyOf": [
+                {
+                  "$ref": "#/components/schemas/Product"
+                },
+                {
+                  "$ref": "#/components/schemas/Price"
+                },
+                {
+                  "$ref": "#/components/schemas/Coupon"
+                }
+              ]
+            }
+          }
+        },
+        "example": {
+          "hits": 2,
+          "results": [
+            {
+              "schema": "product",
+              "description": "product a"
+            },
+            {
+              "schema": "price",
+              "unit_amount_decimal": "124.342343434"
+            }
+          ]
+        }
+      },
+      "ResolveCatalogRequest": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "The entries of one journey block, and the situation to resolve them for. Every member of\nevery pair is resolved for its entity type's context at the same `as_of`.\n",
+        "required": [
+          "entries",
+          "context"
+        ],
+        "properties": {
+          "entries": {
+            "type": "array",
+            "description": "One entry per configured tile, answered independently — a duplicate is answered twice.\nAt most 100.\n",
+            "minItems": 1,
+            "maxItems": 100,
+            "items": {
+              "$ref": "#/components/schemas/CatalogEntry"
+            }
+          },
+          "context": {
+            "$ref": "#/components/schemas/CatalogContext"
+          },
+          "as_of": {
+            "type": "string",
+            "description": "The instant every member is resolved at. Defaults to now. It is written into every\ncatalog reference, and checkout prices at it. Accepts an RFC 3339 date (read as midnight\nUTC) or date-time, to millisecond precision.\n",
+            "example": "2026-12-20T10:15:00Z"
+          }
+        }
+      },
+      "CatalogContext": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "One context per entity type, each the authenticated resolve's context and checked against\nthat type's schema alone. A product resolves against `product`, and a price and each of a\ncomposite's components against `price`. A type left out resolves against an empty context,\nwhich serves the `default` variant.\n",
+        "properties": {
+          "product": {
+            "$ref": "#/components/schemas/ResolveContext"
+          },
+          "price": {
+            "$ref": "#/components/schemas/ResolveContext"
+          },
+          "coupon": {
+            "$ref": "#/components/schemas/ResolveContext"
+          }
+        },
+        "example": {
+          "product": {
+            "postal_code": "46045",
+            "channel": "direct"
+          },
+          "price": {
+            "postal_code": "46045"
+          }
+        }
+      },
+      "CatalogEntry": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "A product and, optionally, one of its prices. With `price_id` the entry is the author's\npair, served as named; without it the entry is served from the resolved product's\n`price_options`, one pair per price.\n",
+        "required": [
+          "product_id"
+        ],
+        "properties": {
+          "product_id": {
+            "type": "string",
+            "description": "The product to show.",
+            "example": "product-pv-2027"
+          },
+          "price_id": {
+            "type": "string",
+            "description": "The price to show it at. Absent, every price the resolved product offers.",
+            "example": "price-sp26d1yo"
+          }
+        }
+      },
+      "ResolveCatalogResult": {
+        "type": "object",
+        "required": [
+          "pairs",
+          "warnings"
+        ],
+        "properties": {
+          "pairs": {
+            "type": "array",
+            "description": "One pair per applicable combination, unordered. A member that matches several variants\nis several pairs; a composite whose components match several variants is one pair per\ncombination. An entry may yield none.\n",
+            "items": {
+              "$ref": "#/components/schemas/CatalogPair"
+            }
+          },
+          "warnings": {
+            "type": "array",
+            "description": "The entries that could not be answered because an id found nothing. Always present, and\nempty in the ordinary case; an entry the catalog answers \"not offered\" is not in it.\n",
+            "items": {
+              "$ref": "#/components/schemas/CatalogWarning"
+            }
+          }
+        }
+      },
+      "CatalogPair": {
+        "type": "object",
+        "description": "A product and one of its prices, resolved for the request's `context` at its `as_of`, with\nthe coupons that apply and the reference checkout prices from.\n",
+        "required": [
+          "product",
+          "price",
+          "coupons",
+          "catalog_reference"
+        ],
+        "properties": {
+          "product": {
+            "description": "The product, hydrated one level deep and sanitised. A conditional product is the resolved\npayload — the entity as its variant leaves it, carrying `_variant_id`,\n`_version_valid_from`, `_conditions` and `_inert_overrides`. A classic product carries\nnone of them.\n",
+            "anyOf": [
+              {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/HydratedProduct"
+                  },
+                  {
+                    "$ref": "#/components/schemas/ResolvedVariant"
+                  }
+                ]
+              },
+              {
+                "$ref": "#/components/schemas/HydratedProduct"
+              }
+            ]
+          },
+          "price": {
+            "description": "The price, hydrated one level deep and sanitised, with the same discriminators when it is\nconditional. A composite price carries its components hydrated in place; a component that\nis itself conditional is resolved against the same context and carries the\ndiscriminators too.\n",
+            "anyOf": [
+              {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/Price"
+                  },
+                  {
+                    "$ref": "#/components/schemas/ResolvedVariant"
+                  }
+                ]
+              },
+              {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/HydratedCompositePrice"
+                  },
+                  {
+                    "$ref": "#/components/schemas/ResolvedVariant"
+                  },
+                  {
+                    "$ref": "#/components/schemas/ResolvedPriceComponents"
+                  }
+                ]
+              },
+              {
+                "$ref": "#/components/schemas/Price"
+              },
+              {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/HydratedCompositePrice"
+                  },
+                  {
+                    "$ref": "#/components/schemas/ResolvedPriceComponents"
+                  }
+                ]
+              }
+            ]
+          },
+          "coupons": {
+            "type": "array",
+            "description": "The active coupons whose `prices` name this price — for a composite, its components —\nwith their promo codes and usage censored, as the v1 catalog serves them. Always present,\nand empty when none applies.\n",
+            "items": {
+              "$ref": "#/components/schemas/CouponWithoutPromoCodes"
+            }
+          },
+          "catalog_reference": {
+            "$ref": "#/components/schemas/CatalogReference"
+          }
+        }
+      },
+      "ResolvedPriceComponents": {
         "type": "object",
+        "description": "The components of a composite price as the v2 catalog serves them: hydrated in place, and\na component that is itself conditional resolved against the same context, carrying the\ndiscriminators a resolved payload carries. A conditional component with no variant in\neffect — nothing matches and there is no default — is left out, as a deleted component is.\n",
         "properties": {
-          "inputs": {
-            "type": "object",
-            "additionalProperties": true
+          "price_components": {
+            "type": "array",
+            "items": {
+              "anyOf": [
+                {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/Price"
+                    },
+                    {
+                      "$ref": "#/components/schemas/ResolvedVariant"
+                    }
+                  ]
+                },
+                {
+                  "$ref": "#/components/schemas/Price"
+                }
+              ]
+            }
           }
         }
       },
-      "ExternalFeeMappings": {
-        "type": "array",
-        "items": {
-          "$ref": "#/components/schemas/ExternalFeeMapping"
-        },
-        "example": [
+      "CatalogWarning": {
+        "description": "An entry the v2 catalog could not answer, and why. `details` is typed per `code`: narrow on\n`code` and the object under it declares exactly the fields that code sends.\n",
+        "oneOf": [
           {
-            "price_id": "589B011B-F8D9-4F8E-AD71-BACE4B543C0F",
-            "frequency_unit": "weekly",
-            "amount_total": 1000,
-            "amount_total_decimal": "10.00"
+            "type": "object",
+            "additionalProperties": false,
+            "description": "An id in the entry finds no entity, or a deleted one. One warning per such id.\n",
+            "required": [
+              "code",
+              "message",
+              "details"
+            ],
+            "properties": {
+              "code": {
+                "type": "string",
+                "enum": [
+                  "CATALOG_ENTRY_NOT_FOUND"
+                ]
+              },
+              "message": {
+                "type": "string"
+              },
+              "details": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "product_id",
+                  "missing"
+                ],
+                "properties": {
+                  "product_id": {
+                    "type": "string",
+                    "description": "The entry's product id, as sent.",
+                    "example": "product-heatpump-2027"
+                  },
+                  "price_id": {
+                    "type": "string",
+                    "description": "The entry's price id, as sent. Absent when the entry named none.",
+                    "example": "price-retired"
+                  },
+                  "missing": {
+                    "type": "string",
+                    "description": "Which of the entry's ids found nothing.",
+                    "enum": [
+                      "product",
+                      "price"
+                    ]
+                  }
+                }
+              }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "An id in the entry names an entity of another type than the entry asked for: a price id\nwhere a product id was expected, or the reverse. One warning per such id.\n",
+            "required": [
+              "code",
+              "message",
+              "details"
+            ],
+            "properties": {
+              "code": {
+                "type": "string",
+                "enum": [
+                  "CATALOG_ENTRY_TYPE_MISMATCH"
+                ]
+              },
+              "message": {
+                "type": "string"
+              },
+              "details": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "product_id",
+                  "mismatched",
+                  "actual_schema"
+                ],
+                "properties": {
+                  "product_id": {
+                    "type": "string",
+                    "description": "The entry's product id, as sent.",
+                    "example": "product-heatpump-2027"
+                  },
+                  "price_id": {
+                    "type": "string",
+                    "description": "The entry's price id, as sent. Absent when the entry named none.",
+                    "example": "product-tariff-2027"
+                  },
+                  "mismatched": {
+                    "type": "string",
+                    "description": "Which of the entry's ids names an entity of another type.",
+                    "enum": [
+                      "product",
+                      "price"
+                    ]
+                  },
+                  "actual_schema": {
+                    "type": "string",
+                    "description": "The type the entity turned out to be.",
+                    "example": "product"
+                  }
+                }
+              }
+            }
           }
         ]
       },
-      "ExternalFeeMapping": {
+      "CatalogReference": {
         "type": "object",
+        "additionalProperties": false,
+        "description": "Names the variant each member of a catalog pair was resolved from, and the instant `as_of`\nthey were resolved at. Checkout prices each conditional member from that variant, using the\nversion in effect at `as_of`.\n\nThe catalog signs every reference, classic pair or not: `_meta` signs the rest of the\nreference. Where the caller is public, a reference must verify. An authenticated caller may\nsend one without `_meta`. Signatures do not expire.\n",
+        "required": [
+          "product",
+          "price",
+          "as_of"
+        ],
         "properties": {
-          "price_id": {
-            "type": "string"
+          "product": {
+            "$ref": "#/components/schemas/CatalogReferenceMember"
           },
-          "frequency_unit": {
-            "type": "string",
-            "enum": [
-              "weekly",
-              "monthly",
-              "every_quarter",
-              "every_6_months",
-              "yearly",
-              "one_time"
-            ]
+          "price": {
+            "$ref": "#/components/schemas/CatalogReferenceMember"
           },
-          "amount_total": {
-            "type": "number"
+          "price_components": {
+            "type": "array",
+            "description": "Present for a composite price that serves at least one component: the components this\npair is the combination of, each with its variant where one produced it. A conditional\ncomponent with no variant in effect is left out of the composite and is not named here.\nA component line item carries no reference of its own.\n",
+            "items": {
+              "$ref": "#/components/schemas/CatalogReferenceMember"
+            }
           },
-          "amount_total_decimal": {
-            "type": "string"
+          "coupons": {
+            "type": "array",
+            "description": "Present when coupons apply to the price. Coupons are served as stored, so a coupon member\ncarries no `variant`.\n",
+            "items": {
+              "$ref": "#/components/schemas/CatalogReferenceMember"
+            }
+          },
+          "as_of": {
+            "type": "string",
+            "description": "The instant every member was resolved at, as an RFC 3339 date-time. Checkout selects\neach conditional member's version at this instant.\n",
+            "example": "2026-12-20T10:15:00.000Z"
+          },
+          "_meta": {
+            "$ref": "#/components/schemas/SignatureMeta"
           }
         },
         "example": {
-          "price_id": "589B011B-F8D9-4F8E-AD71-BACE4B543C0F",
-          "frequency_unit": "weekly",
-          "amount_total": 1000,
-          "amount_total_decimal": "10.00"
-        }
-      },
-      "CatalogSearch": {
-        "description": "A catalog search payload",
-        "type": "object",
-        "properties": {
-          "q": {
-            "description": "The query to perform using lucene query syntax.",
-            "type": "string"
-          },
-          "sort": {
-            "description": "The sort expression to sort the results.",
-            "type": "string"
+          "product": {
+            "id": "product-pv-2027",
+            "variant": "var-46045"
           },
-          "from": {
-            "description": "The index from which to query, used for pagination purposes. Defaults to 0",
-            "type": "number"
-          },
-          "size": {
-            "description": "The max size of the response, defaults to 2000.",
-            "type": "number"
-          },
-          "hydrate": {
-            "type": "boolean",
-            "description": "When true, enables entity hydration to resolve nested $relation references in-place.",
-            "default": false
-          },
-          "fields": {
-            "$ref": "#/components/schemas/CatalogFieldsParam"
+          "price": {
+            "id": "price-composite-9f2",
+            "variant": "var-46046"
           },
-          "availability": {
-            "$ref": "#/components/schemas/AvailabilityFilters"
+          "price_components": [
+            {
+              "id": "price-base-fee-46045",
+              "variant": "var-46047"
+            },
+            {
+              "id": "price-kwh-46045",
+              "variant": "var-46048"
+            }
+          ],
+          "coupons": [
+            {
+              "id": "0f8c4852-23fa-4a64-a2f3-88702335f094"
+            }
+          ],
+          "as_of": "2026-12-20T10:15:00.000Z",
+          "_meta": {
+            "timestamp": 1797000000000,
+            "signature": "c3ab8ff137"
           }
-        },
-        "example": {
-          "q": "_id:1233432 OR _id:123432454 OR _id:23445433",
-          "sort": "description ASC",
-          "from": 0,
-          "size": 200
-        },
-        "required": [
-          "q"
-        ]
-      },
-      "CatalogFieldsParam": {
-        "type": "array",
-        "description": "List of entity fields to include or exclude from the results.\n",
-        "items": {
-          "type": "string"
-        },
-        "example": [
-          "!_files",
-          "!**.versions"
-        ]
+        }
       },
-      "CatalogSearchResult": {
-        "description": "The query result payload",
+      "CatalogReferenceMember": {
         "type": "object",
+        "additionalProperties": false,
+        "description": "One member of a catalog reference: the entity, and the variant that produced it. `variant`\nis absent for a classic entity.\n",
+        "required": [
+          "id"
+        ],
         "properties": {
-          "hits": {
-            "type": "number",
-            "description": "The number of results returned."
+          "id": {
+            "type": "string",
+            "description": "The entity's id.",
+            "example": "price-sp26d1yo"
           },
-          "results": {
-            "type": "array",
-            "items": {
-              "anyOf": [
-                {
-                  "$ref": "#/components/schemas/Product"
-                },
-                {
-                  "$ref": "#/components/schemas/Price"
-                },
-                {
-                  "$ref": "#/components/schemas/Coupon"
-                }
-              ]
-            }
+          "variant": {
+            "type": "string",
+            "description": "The variant checkout prices this member from.",
+            "example": "var-46045"
           }
-        },
-        "example": {
-          "hits": 2,
-          "results": [
-            {
-              "schema": "product",
-              "description": "product a"
-            },
-            {
-              "schema": "price",
-              "unit_amount_decimal": "124.342343434"
-            }
-          ]
         }
       },
       "SearchProvidersParams": {
@@ -11988,6 +12999,14 @@
                 "$ref": "#/components/schemas/Product"
               }
             ]
+          },
+          "catalog_reference": {
+            "description": "The `catalog_reference` of the pair this item came from, unchanged. Required when the\nitem's product or price is conditional. Component items carry none.\n",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/CatalogReference"
+              }
+            ]
           }
         }
       },
@@ -12042,7 +13061,6 @@
           "coupon_ids": {
             "type": "array",
             "description": "The ids of the coupons applicable to the price item",
-            "readOnly": true,
             "items": {
               "type": "string",
               "description": "The id of the coupon"
@@ -12194,7 +13212,6 @@
               "price_component_coupon_ids": {
                 "type": "object",
                 "description": "The map of coupon ids applicable to the price components",
-                "readOnly": true,
                 "additionalProperties": {
                   "type": "array",
                   "items": {
@@ -13862,7 +14879,7 @@
             "type": "boolean"
           },
           "is_conditional": {
-            "description": "The flag for entities whose values vary by context. Resolve the values that apply with\n`POST /v1/conditional-pricing:resolve`.\n",
+            "description": "The flag for entities whose values vary by context. Resolve the values that apply with\n`POST /v1/conditional-pricing:resolve`, or from a journey with `POST /v2/public/catalog`.\n",
             "type": "boolean"
           },
           "requires_promo_code": {