{
"openapi": "3.0.3",
"info": {
"title": "Pricing API",
"description": "The `pricing-api` hub sets the foundations for the following Pricing APIs:\n\n### Order API\nThis api enables the management of orders in epilot 360, providing features such as:\n - Automatic calculation of totals and price breakdowns for taxes on the Order entity\n - Product and pricing data validation\n\n### Shopping Cart API\nUsed to interact with a cart during a customer's checkout session, providing:\n - An unified data model to model a Shopping Cart\n - Product and pricing data validation\n - Checkout a cart into an order or quote\n\n### Catalog API\nProvides a way to query the entire catalog of products and prices.\n\n### Availability API\nProvides endpoints for querying products availability by a set of predefined dimensions.\n\n### Spot Market API\nProvides endpoints to fetch (historic) spot market price data.\n\n### External Integrations API\nProvides endpoints for external integrations. E.g. GetAG.\n\n### External Catalog API\nProvides endpoints for external catalog.\n\n### Product Recommendations API\nProvides endpoints for product recommendations.\n\n### Conditional Pricing API\nProvides endpoints for resolving conditional Products, Prices and Coupons, and for authoring the conditions they vary by.\n",
"version": "1.2.1",
"termsOfService": "https://epilot.cloud/agb",
"contact": {
"name": "Support",
"email": "info@epilot.cloud",
"url": "https://help.epilot.cloud"
}
},
"tags": [
{
"name": "Order API",
"description": "This api enables the management of orders in epilot 360, providing features such as:\n - Automatic calculation of totals and price breakdowns for taxes on the Order entity\n - Product and pricing data validation\n"
},
{
"name": "Cart API",
"description": "Used to interact with a cart during a customer's checkout session, providing:\n - An unified data model to model a Shopping Cart\n - Product and pricing data validation\n - Checkout a cart into an order or quote\n"
},
{
"name": "Catalog API",
"description": "Provides a way to query the entire catalog of products and prices.\n"
},
{
"name": "Promo Codes API",
"description": "This API enables the validation of promo codes within journeys, their uniqueness and availability\n"
},
{
"name": "Availability API",
"description": "Provides endpoints for querying products availability by a set of predefined dimensions.\n"
},
{
"name": "Spot Market API",
"description": "Provides endpoints to fetch (historic) spot market data.\n"
},
{
"name": "External Integrations API",
"description": "Provides endpoints for external integrations. E.g. GetAG.\n"
},
{
"name": "External Catalog API",
"description": "Provides endpoints for external catalog.\n"
},
{
"name": "Product Recommendations API",
"description": "Provides endpoints for product recommendations.\n"
},
{
"name": "Conditional Pricing API",
"description": "Provides endpoints for resolving conditional Products, Prices and Coupons — the variant of an\nentity that applies to a given context — and for authoring the conditions they vary by.\n"
},
{
"name": "order_schema",
"x-displayName": "Order",
"description": "\n"
},
{
"name": "order_composite_prices",
"x-displayName": "Order (with Composite Prices)",
"description": "\n"
},
{
"name": "opportunity_schema",
"x-displayName": "Opportunity",
"description": "\n"
},
{
"name": "product_schema",
"x-displayName": "Product",
"description": "\n"
},
{
"name": "simple_price_schema",
"x-displayName": "Price",
"description": "\n"
},
{
"name": "dynamic_price_schema",
"x-displayName": "Composite Price",
"description": "\n"
},
{
"name": "coupon_schema",
"x-displayName": "Coupon",
"description": "\n"
}
],
"x-tagGroups": [
{
"name": "APIs",
"tags": [
"Order API",
"Cart API",
"Catalog API",
"Spot Market API",
"Availability API",
"External Integrations API",
"External Catalog API",
"Product Recommendations API",
"Promo Codes API",
"Conditional Pricing API"
]
},
{
"name": "Commerce Schemas",
"tags": [
"order_schema",
"opportunity_schema"
]
},
{
"name": "Pricing Schemas",
"tags": [
"product_schema",
"simple_price_schema",
"dynamic_price_schema",
"coupon_schema"
]
},
{
"name": "Examples",
"tags": [
"order_composite_prices"
]
}
],
"security": [
{
"EpilotAuth": []
}
],
"servers": [
{
"url": "https://pricing-api.sls.epilot.io"
}
],
"paths": {
"/v1/pricing:compute": {
"post": {
"description": "Computes a set of pricing details that can be persisted on an entity with the pricing capability enabled, e.g: Orders or Contracts.",
"summary": "$calculatePricingDetails",
"operationId": "$calculatePricingDetails",
"tags": [
"Order API"
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"properties": {
"line_items": {
"$ref": "#/components/schemas/PriceItemsDto"
},
"redeemed_promos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RedeemedPromo"
}
}
}
},
"examples": {
"Compute price": {
"value": {
"line_items": [
{
"product_id": "c5695fb5-f02d-4e46-9fb2-a36dc4e9876f",
"price_id": "396cb5f3-ea0b-4629-99ca-303661de5a9b",
"quantity": 2,
"is_composite_price": false
},
{
"product_id": "c5695fb5-f02d-4e46-9fb2-a36dc4e9876f",
"price_id": "396cb5f3-ea0b-4629-99ca-303661de5a9b",
"quantity": 2,
"coupon_ids": [
"0f8c4852-23fa-4a64-a2f3-88702335f094"
],
"is_composite_price": false
},
{
"product_id": "c5695fb5-f02d-4e46-9fb2-a36dc4e9876f",
"price_id": "2abe0c6f-63ef-417b-8c85-5546359382d9",
"quantity": 1,
"is_composite_price": false,
"price_mappings": [
{
"price_id": "2abe0c6f-63ef-417b-8c85-5546359382d9",
"frequency_unit": "one_time",
"value": 2,
"name": "Estimated consumption",
"metadata": {
"journey_title": "P&G",
"step_name": "Number Inputs"
}
}
]
},
{
"product_id": "c5695fb5-f02d-4e46-9fb2-a36dc4e9876f",
"price_id": "b59acf37-3cc0-456c-a712-1db0fc478d2d",
"quantity": 1,
"is_composite_price": true,
"price_component_coupon_ids": {
"583fb57a-7549-4624-82d6-342d5e6542f7": [
"0f8c4852-23fa-4a64-a2f3-88702335f094"
]
},
"price_mappings": [
{
"price_id": "25c7dc77-ac80-480a-92c0-8c0e913b5534",
"frequency_unit": "yearly",
"value": 10000,
"name": "Estimated consumption",
"metadata": {
"journey_title": "P&G",
"step_name": "Number Inputs"
}
}
],
"item_components": [
{
"pricing_model": "per_unit",
"quantity": 1,
"type": "recurring",
"billing_period": "monthly",
"price_id": "583fb57a-7549-4624-82d6-342d5e6542f7",
"product_id": "c5695fb5-f02d-4e46-9fb2-a36dc4e9876f",
"_price": {
"pricing_model": "per_unit",
"unit_amount": 1500,
"unit_amount_currency": "EUR",
"unit_amount_decimal": "15",
"sales_tax": "standard",
"active": true,
"price_display_in_journeys": "show_price",
"type": "recurring",
"_title": "Base Price",
"tax": [
{
"_schema": "tax",
"active": true,
"description": "GST",
"rate": 19,
"region": "DE",
"type": "Custom",
"_id": "d792070e-328d-4d2c-8aba-5ac7b23ff621",
"_org": "739224",
"_created_at": "2024-12-18T14:14:53.340Z",
"_updated_at": "2025-02-11T11:07:49.660Z",
"_title": "GST",
"behavior": "inclusive"
}
],
"tax_behavior": "inclusive",
"billing_period": "monthly",
"billing_duration_unit": "months",
"notice_time_unit": "months",
"termination_time_unit": "months",
"renewal_duration_unit": "months",
"description": "Base Price",
"is_tax_inclusive": false,
"internal_description": "Base Price",
"variable_price": true
},
"taxes": [
{
"tax": {
"_schema": "tax",
"active": true,
"description": "GST",
"rate": 19,
"region": "DE",
"type": "Custom",
"_id": "d792070e-328d-4d2c-8aba-5ac7b23ff621",
"_org": "739224",
"_created_at": "2024-12-18T14:14:53.340Z",
"_updated_at": "2025-02-11T11:07:49.660Z",
"_title": "GST",
"behavior": "inclusive"
},
"amount": 285
}
],
"unit_amount": 1000,
"unit_amount_decimal": "10",
"currency": "EUR",
"description": "Base Price",
"is_tax_inclusive": false
},
{
"pricing_model": "per_unit",
"quantity": 1,
"type": "recurring",
"billing_period": "monthly",
"price_id": "25c7dc77-ac80-480a-92c0-8c0e913b5534",
"product_id": "c5695fb5-f02d-4e46-9fb2-a36dc4e9876f",
"_price": {
"_id": "25c7dc77-ac80-480a-92c0-8c0e913b5534",
"active": true,
"description": "Work Price",
"is_tax_inclusive": true,
"price_display_in_journeys": "show_price",
"pricing_model": "per_unit",
"type": "recurring",
"unit_amount": 10,
"unit_amount_currency": "EUR",
"unit_amount_decimal": "0.10",
"variable_price": true,
"billing_period": "monthly",
"internal_description": "Work Price",
"_title": "Work Price",
"unit": "kwh"
},
"taxes": [
{
"tax": {
"_schema": "tax",
"active": true,
"description": "19%",
"rate": 19,
"region": "DE",
"type": "VAT",
"_id": "bd488a36-cae5-4b18-9ca5-f5cbf6d9735b",
"_org": "739224",
"_created_at": "2025-01-15T12:04:52.431Z",
"_updated_at": "2025-01-15T12:04:52.431Z",
"_title": "19%"
},
"amount": 1331
}
],
"unit_amount": 8,
"unit_amount_decimal": "0.08",
"currency": "EUR",
"description": "Work Price",
"is_tax_inclusive": true
}
]
},
{
"description": "Product Name",
"quantity": 1,
"is_composite_price": true,
"item_components": [
{
"quantity": 1,
"description": "Price Description",
"unit_amount": 10000,
"unit_amount_decimal": "100",
"unit_amount_currency": "EUR",
"pricing_model": "per_unit",
"taxes": [
{
"rate": "nontaxable",
"rateValue": 0,
"amount": 0
}
],
"type": "one_time",
"is_tax_inclusive": true
}
],
"currency": "EUR"
},
{
"price_id": "b59acf37-3cc0-456c-a712-1db0fc478d2d",
"product_id": "c5695fb5-f02d-4e46-9fb2-a36dc4e9876f",
"quantity": 1,
"description": "Power Test",
"is_composite_price": true,
"item_components": [
{
"price_id": "583fb57a-7549-4624-82d6-342d5e6542f7",
"product_id": "c5695fb5-f02d-4e46-9fb2-a36dc4e9876f",
"quantity": 1,
"description": "Base Price",
"unit_amount": 1500,
"unit_amount_decimal": "15",
"unit_amount_currency": "EUR",
"pricing_model": "per_unit",
"type": "recurring",
"billing_period": "monthly",
"is_tax_inclusive": false,
"_coupons": [
{
"name": "My Custom Discount",
"type": "fixed",
"fixed_value": 500,
"fixed_value_currency": "EUR",
"fixed_value_decimal": "5",
"category": "discount",
"active": true,
"_schema": "coupon",
"requires_promo_code": false,
"_org": "739224",
"_created_at": "2025-02-24T10:01:24.537Z",
"_updated_at": "2025-02-24T10:01:24.537Z",
"percentage_value": "0",
"_title": "My Custom Discount",
"_id": "0f8c4852-23fa-4a64-a2f3-88702335f094"
}
]
},
{
"price_id": "25c7dc77-ac80-480a-92c0-8c0e913b5534",
"product_id": "c5695fb5-f02d-4e46-9fb2-a36dc4e9876f",
"quantity": 1,
"description": "Work Price",
"unit_amount": 10,
"unit_amount_decimal": "0.10123",
"unit_amount_currency": "EUR",
"pricing_model": "per_unit",
"taxes": [
{
"tax": {
"_schema": "tax",
"active": true,
"description": "19%",
"rate": 19,
"region": "DE",
"type": "VAT",
"_id": "bd488a36-cae5-4b18-9ca5-f5cbf6d9735b",
"_org": "739224",
"_created_at": "2025-01-15T12:04:52.431Z",
"_updated_at": "2025-01-15T12:04:52.431Z",
"_title": "19%"
},
"amount": 2
}
],
"type": "recurring",
"billing_period": "monthly",
"unit_amount_net": 8,
"unit_amount_gross": 10,
"amount_subtotal": 8,
"amount_total": 10,
"amount_tax": 2,
"is_tax_inclusive": true,
"unit_amount_net_decimal": "0.084033613445",
"unit_amount_gross_decimal": "0.1",
"amount_subtotal_decimal": "0.084033613445",
"amount_total_decimal": "0.1"
}
],
"price_mappings": [
{
"price_id": "583fb57a-7549-4624-82d6-342d5e6542f7",
"value": 1
},
{
"price_id": "25c7dc77-ac80-480a-92c0-8c0e913b5534",
"value": 2000
}
],
"currency": "EUR"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Pricing details result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PricingDetailsResponse"
},
"example": {
"amount_subtotal": 1000,
"amount_total": 1000,
"amount_tax": 0,
"total_details": {
"amount_tax": 0,
"breakdown": {
"taxes": [
{
"tax": {
"rate": 0
},
"amount": 0
}
],
"recurrences": [
{
"type": "one_time",
"unit_amount_gross": 1000,
"unit_amount_net": 1000,
"amount_subtotal": 1000,
"amount_total": 1000,
"amount_subtotal_decimal": "10",
"amount_total_decimal": "10",
"amount_tax": 0
}
],
"recurrencesByTax": [
{
"type": "one_time",
"amount_total": 1000,
"amount_subtotal": 1000,
"amount_tax": 0,
"tax": {
"tax": {
"rate": 0
},
"amount": 0
}
}
]
}
},
"line_items": [
{
"product_id": "c5695fb5-f02d-4e46-9fb2-a36dc4e9876f",
"price_id": "396cb5f3-ea0b-4629-99ca-303661de5a9b",
"quantity": 1,
"currency": "EUR",
"_price": {
"description": "Standard price component",
"pricing_model": "per_unit",
"unit_amount_currency": "EUR",
"unit_amount": 1000,
"unit_amount_decimal": "10",
"is_tax_inclusive": true,
"price_display_in_journeys": "show_price",
"active": true,
"variable_price": false,
"type": "one_time",
"billing_period": null,
"billing_duration_amount": null,
"billing_duration_unit": null,
"notice_time_amount": null,
"notice_time_unit": null,
"termination_time_amount": null,
"termination_time_unit": null,
"renewal_duration_amount": null,
"renewal_duration_unit": null,
"price_components": null,
"_tags": [],
"_title": "Standard price component",
"_id": "396cb5f3-ea0b-4629-99ca-303661de5a9b",
"internal_description": "Standard price component"
},
"_product": {
"type": "product",
"_title": "Product PH",
"name": "Product PH ",
"price_options": {
"$relation": [
{
"entity_id": "396cb5f3-ea0b-4629-99ca-303661de5a9b",
"_tags": [],
"_schema": "price"
}
]
},
"_id": "c5695fb5-f02d-4e46-9fb2-a36dc4e9876f",
"active": true,
"internal_name": "Product PH",
"description": ""
},
"description": "Standard price component",
"unit_amount": 1000,
"unit_amount_net": 1000,
"unit_amount_net_decimal": "10",
"unit_amount_gross": 1000,
"unit_amount_gross_decimal": "10",
"unit_amount_decimal": "10",
"amount_subtotal": 1000,
"amount_total": 1000,
"amount_tax": 0,
"taxes": [
{
"rate": "nontaxable",
"rateValue": 0,
"amount": 0
}
],
"is_tax_inclusive": true,
"amount_subtotal_decimal": "10",
"amount_total_decimal": "10"
}
],
"currency": "EUR"
}
}
}
},
"400": {
"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/CatalogReferenceError"
}
}
}
}
}
}
},
"/v1/order": {
"post": {
"description": "Create an order",
"operationId": "createOrder",
"summary": "createOrder",
"tags": [
"Order API"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"examples": {
"Order with Simple Prices": {
"value": {
"status": "quote",
"source_type": "manual",
"expires_at": "2022-06-30T16:17:00.000Z",
"line_items": [
{
"price_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
"product_id": "6241487f-b7fd-428b-ab92-24ee0b37fd84",
"quantity": 16,
"is_composite_price": false
},
{
"price_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
"product_id": "6241487f-b7fd-428b-ab92-24ee0b37fd84",
"quantity": 4,
"is_composite_price": false
},
{
"price_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
"product_id": "6241487f-b7fd-428b-ab92-24ee0b37fd84",
"quantity": 1,
"is_composite_price": false
},
{
"price_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
"product_id": "6241487f-b7fd-428b-ab92-24ee0b37fd84",
"quantity": 1,
"is_composite_price": false
}
],
"currency": "EUR",
"payment_method": [
{
"type": "IBAN",
"details": {}
}
],
"billing_contact": {
"$relation": [
{
"entity_id": "1834a54e-b68f-4f7f-a98a-fe16f11bc2a5",
"_tags": []
}
]
},
"billing_first_name": "Joao",
"billing_last_name": "Pinho",
"billing_email": "j.pinho@epilot.cloud",
"billing_company_name": "epilot cloud",
"billing_address": [
{
"_tags": [],
"street": "Im Media Park",
"street_number": "8a",
"postal_code": "52000",
"city": "Cologne",
"country": "DE",
"additional_info": ""
}
],
"delivery_address": [],
"dates": [
{
"_tags": [
"Instalation Date"
],
"dates": "",
"value": "2022-06-30T16:29:00.000Z"
}
]
}
},
"Order with Simple Prices and Dynamic Pricing": {
"value": {
"status": "quote",
"source_type": "manual",
"expires_at": "2022-06-30T16:17:00.000Z",
"line_items": [
{
"price_id": "632b18b5-3f50-4231-b8d5-f8c33a392ed0",
"product_id": "3d1c9987-a7ae-4c1c-a7ef-e12caccab4e0",
"price_mappings": [
{
"price_id": "632b18b5-3f50-4231-b8d5-f8c33a392ed0",
"frequency_unit": "yearly",
"value": 12000,
"name": "Estimated consumption",
"metadata": {
"journey_title": "P&G",
"step_name": "Number Inputs"
}
}
],
"quantity": 16,
"is_composite_price": false
}
],
"currency": "EUR",
"payment_method": [
{
"type": "IBAN",
"details": {}
}
],
"billing_contact": {
"$relation": [
{
"entity_id": "1834a54e-b68f-4f7f-a98a-fe16f11bc2a5",
"_tags": []
}
]
},
"billing_first_name": "Joao",
"billing_last_name": "Pinho",
"billing_email": "j.pinho@epilot.cloud",
"billing_company_name": "epilot cloud",
"billing_address": [
{
"_tags": [],
"street": "Im Media Park",
"street_number": "8a",
"postal_code": "52000",
"city": "Cologne",
"country": "DE",
"additional_info": ""
}
],
"delivery_address": [],
"dates": [
{
"_tags": [
"Instalation Date"
],
"dates": "",
"value": "2022-06-30T16:29:00.000Z"
}
]
}
},
"Order with Composite Prices and Dynamic Pricing": {
"value": {
"status": "quote",
"source_type": "manual",
"expires_at": "2022-06-30T16:17:00.000Z",
"line_items": [
{
"price_id": "b3900bf3-020c-4c58-8af9-32f2682929e3",
"product_id": "924f6881-7ae3-4e2e-a1dd-2d81b8fa2e32",
"price_mappings": [
{
"price_id": "6dc88d6f-ba33-45ee-b5d0-62641344a0d9",
"frequency_unit": "yearly",
"value": 12000,
"name": "Estimated consumption",
"metadata": {
"journey_title": "P&G",
"step_name": "Number Inputs"
}
},
{
"price_id": "60eb12cd-703d-4d41-9265-577ff657bfc9",
"value": 10,
"name": "Distance to power meter",
"metadata": {
"journey_title": "P&G",
"step_name": "Number Inputs"
}
}
],
"quantity": 1,
"is_composite_price": true
}
],
"currency": "EUR",
"payment_method": [
{
"type": "IBAN",
"details": {}
}
],
"billing_contact": {
"$relation": [
{
"entity_id": "1834a54e-b68f-4f7f-a98a-fe16f11bc2a5",
"_tags": []
}
]
},
"billing_first_name": "Joao",
"billing_last_name": "Pinho",
"billing_email": "j.pinho@epilot.cloud",
"billing_company_name": "epilot cloud",
"billing_address": [
{
"_tags": [],
"street": "Im Media Park",
"street_number": "8a",
"postal_code": "52000",
"city": "Cologne",
"country": "DE",
"additional_info": ""
}
],
"delivery_address": [],
"dates": [
{
"_tags": [
"Instalation Date"
],
"dates": "",
"value": "2022-06-30T16:29:00.000Z"
}
]
}
}
},
"schema": {
"$ref": "#/components/schemas/OrderPayload"
}
}
}
},
"responses": {
"201": {
"description": "Order result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
}
},
"400": {
"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/CatalogReferenceError"
}
}
}
}
}
}
},
"/v1/order/{id}": {
"put": {
"description": "Update an existing Order",
"operationId": "putOrder",
"summary": "putOrder",
"tags": [
"Order API"
],
"parameters": [
{
"in": "path",
"name": "id",
"description": "Order entity ID",
"schema": {
"$ref": "#/components/schemas/EntityId"
},
"required": true,
"example": "9d4602d3-03be-4d85-86b2-f3c6555fc606"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderPayload"
},
"examples": {
"Order with Simple Prices": {
"value": {
"status": "quote",
"source_type": "manual",
"expires_at": "2022-06-30T16:17:00.000Z",
"line_items": [
{
"price_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
"product_id": "6241487f-b7fd-428b-ab92-24ee0b37fd84",
"quantity": 16,
"is_composite_price": false
},
{
"price_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
"product_id": "6241487f-b7fd-428b-ab92-24ee0b37fd84",
"quantity": 4,
"is_composite_price": false
},
{
"price_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
"product_id": "6241487f-b7fd-428b-ab92-24ee0b37fd84",
"quantity": 1,
"is_composite_price": false
},
{
"price_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
"product_id": "6241487f-b7fd-428b-ab92-24ee0b37fd84",
"quantity": 1,
"is_composite_price": false
}
],
"currency": "EUR",
"payment_method": [
{
"type": "IBAN",
"details": {}
}
],
"billing_contact": {
"$relation": [
{
"entity_id": "1834a54e-b68f-4f7f-a98a-fe16f11bc2a5",
"_tags": []
}
]
},
"billing_first_name": "Joao",
"billing_last_name": "Pinho",
"billing_email": "j.pinho@epilot.cloud",
"billing_company_name": "epilot cloud",
"billing_address": [
{
"_tags": [],
"street": "Im Media Park",
"street_number": "8a",
"postal_code": "52000",
"city": "Cologne",
"country": "DE",
"additional_info": ""
}
],
"delivery_address": [],
"dates": [
{
"_tags": [
"Instalation Date"
],
"dates": "",
"value": "2022-06-30T16:29:00.000Z"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Order result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Order"
}
}
}
},
"400": {
"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/CatalogReferenceError"
}
}
}
}
}
}
},
"/v1/public/cart:checkout": {
"post": {
"description": "Checkouts a cart and executes the specified checkout `mode` process.\n\nA Checkout implicitly finalizes the provided cart (if not transient from a fast-checkout) and behaves in one of the following modes:\n- `create_order` (**default**): the payment happens at a later date or managed by 3rd-party CRM (SAP)\n- `create_invoice`: the payment happens on the online checkout (paypal, stripe, adyen)\n- `create_quote`: the checkout represents a price quote request\n\nFast checkout is also supported, by passing the Cart contents directly.\nWhen a fast checkout is performed the cart is considered transient and there is no cart persistance.\n\nIf the checkout `mode` is omitted, the `mode` will default to `create_order`.\n",
"operationId": "$checkoutCart",
"summary": "$checkoutCart",
"security": [
{},
{
"EpilotPublicAuth": []
}
],
"tags": [
"Cart API"
],
"parameters": [
{
"in": "header",
"name": "X-Ivy-Org-ID",
"description": "The target Organization Id represented by the caller",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckoutCart"
},
"examples": {
"Checkout with a transient Cart": {
"$ref": "#/components/examples/checkout-with-transient-cart"
}
}
}
}
},
"responses": {
"200": {
"description": "The checkout result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CheckoutCartResult"
},
"examples": {
"Checkout with created order": {
"$ref": "#/components/examples/checkout-result"
}
}
}
}
},
"400": {
"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/CatalogReferenceError"
}
}
}
}
}
}
},
"/v1/public/catalog": {
"post": {
"description": "Provides a querying functionalities over products and prices of the Catalog for a given organization.",
"operationId": "$searchCatalog",
"summary": "$searchCatalog",
"security": [
{},
{
"EpilotPublicAuth": []
}
],
"tags": [
"Catalog API"
],
"parameters": [
{
"in": "header",
"name": "X-Ivy-Org-ID",
"description": "The target Organization Id represented by the caller",
"example": "739224",
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "Authorization",
"description": "The token identifying the client making the request",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogSearch"
}
}
}
},
"responses": {
"200": {
"description": "The search result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogSearchResult"
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/catalog": {
"post": {
"description": "Provides a querying functionalities over products and prices of the Catalog for a given organization.",
"operationId": "$privateSearchCatalog",
"summary": "$privateSearchCatalog",
"tags": [
"Catalog API"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogSearch"
}
}
}
},
"responses": {
"200": {
"description": "The search result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogSearchResult"
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/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",
"summary": "$validatePromoCodes",
"operationId": "$validatePromoCodes",
"tags": [
"Promo Codes API"
],
"security": [
{
"EpilotPublicAuth": []
}
],
"parameters": [
{
"in": "header",
"name": "X-Ivy-Org-ID",
"description": "The target Organization Id represented by the caller",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"properties": {
"coupon_ids": {
"type": "array",
"description": "The list of coupon ids to unlock with promo codes",
"items": {
"type": "string"
}
},
"promo_codes": {
"type": "array",
"description": "The list of promo codes to validate against the coupons",
"items": {
"type": "string"
}
}
}
},
"examples": {
"Find coupons matching codes": {
"value": {
"coupon_ids": [
"81b8e841-5926-4a73-ac77-6607c1037b65",
"45964a30-1a42-4e59-9362-7d954baf4ea1"
],
"promo_codes": [
"ABC",
"DEF"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "Pricing details result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PromoCodeValidationResponse"
},
"example": {
"matched_coupons": [
{
"name": "Coupon with promo-codes",
"type": "fixed",
"percentage_value": null,
"fixed_value": 10,
"fixed_value_currency": "EUR",
"fixed_value_decimal": "10.00",
"category": "discount",
"cashback_period": "12",
"active": true,
"_schema": "coupon",
"requires_promo_code": true,
"_id": "81b8e841-5926-4a73-ac77-6607c1037b65",
"_org": "739224",
"_owners": [
{
"org_id": "739224",
"user_id": "11000622"
}
],
"_created_at": "2025-01-29T15:46:41.014Z",
"_updated_at": "2025-01-29T15:46:41.014Z",
"_title": "Coupon with promo-codes"
}
]
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/public/availability:check": {
"post": {
"description": "The availability check endpoint",
"operationId": "$availabilityCheck",
"summary": "$availabilityCheck",
"security": [
{
"EpilotPublicAuth": []
}
],
"tags": [
"Availability API"
],
"parameters": [
{
"in": "header",
"name": "X-Ivy-Org-ID",
"description": "The target Organization Id represented by the caller",
"schema": {
"type": "string"
},
"required": true
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AvailabilityCheckParams"
},
"examples": {
"Check availability with location dimension": {
"value": {
"products": [
"cd75456a-30e4-4912-95be-e743d5ea175b"
],
"filters": {
"location": {
"postal_code": "57008",
"city": "Cologne",
"street": "Media Park",
"street_number": "8a"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "The availability check result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AvailabilityResult"
},
"examples": {
"Response with available products": {
"value": {
"available_products": [
"cd75456a-30e4-4912-95be-e743d5ea175b"
],
"check_results": [
{
"product_id": "cd75456a-30e4-4912-95be-e743d5ea175b",
"matching_hits": 1
}
]
}
},
"Response with no available products": {
"value": {
"available_products": []
}
},
"Response with available and unavailable products": {
"value": {
"available_products": [
"my-product-id-123-2"
],
"checkResults": [
{
"productId": "my-product-id-123-1",
"matchingError": {
"msg": "Error - Unknown file extension for availability file."
}
},
{
"matchingHits": 1,
"productId": "my-product-id-123-2"
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/validate-availability/{id}": {
"get": {
"description": "Validates an availability file, it returns an array of errors if the file is invalid",
"operationId": "$validateAvailabilityFile",
"summary": "$validateAvailabilityFile",
"tags": [
"Availability API"
],
"parameters": [
{
"in": "path",
"name": "id",
"description": "Product ID that the Availability File is attached to",
"schema": {
"type": "string"
},
"required": true,
"example": "72c803b2-2e5d-4bd6-bffc-fad998bbbe36"
},
{
"in": "header",
"name": "X-Epilot-Org-ID",
"description": "The target Organization Id represented by the caller",
"schema": {
"type": "string"
},
"required": true,
"example": "739224"
}
],
"responses": {
"200": {
"description": "The availability get result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidateAvailabilityFileResult"
},
"examples": {
"Response when file has no errors": {
"value": {
"status": "success",
"rules_parsed_count": 10,
"errors": []
}
},
"Response when file has errors": {
"value": {
"status": "error",
"rules_parsed_count": 8,
"errors": [
{
"line": 3,
"msg": "Postal code is missing or invalid",
"data": "Postal code: 12345"
},
{
"line": 4,
"msg": "Postal code is missing or invalid",
"data": "Postal code: 12345"
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/public/historicMarketPrices": {
"get": {
"description": "Get a series of historic energy prices for a given time period, market and bidding zone.",
"operationId": "$historicMarketPrices",
"summary": "$historicMarketPrices",
"tags": [
"Spot Market API"
],
"security": [
{
"EpilotPublicAuth": []
}
],
"parameters": [
{
"in": "query",
"name": "market",
"schema": {
"$ref": "#/components/schemas/SpotMarketType"
},
"required": true,
"description": "Market to use. For now, only day ahead prices are supported."
},
{
"in": "query",
"name": "bidding_zone",
"schema": {
"$ref": "#/components/schemas/SpotMarketBiddingZone"
},
"required": true,
"description": "Bidding zone to use. For now, only AT and DE-LU are supported."
},
{
"in": "query",
"name": "frequency",
"schema": {
"$ref": "#/components/schemas/SpotMarketDataFrequency"
},
"required": true,
"description": "Frequency of the price data points in ISO 8601 format."
},
{
"in": "query",
"name": "from",
"schema": {
"type": "string",
"anyOf": [
{
"format": "date"
},
{
"format": "date-time"
}
]
},
"required": true,
"description": "Start of price data in ISO 8601 format.\nIf only a date is provided (YYYY-MM-DD) the timzone of the bidding zone is used.\n"
},
{
"in": "query",
"name": "to",
"schema": {
"type": "string",
"anyOf": [
{
"format": "date"
},
{
"format": "date-time"
}
]
},
"required": true,
"description": "End of price data in ISO 8601 format.\nIf only a date is provided (YYYY-MM-DD) the timzone of the bidding zone is used.\n"
}
],
"responses": {
"200": {
"description": "Price data returned successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HistoricMarketPricesResult"
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "No prices for date range found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/public/averageMarketPrice": {
"get": {
"description": "Get the average energy prices for a given time period, market and bidding zone.",
"operationId": "$averageMarketPrice",
"summary": "$averageMarketPrice",
"tags": [
"Spot Market API"
],
"security": [
{
"EpilotPublicAuth": []
}
],
"parameters": [
{
"in": "query",
"name": "market",
"schema": {
"$ref": "#/components/schemas/SpotMarketType"
},
"required": true,
"description": "Market to use. For now, only day ahead prices are supported."
},
{
"in": "query",
"name": "bidding_zone",
"schema": {
"$ref": "#/components/schemas/SpotMarketBiddingZone"
},
"required": true,
"description": "Bidding zone to use. For now, only AT and DE-LU are supported."
},
{
"in": "query",
"name": "from",
"schema": {
"type": "string",
"anyOf": [
{
"format": "date"
},
{
"format": "date-time"
}
]
},
"required": true,
"description": "Start of price data in ISO 8601 format.\nIf only a date is provided (YYYY-MM-DD) the timzone of the bidding zone is used.\n"
},
{
"in": "query",
"name": "to",
"schema": {
"type": "string",
"anyOf": [
{
"format": "date"
},
{
"format": "date-time"
}
]
},
"required": true,
"description": "End of price data in ISO 8601 format.\nIf only a date is provided (YYYY-MM-DD) the timzone of the bidding zone is used.\n"
}
],
"responses": {
"200": {
"description": "Price data returned successfully.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AverageMarketPriceResult"
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "No prices for date range found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/public/integration/{integrationId}/products": {
"post": {
"description": "Returns the list of available products with computed prices based on a given context and for a given org integration.",
"operationId": "$searchExternalProducts",
"security": [
{},
{
"EpilotPublicAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "integrationId",
"description": "The integration identifier",
"schema": {
"$ref": "#/components/schemas/IntegrationId"
},
"required": true,
"example": "external-catalog"
}
],
"summary": "$searchExternalProducts",
"tags": [
"External Integrations API"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchExternalCatalogParams"
}
}
}
},
"responses": {
"200": {
"description": "The available products response payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchExternalCatalogResult"
},
"examples": {
"External products": {
"value": {
"hits": 1,
"results": [
{
"pricing_details": {
"items": [
{
"_id": "price-12312414",
"price_id": "price-12312414",
"is_composite_price": true,
"description": "Home Energy Package Composite",
"item_components": [
{
"_id": "price-12312414-component-0",
"price_id": "price-12312414-component-0",
"description": "Working Price",
"is_tax_inclusive": true,
"amount_total_decimal": "100",
"amount_total": 10000,
"amount_subtotal_decimal": "100",
"amount_subtotal": 10000,
"unit_amount": 10,
"unit_amount_gross": 10,
"unit_amount_gross_decimal": "0.10",
"unit_amount_net": 10,
"unit_amount_net_decimal": "0.10",
"billing_period": "monthly",
"type": "recurring",
"taxes": [],
"pricing_model": "per_unit",
"quantity": 1,
"_price": {
"_id": "price-12312414-component-0",
"unit_amount_currency": "EUR",
"description": "Working Price",
"is_tax_inclusive": true,
"unit_amount": 10,
"unit_amount_decimal": "0.10",
"unit": "kWh",
"billing_period": "monthly",
"type": "recurring",
"billing_duration_amount": 24,
"billing_duration_unit": "months",
"notice_time_amount": 3,
"notice_time_unit": "months",
"termination_time_amount": 3,
"termination_time_unit": "months",
"renewal_duration_amount": 12,
"renewal_duration_unit": "months",
"active": true,
"is_composite_price": false,
"variable_price": true,
"pricing_model": "per_unit",
"price_display_in_journeys": "show_price"
}
}
]
}
],
"currency": "EUR",
"amount_subtotal": 10000,
"amount_total": 10000,
"amount_tax": 0,
"total_details": {
"amount_tax": 0,
"breakdown": {
"taxes": [],
"recurrences": [
{
"type": "recurring",
"billing_period": "monthly",
"amount_total": 10000,
"amount_total_decimal": "100.00",
"amount_subtotal": 10000,
"amount_subtotal_decimal": "100.00",
"amount_tax": 0
}
]
}
}
},
"_meta": {
"signature": "abc123",
"timestamp": 1712049221642
}
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden, no credentials found for the given integration / organization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/public/integration/{integrationId}/product-recommendations": {
"post": {
"description": "Returns the list of available product recommendations with computed prices based on a given context and for a given org integration.",
"operationId": "$searchExternalProductRecommendations",
"security": [
{},
{
"EpilotPublicAuth": []
}
],
"parameters": [
{
"in": "path",
"name": "integrationId",
"description": "The integration identifier",
"schema": {
"$ref": "#/components/schemas/IntegrationId"
},
"required": true,
"example": "external-catalog"
}
],
"summary": "$searchExternalProductRecommendations",
"tags": [
"External Integrations API"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchExternalCatalogParams"
},
"examples": {
"Search recommendations": {
"value": {
"context": {
"journey_id": "8d0a2235-97ce-42d0-88a3-e374634ca44e",
"journey_name": "Energy Provider Selection",
"current_step_name": "product-selection",
"current_block_name": "recommendations-block",
"steps_data": [
{
"step_name": "address",
"step_index": 1,
"blocks": {
"Adresse": {
"countryCode": "DE",
"city": "Koblenz",
"zipCode": "56068",
"streetName": "Am Alten Hospital",
"houseNumber": "123"
}
}
}
]
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "The available products response payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchExternalCatalogRecommendationsResult"
},
"examples": {
"External catalog recommendations": {
"value": {
"source": {
"pricing_details": {
"items": [
{
"_id": "price-12312414",
"price_id": "price-12312414",
"product_id": "product-12312414",
"is_composite_price": true,
"description": "Home Energy Package Composite",
"item_components": [
{
"_id": "price-12312414-component-0",
"price_id": "price-12312414-component-0",
"product_id": "product-12312414",
"description": "Working Price",
"is_tax_inclusive": true,
"amount_total_decimal": "50",
"amount_total": 5000,
"amount_subtotal_decimal": "50",
"amount_subtotal": 5000,
"unit_amount": 5,
"unit_amount_gross": 5,
"unit_amount_gross_decimal": "0.05",
"unit_amount_net": 5,
"unit_amount_net_decimal": "0.05",
"billing_period": "monthly",
"type": "recurring",
"taxes": [],
"pricing_model": "per_unit",
"quantity": 1,
"_price": {
"_id": "price-12312414-component-0",
"unit_amount_currency": "EUR",
"description": "Working Price",
"is_tax_inclusive": true,
"unit_amount": 5,
"unit_amount_decimal": "0.05",
"unit": "kWh",
"billing_period": "monthly",
"type": "recurring",
"billing_duration_amount": 24,
"billing_duration_unit": "months",
"notice_time_amount": 3,
"notice_time_unit": "months",
"termination_time_amount": 3,
"termination_time_unit": "months",
"renewal_duration_amount": 12,
"renewal_duration_unit": "months",
"active": true,
"is_composite_price": false,
"variable_price": true,
"pricing_model": "per_unit",
"price_display_in_journeys": "show_price"
},
"_product": {
"_id": "product-12312414",
"name": "Home Energy Package",
"description": "Composite home energy solution with solar panels and battery"
}
}
]
}
],
"currency": "EUR",
"amount_subtotal": 5000,
"amount_total": 5000,
"amount_tax": 0,
"total_details": {
"amount_tax": 0,
"breakdown": {
"taxes": [],
"recurrences": [
{
"type": "recurring",
"billing_period": "monthly",
"amount_total": 5000,
"amount_total_decimal": "50.00",
"amount_subtotal": 5000,
"amount_subtotal_decimal": "50.00",
"amount_tax": 0
}
]
}
}
},
"_meta": {
"signature": "abc123",
"timestamp": 1712049221642
}
},
"offers": [
{
"pricing_details": {
"items": [
{
"_id": "price-999857a4",
"price_id": "price-999857a4",
"product_id": "product-999857a4",
"is_composite_price": false,
"description": "Single Price",
"is_tax_inclusive": true,
"amount_total_decimal": "25",
"amount_total": 2500,
"amount_subtotal_decimal": "25",
"amount_subtotal": 2500,
"unit_amount": 25,
"unit_amount_gross": 25,
"unit_amount_gross_decimal": "25",
"unit_amount_net": 25,
"unit_amount_net_decimal": "25",
"type": "one_time",
"taxes": [],
"pricing_model": "per_unit",
"quantity": 1,
"_price": {
"_id": "price-999857a4",
"unit_amount_currency": "EUR",
"description": "Single Price",
"is_tax_inclusive": true,
"unit_amount": 25,
"unit_amount_decimal": "25",
"billing_duration_amount": 24,
"billing_duration_unit": "months",
"notice_time_amount": 3,
"notice_time_unit": "months",
"termination_time_amount": 3,
"termination_time_unit": "months",
"renewal_duration_amount": 12,
"renewal_duration_unit": "months",
"active": true,
"is_composite_price": false,
"pricing_model": "per_unit",
"price_display_in_journeys": "show_price"
},
"_product": {
"_id": "product-999857a4",
"name": "Solar Panel X2",
"description": "High-efficiency solar panel for residential use"
}
}
]
},
"currency": "EUR",
"amount_subtotal": 2500,
"amount_total": 2500,
"amount_tax": 0,
"total_details": {
"amount_tax": 0,
"breakdown": {
"taxes": [],
"recurrences": [
{
"type": "one_time",
"amount_total": 2500,
"amount_total_decimal": "25.00",
"amount_subtotal": 2500,
"amount_subtotal_decimal": "25.00",
"amount_tax": 0
}
]
}
},
"_meta": {
"signature": "def456",
"timestamp": 1712049221643
}
},
{
"pricing_details": {
"items": [
{
"_id": "price-93f857a4",
"price_id": "price-93f857a4",
"product_id": "product-93f857a4",
"is_composite_price": false,
"description": "Single Price",
"is_tax_inclusive": false,
"amount_total_decimal": "29.75",
"amount_total": 2975,
"amount_subtotal_decimal": "25",
"amount_subtotal": 2500,
"unit_amount": 25,
"unit_amount_gross": 2975,
"unit_amount_gross_decimal": "29.75",
"unit_amount_net": 25,
"unit_amount_net_decimal": "25",
"type": "one_time",
"taxes": [
{
"tax": {
"_id": "24641e82-0690-4135-8b43-ef12a9b1c5dc",
"_title": "VAT 19%",
"_org": "728",
"_schema": "tax",
"_created_at": "2024-01-01T00:00:00.000Z",
"_updated_at": "2024-01-01T00:00:00.000Z",
"type": "VAT",
"rate": 19
},
"amount": 475
}
],
"pricing_model": "per_unit",
"quantity": 1,
"_price": {
"_id": "price-93f857a4",
"unit_amount_currency": "EUR",
"description": "Single Price",
"is_tax_inclusive": false,
"unit_amount": 25,
"unit_amount_decimal": "25",
"active": true,
"is_composite_price": false,
"pricing_model": "per_unit",
"price_display_in_journeys": "show_price",
"tax": {
"_id": "24641e82-0690-4135-8b43-ef12a9b1c5dc",
"_title": "VAT 19%",
"_org": "728",
"_schema": "tax",
"_created_at": "2024-01-01T00:00:00.000Z",
"_updated_at": "2024-01-01T00:00:00.000Z",
"type": "VAT",
"rate": 19
}
},
"_product": {
"_id": "product-93f857a4",
"name": "Solar Panel X3",
"description": "New generation of high-efficiency solar panel for residential use"
}
}
]
},
"currency": "EUR",
"amount_subtotal": 2500,
"amount_total": 2975,
"amount_tax": 475,
"total_details": {
"amount_tax": 475,
"breakdown": {
"taxes": [
{
"tax": {
"_id": "24641e82-0690-4135-8b43-ef12a9b1c5dc",
"_title": "VAT 19%",
"_org": "728",
"_schema": "tax",
"_created_at": "2024-01-01T00:00:00.000Z",
"_updated_at": "2024-01-01T00:00:00.000Z",
"type": "VAT",
"rate": 19
},
"amount": 475
}
],
"recurrences": [
{
"type": "one_time",
"amount_total": 2975,
"amount_total_decimal": "29.75",
"amount_subtotal": 2500,
"amount_subtotal_decimal": "25.00",
"amount_tax": 475
}
]
}
},
"_meta": {
"signature": "ghi789",
"timestamp": 1712049221644
}
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden, no credentials found for the given integration / organization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/public/integration/{integrationId}/providers:search": {
"post": {
"description": "Returns the list of providers available based on a given location",
"operationId": "$searchProviders",
"security": [
{},
{
"EpilotPublicAuth": []
}
],
"parameters": [
{
"in": "header",
"name": "X-Epilot-Org-ID",
"description": "The target Organization Id represented by the caller",
"schema": {
"type": "string"
},
"required": true,
"example": "739224"
},
{
"in": "path",
"name": "integrationId",
"description": "The integration identifier",
"schema": {
"$ref": "#/components/schemas/IntegrationId"
},
"required": true,
"example": "getag"
}
],
"summary": "$searchProviders",
"tags": [
"External Integrations API"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchProvidersParams"
},
"examples": {
"Search providers (power)": {
"value": {
"type": "power",
"postal_code": "04109",
"city": "Leipzig",
"street": "Willy-Brandt-Platz"
}
},
"Search providers (gas)": {
"value": {
"type": "gas",
"postal_code": "57008",
"city": "Cologne",
"street": "Media Park",
"street_number": "8a"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The available providers response payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchProvidersResult"
},
"examples": {
"Response with available providers": {
"value": [
{
"name": "Provider 1",
"code": "code#1",
"type": "power",
"additionalData": {
"gridOperators": [
{
"name": "Grid Operator 1",
"codeNumber": "9900000000000"
}
],
"defaultSuppliers": [
{
"name": "Default Supplier 1",
"codeNumber": "9900000000001"
}
],
"marketAreaDetails": {
"controlZone": "10YDE-VE-------2",
"balancingZone": "10YDE-VE-------2"
}
}
},
{
"name": "Provider 2",
"code": "code#2",
"type": "gas",
"additionalData": {
"gridOperators": [
{
"name": "Grid Operator 2",
"codeNumber": "9870000000000"
}
],
"defaultSuppliers": [
{
"name": "Default Supplier 2",
"codeNumber": "9870000000001"
}
],
"marketAreaDetails": {
"gasType": "H-Gas",
"marketArea": "NCG",
"virtualTradingPoint": "VHP"
}
}
}
]
}
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden, no credentials found for the given integration / organization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/public/integration/{integrationId}/streets:search": {
"post": {
"description": "Returns the list of streets available for a given postal code and city",
"operationId": "$searchStreets",
"security": [
{},
{
"EpilotPublicAuth": []
}
],
"parameters": [
{
"in": "header",
"name": "X-Epilot-Org-ID",
"description": "The target Organization Id represented by the caller",
"schema": {
"type": "string"
},
"required": true,
"example": "739224"
},
{
"in": "path",
"name": "integrationId",
"description": "The integration identifier",
"schema": {
"$ref": "#/components/schemas/IntegrationId"
},
"required": true,
"example": "getag"
}
],
"summary": "$searchStreets",
"tags": [
"External Integrations API"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchStreetsParams"
},
"examples": {
"Search streets": {
"value": {
"postal_code": "04109",
"city": "Leipzig"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The available streets response payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchStreetsResult"
},
"examples": {
"Response with available streets": {
"value": [
{
"street": "Street 1"
},
{
"street": "Street 2"
}
]
}
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden, no credentials found for the given integration / organization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/public/integration/{integrationId}/compute-price": {
"post": {
"description": "Returns the price for a given product type based on location and consumption",
"operationId": "$computePrice",
"security": [
{},
{
"EpilotPublicAuth": []
}
],
"parameters": [
{
"in": "header",
"name": "X-Epilot-Org-ID",
"description": "The target Organization Id represented by the caller",
"schema": {
"type": "string"
},
"required": true,
"example": "739224"
},
{
"in": "path",
"name": "integrationId",
"description": "The integration identifier",
"schema": {
"$ref": "#/components/schemas/IntegrationId"
},
"required": true,
"example": "getag"
}
],
"summary": "$computePrice",
"tags": [
"External Integrations API"
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ComputePriceParams"
},
"examples": {
"Compute price": {
"value": {
"type": "power",
"billing_period": "monthly",
"postal_code": "04109",
"city": "Leipzig",
"consumption": 3500,
"association_id": "123456789"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The compute price response payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ComputePriceResult"
},
"examples": {
"Response of computed price": {
"value": {
"amount_total": 100,
"amount_total_decimal": "100.00",
"amount_static": 500,
"amount_static_decimal": "50.00",
"amount_variable": 500,
"amount_variable_decimal": "50.00",
"currency": "EUR",
"billing_period": "monthly",
"breakdown": {
"static": {
"maintenance_fee": {
"amount": 50,
"amount_decimal": "50.00"
}
},
"variable": {
"offshore_liability_fee": {
"amount": 50,
"amount_decimal": "50.00"
}
}
},
"inputs": {
"type": "power",
"consumptionHT": 3500,
"zipCode": "04109",
"city": "Leipzig",
"billingPeriod": "monthly"
}
}
}
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden, no credentials found for the given integration / organization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/integration/{integrationId}/credentials": {
"get": {
"description": "Gets the credentials for a given integration / organization",
"operationId": "$getCredentials",
"summary": "$getCredentials",
"tags": [
"External Integrations API"
],
"parameters": [
{
"in": "path",
"name": "integrationId",
"description": "The integration identifier",
"schema": {
"$ref": "#/components/schemas/IntegrationId"
},
"required": true,
"example": "getag"
}
],
"responses": {
"200": {
"description": "The credentials response payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegrationCredentialsResult"
},
"examples": {
"Response when credentials": {
"value": {
"username": "username",
"password": "password"
}
}
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Credentials not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/integration/{integrationId}/credentials:save": {
"put": {
"description": "Saves the credentials for a given integration / organization",
"operationId": "$saveCredentials",
"summary": "$saveCredentials",
"tags": [
"External Integrations API"
],
"parameters": [
{
"in": "path",
"name": "integrationId",
"description": "The integration identifier",
"schema": {
"$ref": "#/components/schemas/IntegrationId"
},
"required": true,
"example": "getag"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SaveIntegrationCredentialsParams"
},
"examples": {
"Save credentials": {
"value": {
"username": "username",
"password": "password"
}
}
}
}
}
},
"responses": {
"204": {
"description": "Credentials saved"
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/integration/{integrationId}/credentials:delete": {
"delete": {
"description": "Delete the credentials for a given integration / organization",
"operationId": "$deleteCredentials",
"summary": "$deleteCredentials",
"tags": [
"External Integrations API"
],
"parameters": [
{
"in": "path",
"name": "integrationId",
"description": "The integration identifier",
"schema": {
"$ref": "#/components/schemas/IntegrationId"
},
"required": true,
"example": "getag"
}
],
"responses": {
"204": {
"description": "Credentials deleted"
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/public/external-catalog/products": {
"post": {
"description": "Returns the list of available external catalog products with computed prices based on a given context",
"operationId": "$getExternalCatalogProducts",
"security": [
{},
{
"EpilotPublicAuth": []
}
],
"summary": "$getExternalCatalogProducts",
"tags": [
"External Catalog API"
],
"parameters": [
{
"in": "header",
"name": "x-epilot-org-id",
"schema": {
"type": "string"
},
"required": false,
"description": "Organization ID (required when not using EpilotPublicAuth token)"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalCatalogRequest"
}
}
}
},
"responses": {
"200": {
"description": "The available external catalog products response payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchExternalCatalogResult"
},
"examples": {
"External products": {
"value": {
"hits": 1,
"results": [
{
"pricing_details": {
"items": [
{
"_id": "price-12312414",
"price_id": "price-12312414",
"is_composite_price": true,
"description": "Home Energy Package Composite",
"item_components": [
{
"_id": "price-12312414-component-0",
"price_id": "price-12312414-component-0",
"description": "Working Price",
"is_tax_inclusive": true,
"amount_total_decimal": "100",
"amount_total": 10000,
"amount_subtotal_decimal": "100",
"amount_subtotal": 10000,
"unit_amount": 10,
"unit_amount_gross": 10,
"unit_amount_gross_decimal": "0.10",
"unit_amount_net": 10,
"unit_amount_net_decimal": "0.10",
"billing_period": "monthly",
"type": "recurring",
"taxes": [],
"pricing_model": "per_unit",
"quantity": 1,
"_price": {
"_id": "price-12312414-component-0",
"unit_amount_currency": "EUR",
"description": "Working Price",
"is_tax_inclusive": true,
"unit_amount": 10,
"unit_amount_decimal": "0.10",
"unit": "kWh",
"billing_period": "monthly",
"type": "recurring",
"billing_duration_amount": 24,
"billing_duration_unit": "months",
"notice_time_amount": 3,
"notice_time_unit": "months",
"termination_time_amount": 3,
"termination_time_unit": "months",
"renewal_duration_amount": 12,
"renewal_duration_unit": "months",
"active": true,
"is_composite_price": false,
"variable_price": true,
"pricing_model": "per_unit",
"price_display_in_journeys": "show_price"
}
}
]
}
],
"currency": "EUR",
"amount_subtotal": 10000,
"amount_total": 10000,
"amount_tax": 0,
"total_details": {
"amount_tax": 0,
"breakdown": {
"taxes": [],
"recurrences": [
{
"type": "recurring",
"billing_period": "monthly",
"amount_total": 10000,
"amount_total_decimal": "100.00",
"amount_subtotal": 10000,
"amount_subtotal_decimal": "100.00",
"amount_tax": 0
}
]
}
}
},
"_meta": {
"signature": "abc123",
"timestamp": 1712049221642
}
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden, no valid configuration found for the given integration / organization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/public/external-catalog/product-recommendations": {
"post": {
"description": "Returns the list of available external catalog products recommendations based on a given context",
"operationId": "$getExternalCatalogProductRecommendations",
"security": [
{},
{
"EpilotPublicAuth": []
}
],
"summary": "$getExternalCatalogProductRecommendations",
"tags": [
"External Catalog API"
],
"parameters": [
{
"in": "header",
"name": "x-epilot-org-id",
"schema": {
"type": "string"
},
"required": false,
"description": "Organization ID (required when not using EpilotPublicAuth token)"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ExternalCatalogRequest"
}
}
}
},
"responses": {
"200": {
"description": "The available products response payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchExternalCatalogRecommendationsResult"
},
"examples": {
"External catalog recommendations": {
"value": {
"source": {
"pricing_details": {
"items": [
{
"_id": "price-12312414",
"price_id": "price-12312414",
"product_id": "product-12312414",
"is_composite_price": true,
"description": "Home Energy Package Composite",
"item_components": [
{
"_id": "price-12312414-component-0",
"price_id": "price-12312414-component-0",
"product_id": "product-12312414",
"description": "Working Price",
"is_tax_inclusive": true,
"amount_total_decimal": "50",
"amount_total": 5000,
"amount_subtotal_decimal": "50",
"amount_subtotal": 5000,
"unit_amount": 5,
"unit_amount_gross": 5,
"unit_amount_gross_decimal": "0.05",
"unit_amount_net": 5,
"unit_amount_net_decimal": "0.05",
"billing_period": "monthly",
"type": "recurring",
"taxes": [],
"pricing_model": "per_unit",
"quantity": 1,
"_price": {
"_id": "price-12312414-component-0",
"unit_amount_currency": "EUR",
"description": "Working Price",
"is_tax_inclusive": true,
"unit_amount": 5,
"unit_amount_decimal": "0.05",
"unit": "kWh",
"billing_period": "monthly",
"type": "recurring",
"billing_duration_amount": 24,
"billing_duration_unit": "months",
"notice_time_amount": 3,
"notice_time_unit": "months",
"termination_time_amount": 3,
"termination_time_unit": "months",
"renewal_duration_amount": 12,
"renewal_duration_unit": "months",
"active": true,
"is_composite_price": false,
"variable_price": true,
"pricing_model": "per_unit",
"price_display_in_journeys": "show_price"
},
"_product": {
"_id": "product-12312414",
"name": "Home Energy Package",
"description": "Composite home energy solution with solar panels and battery"
}
}
]
}
],
"currency": "EUR",
"amount_subtotal": 5000,
"amount_total": 5000,
"amount_tax": 0,
"total_details": {
"amount_tax": 0,
"breakdown": {
"taxes": [],
"recurrences": [
{
"type": "recurring",
"billing_period": "monthly",
"amount_total": 5000,
"amount_total_decimal": "50.00",
"amount_subtotal": 5000,
"amount_subtotal_decimal": "50.00",
"amount_tax": 0
}
]
}
}
},
"_meta": {
"signature": "abc123",
"timestamp": 1712049221642
}
},
"offers": [
{
"pricing_details": {
"items": [
{
"_id": "price-999857a4",
"price_id": "price-999857a4",
"product_id": "product-999857a4",
"is_composite_price": false,
"description": "Single Price",
"is_tax_inclusive": true,
"amount_total_decimal": "25",
"amount_total": 2500,
"amount_subtotal_decimal": "25",
"amount_subtotal": 2500,
"unit_amount": 25,
"unit_amount_gross": 25,
"unit_amount_gross_decimal": "25",
"unit_amount_net": 25,
"unit_amount_net_decimal": "25",
"type": "one_time",
"taxes": [],
"pricing_model": "per_unit",
"quantity": 1,
"_price": {
"_id": "price-999857a4",
"unit_amount_currency": "EUR",
"description": "Single Price",
"is_tax_inclusive": true,
"unit_amount": 25,
"unit_amount_decimal": "25",
"billing_duration_amount": 24,
"billing_duration_unit": "months",
"notice_time_amount": 3,
"notice_time_unit": "months",
"termination_time_amount": 3,
"termination_time_unit": "months",
"renewal_duration_amount": 12,
"renewal_duration_unit": "months",
"active": true,
"is_composite_price": false,
"pricing_model": "per_unit",
"price_display_in_journeys": "show_price"
},
"_product": {
"_id": "product-999857a4",
"name": "Solar Panel X2",
"description": "High-efficiency solar panel for residential use"
}
}
]
},
"currency": "EUR",
"amount_subtotal": 2500,
"amount_total": 2500,
"amount_tax": 0,
"total_details": {
"amount_tax": 0,
"breakdown": {
"taxes": [],
"recurrences": [
{
"type": "one_time",
"amount_total": 2500,
"amount_total_decimal": "25.00",
"amount_subtotal": 2500,
"amount_subtotal_decimal": "25.00",
"amount_tax": 0
}
]
}
},
"_meta": {
"signature": "def456",
"timestamp": 1712049221643
}
},
{
"pricing_details": {
"items": [
{
"_id": "price-93f857a4",
"price_id": "price-93f857a4",
"product_id": "product-93f857a4",
"is_composite_price": false,
"description": "Single Price",
"is_tax_inclusive": false,
"amount_total_decimal": "29.75",
"amount_total": 2975,
"amount_subtotal_decimal": "25",
"amount_subtotal": 2500,
"unit_amount": 25,
"unit_amount_gross": 2975,
"unit_amount_gross_decimal": "29.75",
"unit_amount_net": 25,
"unit_amount_net_decimal": "25",
"type": "one_time",
"taxes": [
{
"tax": {
"_id": "24641e82-0690-4135-8b43-ef12a9b1c5dc",
"_title": "VAT 19%",
"_org": "728",
"_schema": "tax",
"_created_at": "2024-01-01T00:00:00.000Z",
"_updated_at": "2024-01-01T00:00:00.000Z",
"type": "VAT",
"rate": 19
},
"amount": 475
}
],
"pricing_model": "per_unit",
"quantity": 1,
"_price": {
"_id": "price-93f857a4",
"unit_amount_currency": "EUR",
"description": "Single Price",
"is_tax_inclusive": false,
"unit_amount": 25,
"unit_amount_decimal": "25",
"active": true,
"is_composite_price": false,
"pricing_model": "per_unit",
"price_display_in_journeys": "show_price",
"tax": {
"_id": "24641e82-0690-4135-8b43-ef12a9b1c5dc",
"_title": "VAT 19%",
"_org": "728",
"_schema": "tax",
"_created_at": "2024-01-01T00:00:00.000Z",
"_updated_at": "2024-01-01T00:00:00.000Z",
"type": "VAT",
"rate": 19
}
},
"_product": {
"_id": "product-93f857a4",
"name": "Solar Panel X3",
"description": "New generation of high-efficiency solar panel for residential use"
}
}
]
},
"currency": "EUR",
"amount_subtotal": 2500,
"amount_total": 2975,
"amount_tax": 475,
"total_details": {
"amount_tax": 475,
"breakdown": {
"taxes": [
{
"tax": {
"_id": "24641e82-0690-4135-8b43-ef12a9b1c5dc",
"_title": "VAT 19%",
"_org": "728",
"_schema": "tax",
"_created_at": "2024-01-01T00:00:00.000Z",
"_updated_at": "2024-01-01T00:00:00.000Z",
"type": "VAT",
"rate": 19
},
"amount": 475
}
],
"recurrences": [
{
"type": "one_time",
"amount_total": 2975,
"amount_total_decimal": "29.75",
"amount_subtotal": 2500,
"amount_subtotal_decimal": "25.00",
"amount_tax": 475
}
]
}
},
"_meta": {
"signature": "ghi789",
"timestamp": 1712049221644
}
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Forbidden, no credentials found for the given integration / organization",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/public/product-recommendations": {
"post": {
"description": "Get a list of product recommendations based on the search parameters.",
"operationId": "$productRecommendations",
"summary": "$productRecommendations",
"security": [
{
"EpilotPublicAuth": []
}
],
"tags": [
"Product Recommendations API"
],
"parameters": [
{
"in": "header",
"name": "X-Ivy-Org-ID",
"description": "The target Organization Id represented by the caller",
"example": "739224",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductRecommendationSearch"
},
"examples": {
"Search product recommendations by id": {
"value": {
"product_recommendation_ids": [
"22c134b7-8dd8-4872-a5c1-8fc6dd4ac2ee"
]
}
},
"Search product recommendations by id with location filter": {
"value": {
"product_recommendation_ids": [
"22c134b7-8dd8-4872-a5c1-8fc6dd4ac2ee"
],
"filters": {
"location": {
"postal_code": "50670",
"city": "Köln"
}
}
}
},
"Search product recommendations by source product and price": {
"value": {
"catalog_item": {
"product_id": "aa1ebf85-f36e-46ff-978c-ed948c646f12",
"price_id": "4ecf9a61-a974-4594-bae2-bcb798f54d76"
}
}
},
"Search product recommendations by contract": {
"value": {
"contract_id": "98ffca40-46ab-4288-af10-a478893b2aa2"
}
}
}
}
}
},
"responses": {
"200": {
"description": "The product recommendations result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductRecommendationResponse"
},
"examples": {
"Product recommendations": {
"value": {
"hits": 1,
"results": [
{
"_title": "Tarifwechsel 2025",
"_created_at": "2025-01-29T15:46:41.014Z",
"_updated_at": "2025-01-29T15:46:41.014Z",
"name": "Tarifwechsel 2025",
"type": "change",
"source_product": {
"$relation": [
{
"entity_id": "e2b12b54-d904-42b7-ac44-802d8ebaadf4"
}
]
},
"source_price": {
"$relation": [
{
"entity_id": "255877f3-f9c2-483e-9c71-89088c142bfc"
}
]
},
"_schema": "product_recommendation",
"offers": [
{
"target_id": "f9aa8757-505b-46bd-9310-605d64849565",
"items": [
{
"product_id": "70ad8a08-46c2-473b-b1c5-8bccfb85e452",
"price_id": "26c9c39d-db4a-4132-af2e-86ab5c7b156c"
},
{
"product_id": "dd97a2a4-e48b-43c5-8717-7ac563c67e05",
"price_id": "4ecf9a61-a974-4594-bae2-bcb798f54d76"
},
{
"product_id": "aa1ebf85-f36e-46ff-978c-ed948c646f12",
"price_id": "4ecf9a61-a974-4594-bae2-bcb798f54d76"
}
]
}
],
"_id": "6d872912-ef8a-4815-b9db-01744c0828ac",
"_org": "739224"
}
]
}
}
}
}
}
},
"400": {
"description": "Invalid payload",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/conditional-pricing/{slug}/condition-sets": {
"get": {
"description": "Returns the condition sets built in for one conditional entity type, ready to copy into that schema's `conditions` array. Read-only, and the same for every organization.",
"operationId": "$getConditionSets",
"summary": "$getConditionSets",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type whose built-in condition sets to return",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
}
],
"responses": {
"200": {
"description": "The condition sets built in for this entity type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionSetCatalog"
}
}
}
},
"400": {
"description": "Invalid request, e.g. the slug names no conditional entity type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
}
},
"/v1/conditional-pricing:resolve": {
"post": {
"description": "Returns the variants of one conditional entity that apply, each composed: the base entity\noverlaid with the version in effect at `as_of`.\n\nSelect the variant either by `context`, matched against the conditions each variant pins, or\nby `variant_id`. Exactly one of the two. A condition a variant leaves unpinned matches any\nvalue; a condition absent from `context` matches only variants that leave it unpinned.\n\nWhen no variant matches, the entity's `default` variant is returned, or `results` is empty.\n`options.hydrate` replaces relation references with the entities they reference.\n\nSelection by `context` may lag a write by moments. For about ten seconds after a variant is\ncreated, a context it matches can still resolve to the entity's `default` variant, or to no\nresult, rather than to the new variant; a variant just deleted can still be selected for as\nlong. Selection by `variant_id`, and the versions a resolve composes, are not subject to this\nlag.\n",
"operationId": "$resolveConditionalEntity",
"summary": "$resolveConditionalEntity",
"tags": [
"Conditional Pricing API"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolveConditionalEntityRequest"
},
"examples": {
"Pin a variant at a recorded instant": {
"summary": "The numbers an order recorded",
"value": {
"schema": "price",
"entity_id": "price-sp26d1yo",
"variant_id": "var-46045",
"as_of": "2026-01-01T00:00:00Z"
}
},
"Pin a variant as it stands now": {
"summary": "What a contract is billed at today",
"value": {
"schema": "price",
"entity_id": "price-sp26d1yo",
"variant_id": "var-46045"
}
},
"Match a context, hydrating relations": {
"summary": "A composite price and its components in one round trip",
"value": {
"schema": "price",
"entity_id": "price-composite-9f2",
"context": {
"postal_code": "46045"
},
"options": {
"hydrate": true
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "The variants that apply, each composed with the version in effect. Empty when none\napplies and the entity has no `default` variant.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResolvedVariants"
},
"examples": {
"A hydrated composite price": {
"summary": "The component entities the variant's override names, fetched after composition",
"value": {
"results": [
{
"_id": "price-composite-9f2",
"_variant_id": "var-46045",
"_version_valid_from": "2027-01-01T00:00:00.000Z",
"_conditions": {
"postal_code": "46045",
"default": false
},
"_inert_overrides": [],
"_schema": "price",
"is_composite_price": true,
"price_components": [
{
"_id": "price-base-fee-46045",
"_schema": "price",
"unit_amount": 1290,
"unit_amount_currency": "EUR",
"$relation": {
"entity_id": "price-base-fee-46045",
"attribute": "price_components"
}
},
{
"_id": "price-kwh-46045",
"_schema": "price",
"unit_amount": 32,
"unit_amount_currency": "EUR",
"$relation": {
"entity_id": "price-kwh-46045",
"attribute": "price_components"
}
}
]
}
]
}
},
"A variant carrying overrides that did not apply": {
"summary": "`unit_amount_currency` reads as the entity's own value, and `_inert_overrides` says why each stored override was passed over",
"value": {
"results": [
{
"_id": "price-sp26d1yo",
"_variant_id": "var-46045",
"_version_valid_from": "2027-01-01T00:00:00.000Z",
"_conditions": {
"postal_code": "46045",
"default": false
},
"_inert_overrides": [
{
"attribute": "unit_amount_currency",
"reason": "ATTRIBUTE_NOT_OVERRIDABLE"
},
{
"attribute": "legacy_surcharge",
"reason": "ATTRIBUTE_UNDECLARED"
}
],
"_schema": "price",
"unit_amount": 2499,
"unit_amount_currency": "EUR"
}
]
}
}
}
}
}
},
"400": {
"description": "`CONDITION_UNDEFINED`, `OPERATOR_UNSUPPORTED`, `CONTEXT_FORMAT_INVALID`,\n`DEFAULT_MARKER_RESERVED`, `TOO_MANY_MATCHES`, `VALID_FROM_INVALID`,\n`ENTITY_TYPE_MISMATCH`. A body carrying both `context` and `variant_id`, or neither,\nfails validation and carries no `code`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, and on the pinned branch `VARIANT_NOT_FOUND` or\n`NO_ACTIVE_VERSION`. With `resolve_one`, `NO_MATCHES`; without it, no match is a `200`\ncarrying an empty `results`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`AMBIGUOUS_RESOLUTION`, `CONDITION_UNREADABLE`, `VARIANT_PIN_UNDECLARED`,\n`ENTITY_NOT_CONDITIONAL`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
}
},
"/v1/conditional-pricing/{slug}/entities/{entity_id}/variants": {
"post": {
"description": "Creates one variant together with its first version.\n\n`conditions` pins the situation the variant applies to, as exact values. A variant must pin\nat least one condition or be marked `default`, of which an entity may have one, and its\ncondition values are fixed once created.\n\nValues are stored only for attributes carrying `overridable_attribute`; the rest are\nreported in `warnings` rather than rejected. `variant_id` is server-generated.\n",
"operationId": "$createConditionalVariant",
"summary": "$createConditionalVariant",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type this variant belongs to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity to add a variant to",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateVariantRequest"
}
}
}
},
"responses": {
"201": {
"description": "The variant, as created, together with its first version",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatedVariant"
},
"examples": {
"A body naming attributes this variant may not override": {
"summary": "The write succeeded, and the attributes the warning names are absent from `values`",
"value": {
"variant_id": "var-46045",
"entity_id": "price-sp26d1yo",
"schema": "price",
"conditions": {
"postal_code": "46045",
"default": false
},
"valid_from": "2027-01-01T00:00:00.000Z",
"values": {
"unit_amount": 2499
},
"_created_at": "2026-12-01T09:15:00.000Z",
"_updated_at": "2026-12-01T09:15:00.000Z",
"_revision": 1,
"warnings": [
{
"code": "ATTRIBUTES_NOT_APPLIED",
"message": "The values sent for 2 attributes were not applied: unit_amount_currency, legacy_surcharge",
"details": {
"attributes": [
{
"attribute": "unit_amount_currency",
"reason": "ATTRIBUTE_NOT_OVERRIDABLE"
},
{
"attribute": "legacy_surcharge",
"reason": "ATTRIBUTE_UNDECLARED"
}
]
}
}
]
}
}
}
}
}
},
"400": {
"description": "`VARIANT_UNPINNED`, `CONDITION_UNDEFINED`, `CONDITION_VALUE_INVALID`,\n`PIN_FORMAT_INVALID`, `DEFAULT_MARKER_RESERVED`, `DEFAULT_VARIANT_PINS_CONDITIONS`,\n`VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `OVERRIDE_VALUE_INVALID`, `IDENTIFIER_INVALID`,\n`ENTITY_TYPE_MISMATCH`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`TUPLE_CONFLICT` (also how a second `default` variant is refused), `WRITE_CONFLICT`,\n`CONDITION_UNREADABLE`, `CONDITION_UNCONFIGURED`, `VARIANT_LIMIT_REACHED`,\n`ENTITY_NOT_CONDITIONAL`, `CONDITIONAL_PRICING_NOT_READY`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
}
},
"/v1/conditional-pricing/{slug}/entities/{entity_id}/variants:list": {
"post": {
"description": "Lists a conditional entity's variants and the conditions each one pins. A `POST` because the\ncondition filter is a structured object; nothing is written. The body is required, so send\n`{}` for the first page.\n\n`conditions` filters on the pins, taking the same predicates a resolve context does, and\nmatches a variant only where it pins that condition. `search` is free text over pinned\nvalues; `sort` orders by one pin.\n\nOffset paging up to the search index's window, then the `cursor` from `next`.\n",
"operationId": "$listConditionalVariants",
"summary": "$listConditionalVariants",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type the variants belong to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity whose variants to list",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListVariantsRequest"
},
"examples": {
"The first page": {
"summary": "The smallest valid body — the first ten variants, in `variant_id` order",
"value": {}
},
"Find the entity's fallback variant": {
"summary": "The variant served when nothing else applies",
"value": {
"conditions": {
"default": true
}
}
},
"Filter, search and sort together": {
"summary": "Variants pinning a consumption band in either segment, ordered by postal code",
"value": {
"conditions": {
"segment": {
"in": [
"private",
"commercial"
]
},
"consumption": {
"lt": 5000
}
},
"search": "460",
"sort": "conditions.postal_code:asc",
"size": 25
}
},
"Continue past the offset window": {
"summary": "What a caller sends instead of the `from` that was refused",
"value": {
"cursor": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0",
"sort": "conditions.postal_code:asc",
"size": 25
}
}
}
}
}
},
"responses": {
"200": {
"description": "The page of matching variants, and how many match in total",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VariantList"
},
"examples": {
"A page of a postal-code price": {
"summary": "Two of 8,128 matches, with the cursor that continues the listing",
"value": {
"hits": 8128,
"results": [
{
"variant_id": "var-46045",
"entity_id": "price-sp26d1yo",
"schema": "price",
"conditions": {
"postal_code": "46045",
"default": false
}
},
{
"variant_id": "var-50667",
"entity_id": "price-sp26d1yo",
"schema": "price",
"conditions": {
"postal_code": "50667",
"default": false
}
}
],
"next": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
}
}
}
}
}
},
"400": {
"description": "`CONDITION_UNDEFINED`, `OPERATOR_UNSUPPORTED`, `CONTEXT_FORMAT_INVALID`, `SORT_INVALID`,\n`OFFSET_WINDOW_EXCEEDED`, `CURSOR_INVALID`, `ENTITY_TYPE_MISMATCH`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`. An entity with no variants is a `200` carrying\nan empty `results` and `hits: 0`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`CONDITION_UNREADABLE`, raised only where the filter or `sort` names that condition, and\n`ENTITY_NOT_CONDITIONAL`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
}
},
"/v1/conditional-pricing/{slug}/entities/{entity_id}/variants:tree": {
"post": {
"description": "The variants list, each row carrying the version in effect at `as_of` and a `status` saying\nwhether that version is `active` or still `scheduled`.\n\nTakes everything the variants list takes, plus `as_of`. `size` is clamped at 100, and a\nvariant mid-delete is omitted from `results`.\n",
"operationId": "$getConditionalVariantTree",
"summary": "$getConditionalVariantTree",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type the variants belong to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity whose variants to list",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VariantTreeRequest"
},
"examples": {
"The screen as it opens": {
"summary": "The first page as of now, ordered by postal code",
"value": {
"sort": "conditions.postal_code:asc",
"size": 25
}
},
"The screen at a future date": {
"summary": "The table once next year's versions take effect",
"value": {
"as_of": "2027-03-15T00:00:00Z",
"conditions": {
"postal_code": {
"in": [
"46045",
"50667"
]
}
},
"size": 25
}
}
}
}
}
},
"responses": {
"200": {
"description": "The page of matching variants, each with the version its `status` names",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VariantTree"
},
"examples": {
"One live row and one staged row": {
"summary": "A variant whose version is in effect, beside one whose first version is still ahead of `as_of`",
"value": {
"hits": 8128,
"results": [
{
"variant_id": "var-46045",
"entity_id": "price-sp26d1yo",
"schema": "price",
"conditions": {
"postal_code": "46045",
"default": false
},
"status": "active",
"version": {
"variant_id": "var-46045",
"entity_id": "price-sp26d1yo",
"schema": "price",
"conditions": {
"postal_code": "46045",
"default": false
},
"valid_from": "2026-01-01T00:00:00.000Z",
"values": {
"unit_amount": 3261,
"unit_amount_decimal": "32.61"
},
"_created_at": "2025-11-14T09:12:44.101Z",
"_updated_at": "2025-11-14T09:12:44.101Z"
}
},
{
"variant_id": "var-50667",
"entity_id": "price-sp26d1yo",
"schema": "price",
"conditions": {
"postal_code": "50667",
"default": false
},
"status": "scheduled",
"version": {
"variant_id": "var-50667",
"entity_id": "price-sp26d1yo",
"schema": "price",
"conditions": {
"postal_code": "50667",
"default": false
},
"valid_from": "2027-01-01T00:00:00.000Z",
"values": {
"unit_amount": 3412,
"unit_amount_decimal": "34.12"
},
"_created_at": "2026-08-02T16:40:03.882Z",
"_updated_at": "2026-08-02T16:40:03.882Z"
}
}
],
"next": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
}
}
}
}
}
},
"400": {
"description": "`CONDITION_UNDEFINED`, `OPERATOR_UNSUPPORTED`, `CONTEXT_FORMAT_INVALID`, `SORT_INVALID`,\n`OFFSET_WINDOW_EXCEEDED`, `CURSOR_INVALID`, `VALID_FROM_INVALID`,\n`ENTITY_TYPE_MISMATCH`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`. An entity with no variants is a `200` carrying\nan empty `results` and `hits: 0`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`CONDITION_UNREADABLE`, raised only where the filter or `sort` names that condition, and\n`ENTITY_NOT_CONDITIONAL`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
}
},
"/v1/conditional-pricing/{slug}/entities/{entity_id}/variants/{variant_id}": {
"get": {
"description": "Returns the version of this variant in effect now — the latest `valid_from` at or before now\n— with the `_revision` a write to it must carry.\n\nThese are the version's own overrides; `:resolve` composes them onto the entity.\n",
"operationId": "$getActiveConditionalVariantVersion",
"summary": "$getActiveConditionalVariantVersion",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type this variant belongs to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity the variant belongs to",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
},
{
"in": "path",
"name": "variant_id",
"description": "The variant whose timeline this call addresses",
"schema": {
"type": "string"
},
"required": true,
"example": "var-46045"
}
],
"responses": {
"200": {
"description": "The version, as stored",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VariantVersion"
}
}
}
},
"400": {
"description": "`IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `NO_ACTIVE_VERSION`, `VERSION_NOT_FOUND`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`ENTITY_NOT_CONDITIONAL`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
},
"put": {
"description": "Replaces the values of the version in effect. The body is the complete set of overrides: an\noverridable attribute absent from it stops being overridden, and one the variant may not\noverride keeps its stored value.\n\n`valid_from` and `conditions` are accepted only unchanged.\n",
"operationId": "$replaceActiveConditionalVariantVersion",
"summary": "$replaceActiveConditionalVariantVersion",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type this variant belongs to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity the variant belongs to",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
},
{
"in": "path",
"name": "variant_id",
"description": "The variant whose timeline this call addresses",
"schema": {
"type": "string"
},
"required": true,
"example": "var-46045"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplaceVersionRequest"
}
}
}
},
"responses": {
"200": {
"description": "The version, as the write left it, together with anything the write moved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WrittenVariantVersion"
}
}
}
},
"400": {
"description": "`VALID_FROM_IMMUTABLE`, `VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `OVERRIDE_VALUE_INVALID`,\n`IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `NO_ACTIVE_VERSION`,\n`VERSION_NOT_FOUND`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`WRITE_CONFLICT`, `VARIANT_CONDITIONS_IMMUTABLE`, `ENTITY_NOT_CONDITIONAL`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
},
"patch": {
"description": "Changes only the fields it names on the version in effect. `null` sets a value rather than\nremoving an override; use the replace operation to remove one.\n",
"operationId": "$patchActiveConditionalVariantVersion",
"summary": "$patchActiveConditionalVariantVersion",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type this variant belongs to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity the variant belongs to",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
},
{
"in": "path",
"name": "variant_id",
"description": "The variant whose timeline this call addresses",
"schema": {
"type": "string"
},
"required": true,
"example": "var-46045"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchVersionRequest"
}
}
}
},
"responses": {
"200": {
"description": "The version, as the write left it, together with anything the write moved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WrittenVariantVersion"
}
}
}
},
"400": {
"description": "`VALID_FROM_IMMUTABLE`, `VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `OVERRIDE_VALUE_INVALID`,\n`IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `NO_ACTIVE_VERSION`,\n`VERSION_NOT_FOUND`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`WRITE_CONFLICT`, `VARIANT_CONDITIONS_IMMUTABLE`, `ENTITY_NOT_CONDITIONAL`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
},
"delete": {
"description": "Removes one variant: its condition tuple, its index entry and all its versions. The tuple\nbecomes reusable, and an interrupted delete is safe to send again.\n\nOrders and contracts pinning the variant stop resolving. To remove a single version, address\nit under `versions/{valid_from}`.\n",
"operationId": "$deleteConditionalVariant",
"summary": "$deleteConditionalVariant",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type this variant belongs to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity the variant belongs to",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
},
{
"in": "path",
"name": "variant_id",
"description": "The variant to remove",
"schema": {
"type": "string"
},
"required": true,
"example": "var-46045"
}
],
"responses": {
"200": {
"description": "What the delete removed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeletedVariant"
}
}
}
},
"400": {
"description": "`IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`WRITE_CONFLICT`, `ENTITY_NOT_CONDITIONAL`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
}
},
"/v1/conditional-pricing/{slug}/entities/{entity_id}/variants/{variant_id}/versions": {
"get": {
"description": "Lists one variant's versions. Cursor paging only: a page may be short or empty and still\ncarry a `next`, so page until `next` is absent. A cursor is bound to one variant and one\n`order`.\n",
"operationId": "$listConditionalVariantVersions",
"summary": "$listConditionalVariantVersions",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type this variant belongs to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity the variant belongs to",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
},
{
"in": "path",
"name": "variant_id",
"description": "The variant whose timeline to list",
"schema": {
"type": "string"
},
"required": true,
"example": "var-46045"
},
{
"in": "query",
"name": "limit",
"description": "Versions per page. Defaults to 100, which is also the maximum; a larger value is clamped.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 100
},
"required": false,
"example": 100
},
{
"in": "query",
"name": "order",
"description": "Which end of the timeline to read from. Baked into every cursor this read issues.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
},
"required": false,
"example": "asc"
},
{
"in": "query",
"name": "cursor",
"description": "Continue from a previous response's `next`. Opaque.",
"schema": {
"type": "string"
},
"required": false,
"example": "eyJzayI6IlYjcHJpY2Utc3AyNmQxeW8jdmFyLTQ2MDQ1IzIwMjYtMDEtMDFUMDA6MDA6MDAuMDAwWiIsIm9yZGVyIjoiYXNjIn0"
}
],
"responses": {
"200": {
"description": "A page of the variant's timeline, and the cursor that continues it",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VariantVersionList"
},
"examples": {
"A short page that is not the last one": {
"summary": "One version and a `next` — a short page does not mean the timeline has ended",
"value": {
"results": [
{
"variant_id": "var-46045",
"entity_id": "price-sp26d1yo",
"schema": "price",
"conditions": {
"postal_code": "46045",
"default": false
},
"valid_from": "2026-01-01T00:00:00.000Z",
"values": {
"unit_amount": 3261,
"unit_amount_decimal": "32.61"
},
"_created_at": "2025-11-14T09:12:44.101Z",
"_updated_at": "2025-11-14T09:12:44.101Z"
}
],
"next": "eyJzayI6IlYjcHJpY2Utc3AyNmQxeW8jdmFyLTQ2MDQ1IzIwMjYtMDEtMDFUMDA6MDA6MDAuMDAwWiIsIm9yZGVyIjoiYXNjIn0"
}
},
"The last page": {
"summary": "No `next`, which is the end of the timeline",
"value": {
"results": [
{
"variant_id": "var-46045",
"entity_id": "price-sp26d1yo",
"schema": "price",
"conditions": {
"postal_code": "46045",
"default": false
},
"valid_from": "2027-01-01T00:00:00.000Z",
"values": {
"unit_amount": 3412,
"unit_amount_decimal": "34.12"
},
"_created_at": "2026-08-02T16:40:03.882Z",
"_updated_at": "2026-08-02T16:40:03.882Z"
}
]
}
}
}
}
}
},
"400": {
"description": "`CURSOR_INVALID`, `ENTITY_TYPE_MISMATCH`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`ENTITY_NOT_CONDITIONAL`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
},
"post": {
"description": "Appends a version taking effect at its own instant. The version in effect at any instant is\nthe one with the latest `valid_from` at or before it; a future one is staged until its date.\n\nA past `valid_from` is accepted and reported in `warnings`. One the variant already has is\nrefused — replace or patch that version instead.\n",
"operationId": "$appendConditionalVariantVersion",
"summary": "$appendConditionalVariantVersion",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type this variant belongs to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity the variant belongs to",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
},
{
"in": "path",
"name": "variant_id",
"description": "The variant whose timeline this call addresses",
"schema": {
"type": "string"
},
"required": true,
"example": "var-46045"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AppendVersionRequest"
}
}
}
},
"responses": {
"201": {
"description": "The version, as appended, together with anything the write moved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WrittenVariantVersion"
}
}
}
},
"400": {
"description": "`VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `OVERRIDE_VALUE_INVALID`, `IDENTIFIER_INVALID`,\n`ENTITY_TYPE_MISMATCH`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`VERSION_CONFLICT`, `VARIANT_CONDITIONS_IMMUTABLE`, `ENTITY_NOT_CONDITIONAL`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
}
},
"/v1/conditional-pricing/{slug}/entities/{entity_id}/variants/{variant_id}/versions/{valid_from}": {
"get": {
"description": "Returns one version by the instant it takes effect. Exact, never nearest.",
"operationId": "$getConditionalVariantVersion",
"summary": "$getConditionalVariantVersion",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type this variant belongs to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity the variant belongs to",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
},
{
"in": "path",
"name": "variant_id",
"description": "The variant whose timeline this call addresses",
"schema": {
"type": "string"
},
"required": true,
"example": "var-46045"
},
{
"in": "path",
"name": "valid_from",
"description": "The version to address, by the instant it takes effect. An RFC 3339 date\n(`2026-01-01`, read as midnight UTC) or date-time, to at most millisecond precision,\ncanonicalized before it is matched.\n",
"schema": {
"type": "string"
},
"required": true,
"example": "2027-01-01T00:00:00.000Z"
}
],
"responses": {
"200": {
"description": "The version, as stored",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VariantVersion"
}
}
}
},
"400": {
"description": "`VALID_FROM_INVALID`, `IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `VERSION_NOT_FOUND`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`ENTITY_NOT_CONDITIONAL`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
},
"put": {
"description": "Replaces one version's values, whatever its date. Attributes the variant may not override\nkeep their stored value. Writing a superseded version is reported in `warnings`.\n",
"operationId": "$replaceConditionalVariantVersion",
"summary": "$replaceConditionalVariantVersion",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type this variant belongs to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity the variant belongs to",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
},
{
"in": "path",
"name": "variant_id",
"description": "The variant whose timeline this call addresses",
"schema": {
"type": "string"
},
"required": true,
"example": "var-46045"
},
{
"in": "path",
"name": "valid_from",
"description": "The version to address, by the instant it takes effect. An RFC 3339 date\n(`2026-01-01`, read as midnight UTC) or date-time, to at most millisecond precision,\ncanonicalized before it is matched.\n",
"schema": {
"type": "string"
},
"required": true,
"example": "2027-01-01T00:00:00.000Z"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReplaceVersionRequest"
}
}
}
},
"responses": {
"200": {
"description": "The version, as the write left it, together with anything the write moved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WrittenVariantVersion"
}
}
}
},
"400": {
"description": "`VALID_FROM_IMMUTABLE`, `VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `OVERRIDE_VALUE_INVALID`,\n`IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `VERSION_NOT_FOUND`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`WRITE_CONFLICT`, `VARIANT_CONDITIONS_IMMUTABLE`, `ENTITY_NOT_CONDITIONAL`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
},
"patch": {
"description": "Changes only the fields it names on one version.",
"operationId": "$patchConditionalVariantVersion",
"summary": "$patchConditionalVariantVersion",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type this variant belongs to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity the variant belongs to",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
},
{
"in": "path",
"name": "variant_id",
"description": "The variant whose timeline this call addresses",
"schema": {
"type": "string"
},
"required": true,
"example": "var-46045"
},
{
"in": "path",
"name": "valid_from",
"description": "The version to address, by the instant it takes effect. An RFC 3339 date\n(`2026-01-01`, read as midnight UTC) or date-time, to at most millisecond precision,\ncanonicalized before it is matched.\n",
"schema": {
"type": "string"
},
"required": true,
"example": "2027-01-01T00:00:00.000Z"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PatchVersionRequest"
}
}
}
},
"responses": {
"200": {
"description": "The version, as the write left it, together with anything the write moved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WrittenVariantVersion"
}
}
}
},
"400": {
"description": "`VALID_FROM_IMMUTABLE`, `VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `OVERRIDE_VALUE_INVALID`,\n`IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `VERSION_NOT_FOUND`.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`WRITE_CONFLICT`, `VARIANT_CONDITIONS_IMMUTABLE`, `ENTITY_NOT_CONDITIONAL`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
},
"delete": {
"description": "Removes one version. What the removal moves is reported in `warnings`. A variant's last\nremaining version cannot be removed — delete the variant instead.\n",
"operationId": "$deleteConditionalVariantVersion",
"summary": "$deleteConditionalVariantVersion",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type this variant belongs to",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
},
{
"in": "path",
"name": "entity_id",
"description": "The conditional entity the variant belongs to",
"schema": {
"type": "string"
},
"required": true,
"example": "price-sp26d1yo"
},
{
"in": "path",
"name": "variant_id",
"description": "The variant whose timeline this call addresses",
"schema": {
"type": "string"
},
"required": true,
"example": "var-46045"
},
{
"in": "path",
"name": "valid_from",
"description": "The version to address, by the instant it takes effect. An RFC 3339 date\n(`2026-01-01`, read as midnight UTC) or date-time, to at most millisecond precision,\ncanonicalized before it is matched.\n",
"schema": {
"type": "string"
},
"required": true,
"example": "2027-01-01T00:00:00.000Z"
},
{
"in": "query",
"name": "_revision",
"description": "The revision read from the version being deleted. The delete is refused if the version\nhas been written since.\n",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true,
"example": 3
}
],
"responses": {
"200": {
"description": "The version removed, together with anything the delete moved",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeletedVariantVersion"
}
}
}
},
"400": {
"description": "`VALID_FROM_INVALID`, `IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `VERSION_NOT_FOUND`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`LAST_VERSION_UNDELETABLE`, `WRITE_CONFLICT`, `ENTITY_NOT_CONDITIONAL`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
}
},
"/v1/conditional-pricing/{slug}/variants:batchUpsert": {
"post": {
"description": "Writes up to 100 variants or versions in one call. Each item names its own entity, so one\ncall can span a tariff hierarchy, and addresses a variant by condition tuple rather than by\nid — the id it created or found is on the result entry.\n\nEach item's outcome is derived from what is stored: an unknown tuple is `variant_created`, a\nknown tuple with no version at the item's `valid_from` is `version_created`, an existing\nversion there is `updated`, and a write matching what is stored is `skipped`. An item\nwithout `valid_from` is a last-write-wins write with no `skipped` detection.\n\nItems addressing the same `(entity_id, conditions)` apply in array order; the rest run in\nparallel. No cross-item rollback, and no `_revision` guard.\n",
"operationId": "$batchUpsertConditionalVariants",
"summary": "$batchUpsertConditionalVariants",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type every item in this call writes under",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchUpsertVariantsRequest"
},
"examples": {
"A monthly refresh cycle": {
"summary": "Five items across two entities — a new postal code, a scheduled adjustment, a correction, an unchanged row and one bad source row",
"value": {
"correlation_id": "tariff-refresh-2027-01",
"items": [
{
"entity_id": "price-sp26d1yo",
"conditions": {
"postal_code": "46045"
},
"valid_from": "2027-01-01T00:00:00Z",
"values": {
"unit_amount": 3261,
"unit_amount_decimal": "32.61"
}
},
{
"entity_id": "price-sp26d1yo",
"conditions": {
"postal_code": "50667"
},
"valid_from": "2027-01-01T00:00:00Z",
"values": {
"unit_amount": 3412,
"unit_amount_decimal": "34.12"
}
},
{
"entity_id": "price-base-fee",
"conditions": {
"postal_code": "50667"
},
"valid_from": "2027-01-01T00:00:00Z",
"values": {
"unit_amount": 1290,
"unit_amount_decimal": "12.90"
}
},
{
"entity_id": "price-sp26d1yo",
"conditions": {
"postal_code": "80331"
},
"valid_from": "2027-01-01T00:00:00Z",
"values": {
"unit_amount": 3120,
"unit_amount_decimal": "31.20",
"description": "Grundpreis 2027"
}
},
{
"entity_id": "price-sp26d1yo",
"conditions": {
"postal_code": "10115",
"segment": "industrial"
},
"valid_from": "2027-01-01T00:00:00Z",
"values": {
"unit_amount": 2980,
"unit_amount_decimal": "29.80"
}
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "What every item did, in request order, and a count per outcome. Always `200`, whatever\nthe per-item outcomes.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchUpsertResult"
},
"examples": {
"Every outcome once": {
"summary": "The five items above, in order",
"value": {
"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": "This entity holds 4998 of the 5000 variants it may hold",
"details": {
"variant_count": 4998,
"cap": 5000
}
}
]
},
{
"outcome": "version_created",
"entity_id": "price-sp26d1yo",
"variant_id": "var-50667",
"valid_from": "2027-01-01T00:00:00.000Z",
"warnings": []
},
{
"outcome": "updated",
"entity_id": "price-base-fee",
"variant_id": "var-bf-50667",
"valid_from": "2027-01-01T00:00:00.000Z",
"warnings": []
},
{
"outcome": "skipped",
"entity_id": "price-sp26d1yo",
"variant_id": "var-80331",
"valid_from": "2027-01-01T00:00:00.000Z",
"warnings": [
{
"code": "ATTRIBUTES_NOT_APPLIED",
"message": "The value sent for description was not applied",
"details": {
"attributes": [
{
"attribute": "description",
"reason": "ATTRIBUTE_NOT_OVERRIDABLE"
}
]
}
}
]
},
{
"outcome": "error",
"entity_id": "price-sp26d1yo",
"warnings": [],
"error": {
"message": "The value pinned for condition segment is not one of its declared options",
"code": "CONDITION_VALUE_INVALID",
"details": {
"condition_name": "segment",
"value": "industrial",
"options": [
"private",
"commercial"
]
}
}
}
]
}
}
}
}
}
},
"400": {
"description": "The envelope cannot be processed: more than 100 items, an empty `items`, a slug that\nnames no conditional entity type, or a body this schema rejects. No `code` is carried —\nan individual item's failure is on its own result entry.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`SCHEMA_NOT_FOUND`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"409": {
"description": "`CONDITIONAL_PRICING_NOT_READY`: the organization's setup has not finished, so no item is\nwritten. An individual item's failure is on its own result entry.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
}
},
"/v1/conditional-pricing/{slug}/variants:batchDelete": {
"post": {
"description": "Removes up to 100 variants or versions in one call. An item carrying `valid_from` removes\nthat version; one without it removes the whole variant.\n\nEach item addresses its variant by `variant_id` beside its `entity_id`, or by the condition\ntuple it pins, never both. Use ids once a condition has left the schema, since its tuple can\nno longer be canonicalized.\n\nItems addressing the same variant apply in array order, resolved to ids first; the rest run\nin parallel. An item addressing a missing variant or version is `skipped`, and the call is\nsafe to send again.\n",
"operationId": "$batchDeleteConditionalVariants",
"summary": "$batchDeleteConditionalVariants",
"tags": [
"Conditional Pricing API"
],
"parameters": [
{
"in": "path",
"name": "slug",
"description": "The conditional entity type every item in this call removes from",
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"required": true,
"example": "price"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchDeleteVariantsRequest"
},
"examples": {
"A cleanup pass, addressed both ways": {
"summary": "A version withdrawn by the tuple that pins it, a whole variant removed by id, and a version delete that would leave its variant with none",
"value": {
"correlation_id": "postal-code-cleanup-2026-09",
"items": [
{
"entity_id": "price-sp26d1yo",
"conditions": {
"postal_code": "46045"
},
"valid_from": "2026-01-01T00:00:00Z"
},
{
"entity_id": "price-sp26d1yo",
"conditions": {
"postal_code": "99998"
}
},
{
"entity_id": "price-sp26d1yo",
"variant_id": "var-80331",
"valid_from": "2026-01-01T00:00:00Z"
}
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "What every item did, in request order, and a count per outcome. Always `200`, whatever\nthe per-item outcomes.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BatchDeleteResult"
},
"examples": {
"Every outcome once": {
"summary": "The three items above, in order — the second addressed a tuple no variant pins",
"value": {
"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": "2026-01-01T00:00:00.000Z",
"warnings": [
{
"code": "ACTIVE_VERSION_CHANGED",
"message": "The version in effect was removed, so what resolves now has changed",
"details": {
"valid_from": "2026-01-01T00:00:00.000Z",
"active_valid_from": "2026-01-01T00:00:00.000Z"
}
}
]
},
{
"outcome": "skipped",
"entity_id": "price-sp26d1yo",
"warnings": []
},
{
"outcome": "error",
"entity_id": "price-sp26d1yo",
"variant_id": "var-80331",
"valid_from": "2026-01-01T00:00:00.000Z",
"warnings": [],
"error": {
"message": "var-80331 has only this version, so removing it would leave the variant unresolvable",
"code": "LAST_VERSION_UNDELETABLE",
"details": {
"variant_id": "var-80331",
"valid_from": "2026-01-01T00:00:00.000Z"
}
}
}
]
}
}
}
}
}
},
"400": {
"description": "The envelope cannot be processed: more than 100 items, an empty `items`, a slug that\nnames no conditional entity type, an item naming both a `variant_id` and a condition\ntuple, or a body this schema rejects. No `code` is carried — an individual item's\nfailure is on its own result entry.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"403": {
"description": "`CONDITIONAL_PRICING_NOT_ENABLED`: the organization has not opted in to Conditional\nPricing. Without a `code`: the token names no organization this API can act for.\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
},
"404": {
"description": "`SCHEMA_NOT_FOUND`.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConditionalPricingError"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"EpilotAuth": {
"type": "http",
"scheme": "bearer",
"description": "Epilot Bearer Token"
},
"EpilotPublicAuth": {
"type": "http",
"scheme": "bearer",
"description": "Epilot Public Access Bearer Token",
"bearerFormat": "JWT"
}
},
"schemas": {
"IntegrationId": {
"type": "string",
"enum": [
"getag",
"external-catalog"
]
},
"ConditionalEntitySlug": {
"type": "string",
"description": "Schema slug of an entity type that can be conditional — the `{slug}` of every conditional-pricing route.",
"enum": [
"product",
"price",
"coupon"
]
},
"ConditionType": {
"type": "string",
"description": "The kind of value a condition holds, which decides how a pinned value is matched against a\nresolve context.\n\n- `string`: an arbitrary string, matched exactly and case-sensitively\n- `number`: a numeric value\n- `date`: a single date\n- `daterange`: a window with a from and an until timestamp; either end may be left open\n- `boolean`: a true/false value\n- `select`: one of the values declared in `options`, which is always a closed vocabulary\n- `location`: a geographic value, shaped by `format`\n",
"enum": [
"string",
"number",
"date",
"daterange",
"boolean",
"select",
"location"
]
},
"ConditionDefinition": {
"type": "object",
"description": "One condition dimension, in the shape a schema's `conditions` array holds it — copy it in verbatim.",
"required": [
"id",
"name",
"label",
"type"
],
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "Stable identity of the condition, supplied on creation and round-tripped unchanged. A\ncatalog condition keeps the id the catalog gives it.\n",
"example": "d5839b94-ba20-4225-a78e-76951d352bd6"
},
"name": {
"type": "string",
"description": "How variants and resolve contexts refer to this condition, independent of attribute\nnames. `default` and names beginning with `_` are reserved and are ignored here.\n",
"example": "postal_code"
},
"label": {
"type": "string",
"description": "Human-readable name of the condition.",
"example": "Postal Code"
},
"type": {
"$ref": "#/components/schemas/ConditionType"
},
"options": {
"type": "array",
"description": "The vocabulary of a `select` condition, absent for every other type. Each entry is the\nvalue itself or an object carrying that value and a display `title`, which is never\nmatched.\n\nAlways closed: a pinned value outside it is `CONDITION_VALUE_INVALID`, and while\n`options` is absent or empty the condition admits no pin at all. Not enforced on\nresolve, where a context value outside the vocabulary matches nothing.\n",
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"required": [
"value"
],
"properties": {
"value": {
"type": "string"
},
"title": {
"type": "string"
}
}
}
]
},
"example": [
"private",
{
"value": "commercial",
"title": "Commercial customers"
}
]
},
"format": {
"type": "string",
"description": "The value shape of a `location` condition. Absent for every other type.",
"enum": [
"postal_code",
"postal_code_city"
]
}
}
},
"ConditionSet": {
"type": "object",
"description": "A named bundle of condition definitions, built in for one entity type.",
"required": [
"id",
"label",
"description",
"conditions"
],
"properties": {
"id": {
"type": "string",
"description": "Identifies the set within this entity type's catalog.",
"example": "delivery_area"
},
"label": {
"type": "string",
"description": "Human-readable name of the set.",
"example": "Delivery Area"
},
"description": {
"type": "string",
"description": "What the set is for, and when to reach for it."
},
"conditions": {
"type": "array",
"description": "The condition definitions to copy into the schema's own `conditions` array.",
"items": {
"$ref": "#/components/schemas/ConditionDefinition"
}
}
}
},
"ConditionSetCatalog": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "The condition sets built in for the requested entity type, in the order they are offered.",
"items": {
"$ref": "#/components/schemas/ConditionSet"
}
}
}
},
"ConditionalPricingOptIn": {
"type": "object",
"additionalProperties": false,
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "- `PROVISIONING`: the organization's search collection is still being set up, and\n creating a variant is refused with `CONDITIONAL_PRICING_NOT_READY`.\n- `ACTIVE`: setup has finished.\n",
"enum": [
"PROVISIONING",
"ACTIVE"
]
}
}
},
"ConditionalPricingErrorCode": {
"type": "string",
"description": "Machine-readable failure mode of a conditional-pricing operation, so a client can branch on\nthe kind of failure instead of parsing the message. A `400` is about the request; a `409` is\nabout what is already stored. Refusals raised by request validation carry no `code` at all.\n\n- `SCHEMA_NOT_FOUND` (404): no conditional entity type by that slug\n- `ENTITY_NOT_FOUND` (404): the schema holds no entity with that id\n- `ENTITY_TYPE_MISMATCH` (400): that id belongs to an entity of another type than the slug named\n- `ENTITY_NOT_CONDITIONAL` (409): the entity is of the right type but was not created as a conditional one\n- `VARIANT_NOT_FOUND` (404): the entity has no such variant\n- `VERSION_NOT_FOUND` (404): the variant has no version at that `valid_from`\n- `NO_MATCHES` (404): nothing applied to the context and the entity has no `default` variant\n- `NO_ACTIVE_VERSION` (404): the variant has no version in effect at the instant asked about\n- `AMBIGUOUS_RESOLUTION` (409): several variants match the given context while a single result was requested\n- `TUPLE_CONFLICT` (409): the condition tuple is already claimed by another variant\n- `VERSION_CONFLICT` (409): a version already exists at the given `valid_from` on that variant\n- `CONDITION_UNDEFINED` (400): the request names a condition the entity's schema does not define\n- `VARIANT_PIN_UNDECLARED` (409): a variant a resolve would compose pins a condition the entity's schema no longer declares\n- `OPERATOR_UNSUPPORTED` (400): the requested predicate, or a sort, is not applicable to the condition's type\n- `CONTEXT_FORMAT_INVALID` (400): a resolve context or listing filter value is malformed for its condition type\n- `CONDITION_VALUE_INVALID` (400): a variant write pins a `select` value absent from the condition's declared `options`\n- `CONDITION_UNCONFIGURED` (409): a variant write pins a `select` condition whose `options` are absent or empty\n- `TOO_MANY_MATCHES` (400): a multi-match resolve exceeded its result cap\n- `WRITE_CONFLICT` (409): transient write contention, retryable unlike `TUPLE_CONFLICT`\n- `OFFSET_WINDOW_EXCEEDED` (400): a listing's `from` plus `size` reaches past the offset window the search index allows\n- `CURSOR_INVALID` (400): a paging cursor cannot be read, or does not belong to the read it was sent with\n- `VARIANT_LIMIT_REACHED` (409): the entity already holds every variant it may hold\n- `PIN_FORMAT_INVALID` (400): a variant pins a value malformed for its condition's type\n- `VARIANT_UNPINNED` (400): a variant write pins no condition and is not marked `default`, or a batch delete item addresses no variant\n- `LAST_VERSION_UNDELETABLE` (409): the delete would leave the variant with no version at all\n- `CONDITION_UNREADABLE` (409): the entity's schema declares a condition in a way this deploy cannot read\n- `SORT_INVALID` (400): a listing's `sort` is not `conditions.:asc` or `conditions.:desc`\n- `DEFAULT_MARKER_RESERVED` (400): a variant write's pins, or a resolve context, address the fallback marker — `default` or `_default`\n- `DEFAULT_VARIANT_PINS_CONDITIONS` (400): a variant marked `default` also pins real conditions\n- `VALID_FROM_IMMUTABLE` (400): a version write asks for a different `valid_from` than the version its own address names\n- `VARIANT_CONDITIONS_IMMUTABLE` (409): a version write carries a condition tuple other than the one its variant was created with\n- `IDENTIFIER_INVALID` (400): an id in the request cannot be used as a storage key — empty, carrying an unsupported character, or longer than 128 characters\n- `VALID_FROM_INVALID` (400): a `valid_from` is not one of the timestamp forms a version timeline can be sorted by\n- `VALUE_UNSTORABLE` (400): a write carries a value the store cannot hold, such as a non-finite number or one outside the table's numeric range\n- `OVERRIDE_VALUE_INVALID` (400): a write overrides a `currency` or `number` field, or an amount/decimal pair, with a value of the wrong type\n- `CONDITIONAL_PRICING_NOT_ENABLED` (403): the organization has not opted in to Conditional Pricing\n- `CONDITIONAL_PRICING_NOT_READY` (409): the organization opted in minutes ago and a variant cannot be created until its setup finishes\n",
"enum": [
"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",
"VARIANT_PIN_UNDECLARED",
"OPERATOR_UNSUPPORTED",
"CONTEXT_FORMAT_INVALID",
"CONDITION_VALUE_INVALID",
"CONDITION_UNCONFIGURED",
"TOO_MANY_MATCHES",
"WRITE_CONFLICT",
"OFFSET_WINDOW_EXCEEDED",
"CURSOR_INVALID",
"VARIANT_LIMIT_REACHED",
"PIN_FORMAT_INVALID",
"VARIANT_UNPINNED",
"LAST_VERSION_UNDELETABLE",
"CONDITION_UNREADABLE",
"SORT_INVALID",
"DEFAULT_MARKER_RESERVED",
"DEFAULT_VARIANT_PINS_CONDITIONS",
"VALID_FROM_IMMUTABLE",
"VARIANT_CONDITIONS_IMMUTABLE",
"IDENTIFIER_INVALID",
"VALID_FROM_INVALID",
"VALUE_UNSTORABLE",
"OVERRIDE_VALUE_INVALID",
"CONDITIONAL_PRICING_NOT_ENABLED",
"CONDITIONAL_PRICING_NOT_READY"
]
},
"ResolveConditionalEntityRequest": {
"description": "A resolve names one conditional entity and selects its variants either by `context` or by\n`variant_id`, never both. `context: {}` matches nothing and so returns the `default`\nvariant, which is how to ask for it without knowing its id.\n",
"oneOf": [
{
"$ref": "#/components/schemas/ResolveByContextRequest"
},
{
"$ref": "#/components/schemas/ResolveByPinRequest"
}
]
},
"ResolveByContextRequest": {
"type": "object",
"additionalProperties": false,
"description": "Resolve by matching a situation: which of this entity's variants apply to `context`, each\ncomposed with the version in effect at `as_of`.\n",
"required": [
"schema",
"entity_id",
"context"
],
"properties": {
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"entity_id": {
"type": "string",
"description": "The conditional entity to resolve. Resolution is always scoped to exactly one.",
"example": "price-sp26d1yo"
},
"context": {
"$ref": "#/components/schemas/ResolveContext"
},
"as_of": {
"type": "string",
"description": "The instant the version is selected at — the version with the latest `valid_from` at or\nbefore it. Defaults to now. A variant whose first version is later is excluded from\nmatching; a pin naming one is answered `NO_ACTIVE_VERSION` instead.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time, to at most\nmillisecond precision.\n",
"example": "2027-03-15T00:00:00Z"
},
"options": {
"$ref": "#/components/schemas/ResolveOptions"
}
}
},
"ResolveByPinRequest": {
"type": "object",
"additionalProperties": false,
"description": "Resolve by naming a variant: compose this one, whatever a context would have matched.",
"required": [
"schema",
"entity_id",
"variant_id"
],
"properties": {
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"entity_id": {
"type": "string",
"description": "The conditional entity to resolve. Resolution is always scoped to exactly one.",
"example": "price-sp26d1yo"
},
"variant_id": {
"type": "string",
"description": "The variant to compose. Condition matching is skipped, the `default` fallback does not\napply, and `results` carries exactly one entry. A variant of another entity is\n`VARIANT_NOT_FOUND`.\n",
"example": "var-46045"
},
"as_of": {
"type": "string",
"description": "The instant the version is selected at — the version with the latest `valid_from` at or\nbefore it. Defaults to now. A pinned variant whose first version is later is\n`NO_ACTIVE_VERSION`, carrying the instant in `details.as_of`.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time, to at most\nmillisecond precision.\n",
"example": "2027-03-15T00:00:00Z"
},
"options": {
"$ref": "#/components/schemas/PinnedResolveOptions"
}
}
},
"ResolveContext": {
"type": "object",
"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",
"consumption": {
"lt": 5000
}
}
},
"ResolveOptions": {
"type": "object",
"additionalProperties": false,
"description": "The options a context resolve accepts. A pin takes `PinnedResolveOptions` instead.",
"properties": {
"resolve_one": {
"type": "boolean",
"default": false,
"description": "Ask for an unambiguous answer: several applicable variants become\n`AMBIGUOUS_RESOLUTION`, and none becomes `NO_MATCHES`.\n"
},
"hydrate": {
"type": "boolean",
"default": false,
"description": "Return the entities a relation attribute references in place of the references, one\nlevel deep, as an entity read with hydration does. Applied after composition, so a\nrelation this variant's version replaced is hydrated too.\n\nA referenced entity that is itself conditional is returned unresolved, carrying its own\nflag. Costs one fetch per distinct referenced entity, with no per-attribute limit.\n"
}
}
},
"PinnedResolveOptions": {
"type": "object",
"additionalProperties": false,
"description": "The options a pinned resolve accepts — `hydrate` and nothing else. `resolve_one` has nothing\nto change where the answer is one result or a 404, so a body sending it is a `400`.\n",
"properties": {
"hydrate": {
"type": "boolean",
"default": false,
"description": "Return the entities a relation attribute references in place of the references, one\nlevel deep, as an entity read with hydration does. Applied after composition, so a\nrelation this variant's version replaced is hydrated too.\n\nA referenced entity that is itself conditional is returned unresolved, carrying its own\nflag. Costs one fetch per distinct referenced entity, with no per-attribute limit.\n"
}
}
},
"ResolvedVariants": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "One composed payload per applicable variant, capped at 100 — a context selecting more is\n`TOO_MANY_MATCHES`. Unordered.\n",
"items": {
"$ref": "#/components/schemas/ResolvedVariant"
}
}
}
},
"ResolvedVariant": {
"type": "object",
"additionalProperties": true,
"description": "The entity as this variant leaves it — every attribute of a plain entity read with the\napplicable version's overrides applied — plus the discriminators below.\n",
"required": [
"_id",
"_variant_id",
"_version_valid_from",
"_conditions",
"_inert_overrides"
],
"properties": {
"_id": {
"type": "string",
"description": "The logical entity's id, the same one a plain entity read returns.",
"example": "price-sp26d1yo"
},
"_variant_id": {
"type": "string",
"description": "The variant these values came from — what an order or contract pins.",
"example": "var-46045"
},
"_version_valid_from": {
"type": "string",
"description": "The `valid_from` of the version applied for the requested `as_of`.",
"example": "2027-01-01T00:00:00.000Z"
},
"_conditions": {
"allOf": [
{
"$ref": "#/components/schemas/VariantConditions"
}
],
"description": "The conditions this variant pins, plus the boolean `default` discriminator."
},
"_inert_overrides": {
"type": "array",
"description": "The variant's stored overrides this payload did not apply, and why. Always present, and\nempty in the ordinary case. Computed per read against the schema as it stands, so\ngranting or withdrawing `overridable_attribute` changes it without any data being\nrewritten.\n",
"items": {
"$ref": "#/components/schemas/InertOverride"
}
}
}
},
"CreateVariantRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"values"
],
"properties": {
"conditions": {
"$ref": "#/components/schemas/PinnedConditions"
},
"default": {
"type": "boolean",
"default": false,
"description": "Mark this variant as the entity's fallback, served when no other variant applies. It can\npin nothing else, and an entity may have one; a second is `TUPLE_CONFLICT`. Available to\nevery conditional entity without anything being declared in the schema.\n"
},
"valid_from": {
"type": "string",
"description": "When the first version takes effect. Defaults to now. An RFC 3339 date (`2026-01-01`,\nread as midnight UTC) or date-time, to at most millisecond precision.\n",
"example": "2027-01-01T00:00:00Z"
},
"values": {
"$ref": "#/components/schemas/VariantValues"
}
}
},
"VariantConditions": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/PinnedConditionValue"
},
"required": [
"default"
],
"description": "A variant's pinned conditions as a reader sees them: the pins the schema declares, plus a\nboolean `default` saying whether this is the entity's fallback.\n",
"properties": {
"default": {
"type": "boolean"
}
},
"example": {
"postal_code": "46045",
"default": false
}
},
"PinnedConditions": {
"type": "object",
"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"
}
},
"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": 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"
}
}
},
"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": [
"postal_code",
"city"
],
"properties": {
"postal_code": {
"type": "string",
"example": "50667"
},
"city": {
"type": "string",
"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"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"$ref": "#/components/schemas/PostalCodeCity"
},
{
"$ref": "#/components/schemas/ConditionPredicate"
}
]
},
"ConditionPredicate": {
"description": "A single-operator predicate.",
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"lt"
],
"properties": {
"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",
"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": {
"type": "number",
"description": "Variants this entity may hold. Configurable per deploy."
}
}
}
}
},
{
"type": "object",
"additionalProperties": false,
"description": "What resolves now changed, other than by a newer version taking effect: the version in\neffect was written behind, or removed.\n",
"required": [
"code",
"message",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"ACTIVE_VERSION_CHANGED"
]
},
"message": {
"type": "string"
},
"details": {
"$ref": "#/components/schemas/VersionMoved"
}
}
},
{
"type": "object",
"additionalProperties": false,
"description": "What a past-dated (`as_of`) read returns changed: the write landed on, or created, a\nversion dated in the past.\n",
"required": [
"code",
"message",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"SUPERSEDED_VERSION_WRITTEN"
]
},
"message": {
"type": "string"
},
"details": {
"$ref": "#/components/schemas/VersionMoved"
}
}
},
{
"type": "object",
"additionalProperties": false,
"description": "Attributes named in the request body that the write did not store, one entry each with\nits own reason. The write itself succeeded.\n",
"required": [
"code",
"message",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"ATTRIBUTES_NOT_APPLIED"
]
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"attributes"
],
"properties": {
"attributes": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "#/components/schemas/InertOverride"
}
}
}
}
}
},
{
"type": "object",
"additionalProperties": false,
"description": "The variant was stored but its index entry was not written. `:resolve`, `variants:list` and\n`variants:tree` miss it until it is repaired, within about a minute and a half; until then a\nresolve it would match returns the entity's default variant. Retrying the write does not help.\n",
"required": [
"code",
"message",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"VARIANT_NOT_INDEXED"
]
},
"message": {
"type": "string"
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"reason"
],
"properties": {
"reason": {
"type": "string",
"description": "- `INDEX_WRITE_FAILED`: the index write was attempted and did not succeed.\n",
"enum": [
"INDEX_WRITE_FAILED"
]
}
}
}
}
}
]
},
"VersionMoved": {
"type": "object",
"additionalProperties": false,
"description": "Which version a write moved, and which one was in effect while it did.",
"required": [
"valid_from"
],
"properties": {
"valid_from": {
"type": "string",
"description": "The version this write created, changed or removed.",
"example": "2026-08-01T00:00:00.000Z"
},
"active_valid_from": {
"type": "string",
"description": "The version in effect when the write landed, before it did. Absent when the variant had\nnone. Advisory, and may lag the timeline by milliseconds.\n",
"example": "2026-01-01T00:00:00.000Z"
}
}
},
"InertOverride": {
"type": "object",
"additionalProperties": false,
"description": "One override that did not apply, and why — reported by a write for the attributes in its\nbody, and by a resolved payload for the stored overrides composition passed over.\n",
"required": [
"attribute",
"reason"
],
"properties": {
"attribute": {
"type": "string",
"description": "The attribute's name, as the request body or the stored version spells it.",
"example": "unit_amount"
},
"reason": {
"$ref": "#/components/schemas/InertOverrideReason"
}
}
},
"InertOverrideReason": {
"type": "string",
"description": "Why one override did not apply.\n\n- `ATTRIBUTE_NOT_OVERRIDABLE`: the schema declares the attribute without\n `overridable_attribute`, which is an ordinary schema edit away\n- `ATTRIBUTE_READONLY`: the attribute is readonly, and cannot be granted the flag\n- `ATTRIBUTE_HIDDEN`: the attribute is hidden, and cannot be granted the flag\n- `ATTRIBUTE_COMPUTED`: the attribute's value is derived rather than stored\n- `ATTRIBUTE_UNDECLARED`: the schema declares no attribute of that name\n- `TYPE_NOT_OVERRIDABLE`: the attribute's type is not one a variant may override\n- `CAPABILITY_NOT_OVERRIDABLE`: the field is managed by a capability that does not declare\n `overridable_attribute`\n",
"enum": [
"ATTRIBUTE_NOT_OVERRIDABLE",
"ATTRIBUTE_READONLY",
"ATTRIBUTE_HIDDEN",
"ATTRIBUTE_COMPUTED",
"ATTRIBUTE_UNDECLARED",
"TYPE_NOT_OVERRIDABLE",
"CAPABILITY_NOT_OVERRIDABLE"
]
},
"DeletedVariant": {
"type": "object",
"required": [
"variant_id",
"entity_id",
"schema",
"tuple_released",
"versions_deleted"
],
"properties": {
"variant_id": {
"type": "string",
"example": "var-46045"
},
"entity_id": {
"type": "string",
"example": "price-sp26d1yo"
},
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"tuple_released": {
"type": "boolean",
"description": "Whether this call freed the variant's combination of condition values. `false` where an\nearlier, interrupted attempt had already freed it.\n"
},
"versions_deleted": {
"type": "number",
"description": "Version rows this call removed."
}
}
},
"VariantVersion": {
"type": "object",
"description": "One version of one variant: the overrides it carries, the instant it takes effect, and the\nvariant it belongs to. These are the version's own overrides; `:resolve` composes them onto\nthe entity.\n",
"required": [
"variant_id",
"entity_id",
"schema",
"conditions",
"valid_from",
"values",
"_created_at",
"_updated_at",
"_revision"
],
"properties": {
"variant_id": {
"type": "string",
"example": "var-46045"
},
"entity_id": {
"type": "string",
"example": "price-sp26d1yo"
},
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"conditions": {
"allOf": [
{
"$ref": "#/components/schemas/VariantConditions"
}
],
"description": "The situation the variant applies to, plus the boolean `default` discriminator. A\nproperty of the variant: every version carries the same one.\n"
},
"valid_from": {
"type": "string",
"description": "When this version takes effect, canonicalized to millisecond-precision UTC. Its identity\nwithin the variant.\n",
"example": "2027-01-01T00:00:00.000Z"
},
"values": {
"$ref": "#/components/schemas/VariantValues"
},
"_created_at": {
"type": "string",
"description": "When this version was created.",
"readOnly": true
},
"_updated_at": {
"type": "string",
"description": "When this version was last written.",
"readOnly": true
},
"_revision": {
"type": "integer",
"description": "The revision a write to this version must carry. Read from a strongly consistent read.",
"readOnly": true,
"example": 3
}
}
},
"WrittenVariantVersion": {
"description": "A version as a write left it, together with anything the write moved.",
"allOf": [
{
"$ref": "#/components/schemas/VariantVersion"
},
{
"type": "object",
"required": [
"warnings"
],
"properties": {
"warnings": {
"type": "array",
"description": "What this write moved, and anything in the body it did not store. Always present,\nand empty in the ordinary case.\n",
"items": {
"$ref": "#/components/schemas/WriteWarning"
}
}
}
}
]
},
"DeletedVariantVersion": {
"type": "object",
"required": [
"variant_id",
"entity_id",
"schema",
"valid_from",
"warnings"
],
"properties": {
"variant_id": {
"type": "string",
"example": "var-46045"
},
"entity_id": {
"type": "string",
"example": "price-sp26d1yo"
},
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"valid_from": {
"type": "string",
"description": "The version removed, canonicalized to millisecond-precision UTC.",
"example": "2027-01-01T00:00:00.000Z"
},
"warnings": {
"type": "array",
"description": "What the delete moved. Always present, and empty when a scheduled version was withdrawn.",
"items": {
"$ref": "#/components/schemas/WriteWarning"
}
}
}
},
"AppendVersionRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"values"
],
"properties": {
"valid_from": {
"type": "string",
"description": "When this version takes effect. Omit it to mean now; a timestamp read from the caller's\nown clock is already a backdate by the time the server judges it, and earns a warning.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time, to at most\nmillisecond precision. A date in the past is accepted; one the variant already has a\nversion at is `VERSION_CONFLICT`.\n",
"example": "2027-01-01T00:00:00Z"
},
"values": {
"allOf": [
{
"$ref": "#/components/schemas/VariantValues"
}
],
"description": "The overrides this version carries. Attributes the variant may not override are seeded\nfrom the version in effect at this version's own `valid_from`.\n"
},
"conditions": {
"allOf": [
{
"$ref": "#/components/schemas/PinnedConditions"
}
],
"description": "Accepted only unchanged, so a client can send back the body it loaded. A variant's\nconditions are fixed when it is created.\n"
}
}
},
"ReplaceVersionRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"values",
"_revision"
],
"properties": {
"values": {
"allOf": [
{
"$ref": "#/components/schemas/VariantValues"
}
],
"description": "The complete set of overrides this version carries. An overridable attribute absent from\nhere stops being overridden; one the variant may not override keeps its stored value.\n"
},
"_revision": {
"type": "integer",
"minimum": 1,
"description": "The revision read from the version being written. Refused with `WRITE_CONFLICT` if the\nversion has been written since.\n",
"example": 3
},
"valid_from": {
"type": "string",
"description": "Accepted only when it names the version being addressed. Moving a version is an append\nand a delete.\n"
},
"conditions": {
"allOf": [
{
"$ref": "#/components/schemas/PinnedConditions"
}
],
"description": "Accepted only unchanged. A variant's conditions are fixed when it is created."
}
}
},
"PatchVersionRequest": {
"type": "object",
"additionalProperties": false,
"required": [
"values",
"_revision"
],
"properties": {
"values": {
"allOf": [
{
"$ref": "#/components/schemas/VariantValues"
}
],
"description": "Only the overrides to change; everything not mentioned is left as stored. `null` sets a\nvalue rather than removing an override — use the replace operation to remove one.\n"
},
"_revision": {
"type": "integer",
"minimum": 1,
"description": "The revision read from the version being written. Refused with `WRITE_CONFLICT` if the\nversion has been written since.\n",
"example": 3
},
"valid_from": {
"type": "string",
"description": "Accepted only when it names the version being addressed."
},
"conditions": {
"allOf": [
{
"$ref": "#/components/schemas/PinnedConditions"
}
],
"description": "Accepted only unchanged. A variant's conditions are fixed when it is created."
}
}
},
"ListVariantsRequest": {
"type": "object",
"additionalProperties": false,
"description": "How to narrow and page a variant listing. Every property is optional, so `{}` asks for the\nfirst ten variants in `variant_id` order, but the body itself is required. `conditions` and\n`search` narrow independently and a variant must satisfy both.\n",
"properties": {
"conditions": {
"$ref": "#/components/schemas/VariantConditionFilter"
},
"search": {
"type": "string",
"description": "Free text matched against the scalar pins — `string`, `select`, `number` and `date`.\n`location` and `daterange` pins are stored structured and are not matched.\n",
"example": "460"
},
"sort": {
"type": "string",
"description": "`conditions.:asc` or `conditions.:desc`, for a `string`, `select`, `number`\nor `date` pin. `variant_id:asc` is always appended, so the order is total.\n",
"example": "conditions.postal_code:asc"
},
"from": {
"type": "integer",
"minimum": 0,
"default": 0,
"description": "The offset to read from, ignored when a `cursor` is sent. Bounded together with `size`\nby the search index's offset window; a page reaching past it is\n`OFFSET_WINDOW_EXCEEDED`, which reports the window.\n"
},
"size": {
"type": "integer",
"minimum": 1,
"default": 10,
"description": "Rows per page. Clamped silently at 1000."
},
"cursor": {
"type": "string",
"description": "Continue from a previous response's `next`, which is where a caller goes when the offset\nwindow runs out. Opaque, and valid only with the `conditions`, `search` and `sort` it\nwas issued with.\n",
"example": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
}
}
},
"VariantTreeRequest": {
"type": "object",
"additionalProperties": false,
"description": "The variants list's request plus `as_of`, the instant each row's version is selected at.\n`size` is clamped at 100 here; every other property means what it means on the list.\n",
"properties": {
"conditions": {
"$ref": "#/components/schemas/VariantConditionFilter"
},
"search": {
"type": "string",
"description": "Free text matched against the scalar pins — `string`, `select`, `number` and `date`.\n`location` and `daterange` pins are stored structured and are not matched.\n",
"example": "460"
},
"sort": {
"type": "string",
"description": "`conditions.:asc` or `conditions.:desc`, for a `string`, `select`, `number`\nor `date` pin. `variant_id:asc` is always appended, so the order is total.\n",
"example": "conditions.postal_code:asc"
},
"from": {
"type": "integer",
"minimum": 0,
"default": 0,
"description": "The offset to read from, ignored when a `cursor` is sent. Bounded together with `size`\nby the search index's offset window; a page reaching past it is\n`OFFSET_WINDOW_EXCEEDED`, which reports the window.\n"
},
"size": {
"type": "integer",
"minimum": 1,
"default": 10,
"description": "Rows per page. Clamped silently at 100, since every row costs its own version lookup."
},
"cursor": {
"type": "string",
"description": "Continue from a previous response's `next`, which is where a caller goes when the offset\nwindow runs out. Opaque, and valid only with the `conditions`, `search` and `sort` it\nwas issued with.\n",
"example": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
},
"as_of": {
"type": "string",
"description": "The instant each row's version is selected at. Defaults to now. A variant whose first\nversion is later is a row with `status: scheduled` carrying that upcoming version.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time, to at most\nmillisecond precision.\n",
"example": "2027-03-15T00:00:00Z"
}
}
},
"VariantConditionFilter": {
"type": "object",
"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",
"consumption": {
"lt": 5000
}
}
},
"VariantList": {
"type": "object",
"required": [
"hits",
"results"
],
"properties": {
"hits": {
"type": "integer",
"description": "How many variants match in total, exactly — not how many this page carries.",
"example": 8128
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/VariantListRow"
}
},
"next": {
"type": "string",
"description": "The cursor that continues this listing, absent on the last page. Send it back as\n`cursor`, with the same filter, search and sort.\n",
"example": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
}
}
},
"VariantListRow": {
"type": "object",
"description": "One variant as a listing reports it: which variant it is and what it pins.",
"required": [
"variant_id",
"entity_id",
"schema",
"conditions"
],
"properties": {
"variant_id": {
"type": "string",
"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.\nMembership of a page may lag a write by moments; the pins themselves never do.\n"
}
}
},
"VariantTree": {
"type": "object",
"required": [
"hits",
"results"
],
"properties": {
"hits": {
"type": "integer",
"description": "How many variants match in total, exactly — not how many this page carries.",
"example": 8128
},
"results": {
"type": "array",
"description": "One row per matching variant, in the requested order. A variant mid-delete is omitted,\nso `results` can be shorter than `hits` implies.\n",
"items": {
"$ref": "#/components/schemas/VariantTreeRow"
}
},
"next": {
"type": "string",
"description": "The cursor that continues this listing, absent on the last page. Send it back as\n`cursor`, with the same filter, search and sort; `as_of` may change between pages.\n",
"example": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
}
}
},
"VariantTreeRow": {
"type": "object",
"description": "A listing row plus the one version the tree shows for it, and the status saying which.",
"required": [
"variant_id",
"entity_id",
"schema",
"conditions",
"status",
"version"
],
"properties": {
"variant_id": {
"type": "string",
"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.\nMembership of a page may lag a write by moments; the pins themselves never do.\n"
},
"status": {
"$ref": "#/components/schemas/VariantTreeRowStatus"
},
"version": {
"allOf": [
{
"$ref": "#/components/schemas/VariantVersionSnapshot"
}
],
"description": "The version in effect at `as_of`, or the variant's upcoming first one where every\nversion is still ahead of it. `status` says which. Always present.\n"
}
}
},
"VariantTreeRowStatus": {
"type": "string",
"description": "Whether a tree row's version is the one in effect at `as_of`, or one still ahead of it.\n\n- `active`: the version with the latest `valid_from` at or before `as_of`\n- `scheduled`: the variant's first version, which is later than `as_of`\n",
"enum": [
"active",
"scheduled"
]
},
"VariantVersionSnapshot": {
"type": "object",
"description": "One version of one variant as a listing reports it: `VariantVersion` without `_revision`.\nRead the version through its own `GET` to get the revision a write must carry.\n",
"required": [
"variant_id",
"entity_id",
"schema",
"conditions",
"valid_from",
"values",
"_created_at",
"_updated_at"
],
"properties": {
"variant_id": {
"type": "string",
"example": "var-46045"
},
"entity_id": {
"type": "string",
"example": "price-sp26d1yo"
},
"schema": {
"$ref": "#/components/schemas/ConditionalEntitySlug"
},
"conditions": {
"allOf": [
{
"$ref": "#/components/schemas/VariantConditions"
}
],
"description": "The situation the variant applies to, plus the boolean `default` discriminator. A\nproperty of the variant: every version carries the same one.\n"
},
"valid_from": {
"type": "string",
"description": "When this version takes effect, canonicalized to millisecond-precision UTC. Its identity\nwithin the variant.\n",
"example": "2027-01-01T00:00:00.000Z"
},
"values": {
"$ref": "#/components/schemas/VariantValues"
},
"_created_at": {
"type": "string",
"description": "When this version was created.",
"readOnly": true
},
"_updated_at": {
"type": "string",
"description": "When this version was last written.",
"readOnly": true
}
}
},
"VariantVersionList": {
"type": "object",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"description": "A page of the variant's timeline, in the requested `order`.",
"items": {
"$ref": "#/components/schemas/VariantVersionSnapshot"
}
},
"next": {
"type": "string",
"description": "The cursor that continues this timeline, absent only on the last page — the only\nend-of-data signal, since a short or empty page can still carry one. Send it back as\n`cursor`, against the same variant and `order`.\n",
"example": "eyJzayI6IlYjcHJpY2Utc3AyNmQxeW8jdmFyLTQ2MDQ1IzIwMjYtMDEtMDFUMDA6MDA6MDAuMDAwWiIsIm9yZGVyIjoiYXNjIn0"
}
}
},
"BatchUpsertVariantsRequest": {
"type": "object",
"additionalProperties": false,
"description": "A batch of variant writes under one schema, each item naming the entity it writes to.",
"required": [
"items"
],
"properties": {
"correlation_id": {
"type": "string",
"description": "An opaque string echoed back verbatim when it was sent, and never interpreted.",
"example": "tariff-refresh-2027-01"
},
"items": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "The writes to apply, in the order they should apply where two of them address the same\nvariant. At most 100 per call, which is distinct from the per-entity variant cap.\n",
"items": {
"$ref": "#/components/schemas/BatchUpsertItem"
}
}
}
},
"BatchUpsertItem": {
"type": "object",
"additionalProperties": false,
"description": "One variant write: the single-item create's body plus `entity_id`, and no `variant_id`. An\nexisting condition tuple appends a version to the variant holding it rather than conflicting.\n",
"required": [
"entity_id",
"values"
],
"properties": {
"entity_id": {
"type": "string",
"description": "The conditional entity this item writes to.",
"example": "price-sp26d1yo"
},
"conditions": {
"$ref": "#/components/schemas/PinnedConditions"
},
"default": {
"type": "boolean",
"default": false,
"description": "Mark this variant as the entity's fallback, as a create does. An item that pins nothing\nand is not the default is `VARIANT_UNPINNED`.\n"
},
"valid_from": {
"type": "string",
"description": "When the version this item writes takes effect. Omitted, it is a last-write-wins write\nwith no `skipped` detection; a past instant is accepted and reported in this item's\n`warnings`.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time, to at most\nmillisecond precision.\n",
"example": "2027-01-01T00:00:00Z"
},
"values": {
"$ref": "#/components/schemas/VariantValues"
}
}
},
"BatchDeleteVariantsRequest": {
"type": "object",
"additionalProperties": false,
"description": "A batch of variant and version deletes under one schema, each item naming the entity it removes from.",
"required": [
"items"
],
"properties": {
"correlation_id": {
"type": "string",
"description": "An opaque string echoed back verbatim when it was sent, and never interpreted.",
"example": "postal-code-cleanup-2026-09"
},
"items": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"description": "The deletes to apply, in the order they should apply where two of them address the same\nvariant — decided after every condition tuple has been resolved to a variant id. At most\n100 per call.\n",
"items": {
"$ref": "#/components/schemas/BatchDeleteItem"
}
}
}
},
"BatchDeleteItem": {
"description": "One delete: the variant, addressed by id or by the condition tuple it pins, and optionally\nthe one version of it to remove. An item carrying both matches neither branch and is an\nenvelope `400`.\n",
"oneOf": [
{
"$ref": "#/components/schemas/BatchDeleteByVariantId"
},
{
"$ref": "#/components/schemas/BatchDeleteByConditions"
}
]
},
"BatchDeleteByVariantId": {
"type": "object",
"additionalProperties": false,
"description": "A delete addressing its variant by id.",
"required": [
"entity_id",
"variant_id"
],
"properties": {
"entity_id": {
"type": "string",
"description": "The conditional entity the variant belongs to. Required: a variant id alone addresses nothing.",
"example": "price-sp26d1yo"
},
"variant_id": {
"type": "string",
"description": "The variant to remove, or whose version to remove.",
"example": "var-46045"
},
"valid_from": {
"type": "string",
"description": "The one version to remove, by the instant it takes effect. Omitted, the whole variant\ngoes. An RFC 3339 date or date-time, canonicalized before it is matched.\n",
"example": "2027-01-01T00:00:00Z"
}
}
},
"BatchDeleteByConditions": {
"type": "object",
"additionalProperties": false,
"description": "A delete addressing its variant by the situation it applies to.\n\n`conditions` is optional because the fallback variant pins nothing: address it with\n`default: true` and no `conditions`. An item that ends up addressing no variant at all is a\nper-item `VARIANT_UNPINNED`, and one marking `default` beside `conditions` is refused per\nitem with no code.\n",
"required": [
"entity_id"
],
"properties": {
"entity_id": {
"type": "string",
"description": "The conditional entity the variant belongs to.",
"example": "price-sp26d1yo"
},
"conditions": {
"$ref": "#/components/schemas/PinnedConditions"
},
"default": {
"type": "boolean",
"default": false,
"description": "Address the entity's fallback variant, the one served when nothing else applies."
},
"valid_from": {
"type": "string",
"description": "The one version to remove, by the instant it takes effect. Omitted, the whole variant\ngoes. An RFC 3339 date or date-time, canonicalized before it is matched.\n",
"example": "2027-01-01T00:00:00Z"
}
}
},
"BatchUpsertResult": {
"type": "object",
"description": "What a batch upsert did: one entry per item, in request order, and a count per outcome.",
"required": [
"counts",
"results"
],
"properties": {
"correlation_id": {
"type": "string",
"description": "The `correlation_id` the request carried, echoed only when it was sent.",
"example": "tariff-refresh-2027-01"
},
"counts": {
"$ref": "#/components/schemas/BatchUpsertCounts"
},
"results": {
"type": "array",
"description": "One entry per item, in request order, which is what maps an outcome back to its source row.",
"items": {
"$ref": "#/components/schemas/BatchUpsertResultEntry"
}
}
}
},
"BatchDeleteResult": {
"type": "object",
"description": "What a batch delete did: one entry per item, in request order, and a count per outcome.",
"required": [
"counts",
"results"
],
"properties": {
"correlation_id": {
"type": "string",
"description": "The `correlation_id` the request carried, echoed only when it was sent.",
"example": "postal-code-cleanup-2026-09"
},
"counts": {
"$ref": "#/components/schemas/BatchDeleteCounts"
},
"results": {
"type": "array",
"description": "One entry per item, in request order, which is what maps an outcome back to its source row.",
"items": {
"$ref": "#/components/schemas/BatchDeleteResultEntry"
}
}
}
},
"BatchUpsertOutcome": {
"type": "string",
"description": "What one upsert item did, derived from what was stored.\n\n- `variant_created`: the condition tuple was unknown, so a variant and its first version\n were created\n- `version_created`: the tuple was known and had no version at the item's `valid_from`\n- `updated`: a version existed at that exact instant and was written in place\n- `skipped`: the values are identical to what is stored; not detected for an item without\n `valid_from`\n- `error`: this item alone failed, and the entry's `error` says why\n",
"enum": [
"variant_created",
"version_created",
"updated",
"skipped",
"error"
]
},
"BatchDeleteOutcome": {
"type": "string",
"description": "What one delete item did.\n\n- `deleted`: the variant, or the one version the item named, is gone\n- `skipped`: the item addressed no such variant or version; a missing entity is an `error`\n- `error`: this item alone failed, and the entry's `error` says why\n",
"enum": [
"deleted",
"skipped",
"error"
]
},
"BatchUpsertCounts": {
"type": "object",
"additionalProperties": false,
"description": "How many items reached each outcome. Keyed by exactly the values of `BatchUpsertOutcome`,\nall present, and summing to the length of `results`.\n",
"required": [
"variant_created",
"version_created",
"updated",
"skipped",
"error"
],
"properties": {
"variant_created": {
"type": "integer",
"example": 1
},
"version_created": {
"type": "integer",
"example": 1
},
"updated": {
"type": "integer",
"example": 1
},
"skipped": {
"type": "integer",
"example": 1
},
"error": {
"type": "integer",
"example": 1
}
}
},
"BatchDeleteCounts": {
"type": "object",
"additionalProperties": false,
"description": "How many items reached each outcome. Keyed by exactly the values of `BatchDeleteOutcome`,\nall present, and summing to the length of `results`.\n",
"required": [
"deleted",
"skipped",
"error"
],
"properties": {
"deleted": {
"type": "integer",
"example": 1
},
"skipped": {
"type": "integer",
"example": 1
},
"error": {
"type": "integer",
"example": 1
}
}
},
"BatchUpsertResultEntry": {
"type": "object",
"additionalProperties": false,
"description": "What one upsert item did. Position in `results` maps it back to its source row.",
"required": [
"outcome",
"entity_id",
"warnings"
],
"properties": {
"outcome": {
"$ref": "#/components/schemas/BatchUpsertOutcome"
},
"entity_id": {
"type": "string",
"description": "The entity this item wrote to, echoed from the item.",
"example": "price-sp26d1yo"
},
"variant_id": {
"type": "string",
"description": "The variant this item created or wrote to. Present on every outcome but `error`.",
"example": "var-46045"
},
"valid_from": {
"type": "string",
"description": "The version this item wrote, canonicalized to millisecond-precision UTC. Present on\nevery outcome but `error`, including for an item that sent none.\n",
"example": "2027-01-01T00:00:00.000Z"
},
"warnings": {
"type": "array",
"description": "Things worth knowing that did not stop this item's write. Always present and possibly\nempty, on every outcome. Fires per item, with no batch-level deduplication.\n",
"items": {
"$ref": "#/components/schemas/WriteWarning"
}
},
"error": {
"allOf": [
{
"$ref": "#/components/schemas/ConditionalPricingError"
}
],
"description": "Why this item failed, present only with `outcome: error`: the codes a variant create\nraises, plus `ENTITY_NOT_FOUND`, `ENTITY_TYPE_MISMATCH` and `ENTITY_NOT_CONDITIONAL`,\nwhich are per item because each item names its own entity. Never `TUPLE_CONFLICT` or\n`VERSION_CONFLICT`.\n"
}
}
},
"BatchDeleteResultEntry": {
"type": "object",
"additionalProperties": false,
"description": "What one delete item did. Position in `results` maps it back to its source row.",
"required": [
"outcome",
"entity_id",
"warnings"
],
"properties": {
"outcome": {
"$ref": "#/components/schemas/BatchDeleteOutcome"
},
"entity_id": {
"type": "string",
"description": "The entity this item removed from, echoed from the item.",
"example": "price-sp26d1yo"
},
"variant_id": {
"type": "string",
"description": "The variant this item removed, or whose version it removed. Present wherever it is\nknown, so a `skipped` entry for a tuple no variant pins names none.\n",
"example": "var-46045"
},
"valid_from": {
"type": "string",
"description": "The version this item removed, canonicalized to millisecond-precision UTC. Absent where\nthe item removed the whole variant.\n",
"example": "2027-01-01T00:00:00.000Z"
},
"warnings": {
"type": "array",
"description": "Things worth knowing that did not stop this item's delete, chiefly which reads the\nremoval moved. Always present and possibly empty, on every outcome.\n",
"items": {
"$ref": "#/components/schemas/WriteWarning"
}
},
"error": {
"allOf": [
{
"$ref": "#/components/schemas/ConditionalPricingError"
}
],
"description": "Why this item failed, present only with `outcome: error`:\n`LAST_VERSION_UNDELETABLE`, `VARIANT_UNPINNED`, the codes a condition tuple that cannot\nbe canonicalized raises, `IDENTIFIER_INVALID`, `VALID_FROM_INVALID`, `WRITE_CONFLICT`,\nand the per-item `ENTITY_NOT_FOUND`, `ENTITY_TYPE_MISMATCH` and\n`ENTITY_NOT_CONDITIONAL`. A missing variant or version is `skipped` instead.\n"
}
}
},
"Error": {
"required": [
"message"
],
"properties": {
"message": {
"type": "string",
"description": "Error message"
},
"status": {
"type": "number",
"description": "The HTTP status code"
},
"cause": {
"type": "string",
"description": "The cause of the error (visible for bad requests - http 400)"
}
}
},
"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": [
{
"type": "string",
"description": "The message, the same string as `message`.",
"example": "The conditions requested for variant var-46045 are already pinned"
},
{
"type": "array",
"description": "One entry per validation failure, as the request validator reported it.",
"items": {
"type": "object",
"additionalProperties": true
}
}
]
},
"ConditionalPricingError": {
"description": "An error from a conditional-pricing operation, carrying a `code` plus the structured data\nthat code explains. `details` is typed per code: narrow on `code` and the object under it\ndeclares exactly the fields that code sends.\n\nA request these schemas reject is answered by the request validator with a message and\ncarries neither `code` nor `details` — the last member of the union.\n",
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"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"
}
}
},
{
"oneOf": [
{
"type": "object",
"description": "No conditional entity type by that slug.",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"SCHEMA_NOT_FOUND"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"schema"
],
"properties": {
"schema": {
"type": "string",
"description": "The entity type the request addressed.",
"example": "price"
}
}
}
}
},
{
"type": "object",
"description": "The schema holds no entity with that id.",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"ENTITY_NOT_FOUND"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"schema",
"entity_id"
],
"properties": {
"schema": {
"type": "string",
"description": "The entity type the request addressed.",
"example": "price"
},
"entity_id": {
"type": "string",
"description": "The conditional entity the request addressed.",
"example": "price-sp26d1yo"
}
}
}
}
},
{
"type": "object",
"description": "That entity id belongs to an entity of a different type than the `{slug}` segment\nnamed. Correct the slug and send the request again.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"ENTITY_TYPE_MISMATCH"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"schema",
"entity_id",
"actual_schema"
],
"properties": {
"schema": {
"type": "string",
"description": "The entity type the request addressed.",
"example": "price"
},
"entity_id": {
"type": "string",
"description": "The conditional entity the request addressed.",
"example": "price-sp26d1yo"
},
"actual_schema": {
"type": "string",
"description": "The entity type that id belongs to. Where it is a conditional entity type,\nit is the slug to send instead.\n",
"example": "product"
}
}
}
}
},
{
"type": "object",
"description": "The entity is of the type the slug named and was not created with `is_conditional`,\nwhich is fixed at creation. Reading and writing the entity itself are unaffected.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"ENTITY_NOT_CONDITIONAL"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"schema",
"entity_id"
],
"properties": {
"schema": {
"type": "string",
"description": "The entity type the request addressed.",
"example": "price"
},
"entity_id": {
"type": "string",
"description": "The conditional entity the request addressed.",
"example": "price-sp26d1yo"
}
}
}
}
},
{
"type": "object",
"description": "This entity has no such variant.",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"VARIANT_NOT_FOUND"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"entity_id",
"variant_id"
],
"properties": {
"entity_id": {
"type": "string",
"description": "The conditional entity the request addressed.",
"example": "price-sp26d1yo"
},
"variant_id": {
"type": "string",
"description": "The variant the request addressed.",
"example": "var-46045"
}
}
}
}
},
{
"type": "object",
"description": "No version at that `valid_from` — never written, or deleted since. A version is\naddressed by the exact instant it takes effect from; for the version in effect at an\ninstant, see `NO_ACTIVE_VERSION`.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"VERSION_NOT_FOUND"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"variant_id",
"valid_from"
],
"properties": {
"variant_id": {
"type": "string",
"description": "The variant the request addressed.",
"example": "var-46045"
},
"valid_from": {
"type": "string",
"description": "The version the request addressed, by the instant it takes effect from.",
"example": "2027-01-01T00:00:00.000Z"
}
}
}
}
},
{
"type": "object",
"description": "Nothing applied to the given context and the entity has no `default` variant. Only\nreachable with `resolve_one`; without it the same situation is a `200` carrying an\nempty `results`.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"NO_MATCHES"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"schema",
"entity_id"
],
"properties": {
"schema": {
"type": "string",
"description": "The entity type the request addressed.",
"example": "price"
},
"entity_id": {
"type": "string",
"description": "The conditional entity the resolve was scoped to.",
"example": "price-sp26d1yo"
}
}
}
}
},
{
"type": "object",
"description": "The variant has no version in effect at the instant asked about — typically a\nvariant staged ahead of its launch. Address one of its versions by `valid_from` to\nread or edit it before it takes effect.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"NO_ACTIVE_VERSION"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"variant_id",
"as_of"
],
"properties": {
"variant_id": {
"type": "string",
"description": "The variant the request addressed.",
"example": "var-46045"
},
"as_of": {
"type": "string",
"description": "The instant a version in effect was asked for at.",
"example": "2026-06-01T00:00:00.000Z"
}
}
}
}
},
{
"type": "object",
"description": "Several variants apply to the given context while a single result was requested.",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"AMBIGUOUS_RESOLUTION"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"candidates"
],
"properties": {
"candidates": {
"type": "array",
"minItems": 2,
"description": "Every variant that applied, each with the conditions it pins.",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"variant_id",
"conditions"
],
"properties": {
"variant_id": {
"type": "string",
"description": "The candidate variant.",
"example": "var-46045"
},
"conditions": {
"$ref": "#/components/schemas/VariantConditions"
}
}
}
}
}
}
}
},
{
"type": "object",
"description": "The condition tuple this write claims is already held. Persistent, unlike\n`WRITE_CONFLICT`: the same request fails the same way until the holder changes.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"TUPLE_CONFLICT"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"variant_id"
],
"properties": {
"variant_id": {
"type": "string",
"description": "The variant the write addressed.",
"example": "var-46045"
},
"conflicting_variant_id": {
"type": "string",
"description": "The variant already holding the tuple, where the write read it back.",
"example": "var-50667"
}
}
}
}
},
{
"type": "object",
"description": "A version already exists at the given `valid_from` on that variant.",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"VERSION_CONFLICT"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"variant_id",
"valid_from"
],
"properties": {
"variant_id": {
"type": "string",
"description": "The variant the write addressed.",
"example": "var-46045"
},
"valid_from": {
"type": "string",
"description": "The instant already claimed by a version of that variant.",
"example": "2027-01-01T00:00:00.000Z"
}
}
}
}
},
{
"type": "object",
"description": "The request names a condition the entity's schema does not define. A *stored* pin on\na condition the schema no longer declares is `VARIANT_PIN_UNDECLARED`.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"CONDITION_UNDEFINED"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"condition_name"
],
"properties": {
"condition_name": {
"type": "string",
"description": "The condition the request named and the schema does not define.",
"example": "postal_code"
}
}
}
}
},
{
"type": "object",
"description": "A variant a resolve would compose pins a condition the entity's schema no longer\ndeclares, which would make it match every context. Declare the condition again, or\nremove the variants pinning it — found with `variants:list` or the tree, and removed\nby id.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"VARIANT_PIN_UNDECLARED"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"condition_name",
"variant_id"
],
"properties": {
"condition_name": {
"type": "string",
"description": "The condition the variant pins and the schema no longer declares.",
"example": "postal_code"
},
"variant_id": {
"type": "string",
"description": "One variant carrying such a pin.",
"example": "var-46045"
}
}
}
}
},
{
"type": "object",
"description": "The requested operator is not applicable to the condition's type.",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"OPERATOR_UNSUPPORTED"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"condition_name",
"condition_type",
"operator"
],
"properties": {
"condition_name": {
"type": "string",
"example": "postal_code"
},
"condition_type": {
"type": "string",
"description": "The type the schema declares that condition with.",
"example": "location"
},
"operator": {
"type": "string",
"description": "The predicate the context or filter asked for, or `sort` where a listing\nasked to order by a condition whose type has no order.\n",
"example": "between"
}
}
}
}
},
{
"type": "object",
"description": "A resolve context or listing filter value that is malformed for its condition's type.",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"CONTEXT_FORMAT_INVALID"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"condition_name",
"expected"
],
"properties": {
"condition_name": {
"type": "string",
"example": "postal_code"
},
"expected": {
"type": "string",
"description": "What a value for that condition has to be, in prose.",
"example": "a postal code"
}
}
}
}
},
{
"type": "object",
"description": "A variant write pins a `select` value absent from its condition's vocabulary. A\ncondition declaring no vocabulary at all is `CONDITION_UNCONFIGURED`, and one whose\n`options` hold nothing readable is `CONDITION_UNREADABLE`.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"CONDITION_VALUE_INVALID"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"condition_name",
"value",
"options"
],
"properties": {
"condition_name": {
"type": "string",
"example": "segment"
},
"value": {
"description": "The value the write pinned, as it arrived.",
"example": "industrial"
},
"options": {
"type": "array",
"minItems": 1,
"description": "The vocabulary as enforced, after any entries this deploy cannot read have\nbeen dropped.\n",
"items": {
"type": "string"
},
"example": [
"private",
"commercial"
]
}
}
}
}
},
{
"type": "object",
"description": "A variant write pins a `select` condition whose `options` are absent or empty. A\n`select` vocabulary is always closed, so one declaring nothing admits nothing; fill\nthe `options` in.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"CONDITION_UNCONFIGURED"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"condition_name"
],
"properties": {
"condition_name": {
"type": "string",
"description": "The condition whose vocabulary is not configured yet.",
"example": "segment"
}
}
}
}
},
{
"type": "object",
"description": "A multi-match resolve found more variants than one response may carry. Narrow the\ncontext; the matches are not reported.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"TOO_MANY_MATCHES"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"limit"
],
"properties": {
"limit": {
"type": "number",
"description": "The most variants one resolve may compose.",
"example": 100
}
}
}
}
},
{
"type": "object",
"description": "Transient write contention. Retryable, unlike `TUPLE_CONFLICT`. The revisions are\npresent where the contention was detected on a specific version.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"WRITE_CONFLICT"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"variant_id"
],
"properties": {
"variant_id": {
"type": "string",
"description": "The variant the write addressed.",
"example": "var-46045"
},
"valid_from": {
"type": "string",
"description": "The version the write addressed, where one was addressed.",
"example": "2027-01-01T00:00:00.000Z"
},
"expected_revision": {
"type": "number",
"description": "The revision the write required the stored version to still be at.",
"example": 3
},
"current_revision": {
"type": "number",
"description": "The revision the version is actually at, where the failed write read it back.",
"example": 4
}
}
}
}
},
{
"type": "object",
"description": "A listing's `from` plus `size` reaches past the offset window the search index\nallows — the window bounds the last row a page may contain. The page is not clamped;\npage on with the last response's `next` instead.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"OFFSET_WINDOW_EXCEEDED"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"from",
"size",
"window"
],
"properties": {
"from": {
"type": "integer",
"description": "The offset the request asked for.",
"example": 24990
},
"size": {
"type": "integer",
"description": "The page size the request asked for, after clamping.",
"example": 25
},
"window": {
"type": "integer",
"description": "The last row this deploy's index will serve from an offset.",
"example": 25000
}
}
}
}
},
{
"type": "object",
"description": "A paging cursor could not be used for the read it arrived on. Start the read again\nwithout one; `details.reason` says which check failed.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"CURSOR_INVALID"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"reason"
],
"properties": {
"reason": {
"type": "string",
"description": "Which check the cursor failed, in prose.",
"example": "The cursor was issued for a different sort order"
}
}
}
}
},
{
"type": "object",
"description": "The entity already holds every variant it may hold. In a batch, every remaining item\nfor that entity will be refused the same way.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"VARIANT_LIMIT_REACHED"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"variant_count",
"cap"
],
"properties": {
"variant_count": {
"type": "number",
"description": "Variants this entity already holds.",
"example": 5000
},
"cap": {
"type": "number",
"description": "Variants this entity may hold. Configurable per deploy.",
"example": 5000
}
}
}
}
},
{
"type": "object",
"description": "A variant pins a value malformed for its condition's type. `condition_type` is what\na client branches on; `expected` says what the value had to be, which the type alone\ndoes not — a `location` is `location` whichever `format` it declares.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"PIN_FORMAT_INVALID"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"condition_name",
"condition_type",
"expected",
"value"
],
"properties": {
"condition_name": {
"type": "string",
"example": "valid_period"
},
"condition_type": {
"type": "string",
"description": "The type the schema declares that condition with.",
"example": "daterange"
},
"expected": {
"type": "string",
"description": "What a pin for that condition has to be, in prose.",
"example": "an object carrying a from and an until date, either may be open"
},
"value": {
"description": "The value the write pinned, as it arrived.",
"example": "2027-01-01/2027-12-31"
}
}
}
}
},
{
"type": "object",
"description": "The write pins no condition and is not marked `default`, so it would match every\nresolve. On a delete, the item addresses no variant at all.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"VARIANT_UNPINNED"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"entity_id"
],
"properties": {
"entity_id": {
"type": "string",
"description": "The conditional entity the item addressed.",
"example": "price-sp26d1yo"
}
}
}
}
},
{
"type": "object",
"description": "The delete would leave the variant with no version at all, which would keep its\ncondition tuple claimed while resolving to nothing. Delete the variant instead.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"LAST_VERSION_UNDELETABLE"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"variant_id",
"valid_from"
],
"properties": {
"variant_id": {
"type": "string",
"description": "The variant whose last version the delete addressed.",
"example": "var-46045"
},
"valid_from": {
"type": "string",
"description": "The version the delete addressed, by the instant it takes effect from.",
"example": "2027-01-01T00:00:00.000Z"
}
}
}
}
},
{
"type": "object",
"description": "A condition the entity's schema declares in a way this deploy cannot read: a\n`location` whose `format` is unrecognized or absent, or a `select` whose `options`\nhold nothing readable. Repair the definition on the schema.\n\nReads that do not interpret the condition — an unfiltered variants list, the tree, a\nvariant by id, a version timeline — keep working.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"CONDITION_UNREADABLE"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"condition_name",
"unreadable"
],
"properties": {
"condition_name": {
"type": "string",
"description": "The condition whose definition this deploy cannot read.",
"example": "delivery_area"
},
"unreadable": {
"type": "string",
"description": "Which field of the definition cannot be read, named as the schema spells it.",
"enum": [
"format",
"options"
],
"example": "format"
}
}
}
}
},
{
"type": "object",
"description": "A listing's `sort` is not a field and direction this API can read. A well-formed\n`sort` naming a condition is refused under that condition's own code instead.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"SORT_INVALID"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"expected"
],
"properties": {
"expected": {
"type": "string",
"description": "What a `sort` has to be, in prose.",
"example": "conditions.:asc or conditions.:desc, naming a string, select, number or date condition"
}
}
}
}
},
{
"type": "object",
"description": "The fallback marker — `default` or `_default` — used as though it were a condition.\nMark the variant `default` instead, or leave the marker out of the context.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"DEFAULT_MARKER_RESERVED"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"condition_name"
],
"properties": {
"condition_name": {
"type": "string",
"description": "The marker, spelled as the request spelled it.",
"example": "default"
}
}
}
}
},
{
"type": "object",
"description": "A variant marked `default` that also pins real conditions. Drop `default` to keep\nthe pins, or drop the pins to keep the fallback.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"DEFAULT_VARIANT_PINS_CONDITIONS"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"condition_names"
],
"properties": {
"condition_names": {
"type": "array",
"description": "The conditions the write pinned beside the marker.",
"items": {
"type": "string"
},
"example": [
"postal_code"
]
}
}
}
}
},
{
"type": "object",
"description": "A version write asking for a different `valid_from` than the version its own address\nnames. Moving a version is an append and a delete; a body repeating the `valid_from`\nit was read with is accepted.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"VALID_FROM_IMMUTABLE"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"addressed",
"requested"
],
"properties": {
"addressed": {
"type": "string",
"description": "The version the request addressed, by the instant it takes effect from.",
"example": "2027-01-01T00:00:00.000Z"
},
"requested": {
"type": "string",
"description": "The instant the body asked for instead, canonicalized.",
"example": "2027-04-01T00:00:00.000Z"
}
}
}
}
},
{
"type": "object",
"description": "A version write carrying a condition tuple other than the one its variant was\ncreated with. Create a second variant for the other situation.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"VARIANT_CONDITIONS_IMMUTABLE"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"variant_id"
],
"properties": {
"variant_id": {
"type": "string",
"description": "The variant whose conditions the write would have changed.",
"example": "var-46045"
}
}
}
}
},
{
"type": "object",
"description": "An id in the request that cannot be used as a storage key: empty, longer than 128\ncharacters, or carrying a character outside letters, digits, `_`, `.`, `:` and `-`.\nEvery id the platform issues qualifies.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"IDENTIFIER_INVALID"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"field",
"reason"
],
"properties": {
"field": {
"type": "string",
"description": "Which id could not be keyed by, named as the request names it.",
"enum": [
"entity_id",
"variant_id"
],
"example": "entity_id"
},
"reason": {
"type": "string",
"description": "Which of the three checks the id failed, in prose.",
"example": "it carries a character this scheme does not admit"
}
}
}
}
},
{
"type": "object",
"description": "A `valid_from` that is not one of the timestamp forms a version timeline can be\nsorted by. Wider ISO 8601 forms — a bare year, an ordinal date, `T24:00:00Z` — are\nrefused rather than interpreted.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"VALID_FROM_INVALID"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"expected"
],
"properties": {
"expected": {
"type": "string",
"description": "What a `valid_from` has to be, in prose.",
"example": "an RFC 3339 date, optionally with a time to at most millisecond precision and an optional UTC offset"
}
}
}
}
},
{
"type": "object",
"description": "A value the store cannot hold: a non-finite number, one outside the table's numeric\nrange, or a key with no value. Send a value needing more precision than a JSON\nnumber carries as a decimal string, as `unit_amount_decimal` does.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"VALUE_UNSTORABLE"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"path",
"reason"
],
"properties": {
"path": {
"type": "string",
"description": "Where the value sits, as a dotted path of the request's own keys, with array\nentries by index.\n",
"example": "values.tiers.0.unit_amount"
},
"reason": {
"type": "string",
"description": "What about the value cannot be stored, in prose.",
"example": "the non-finite number Infinity"
}
}
}
}
},
{
"type": "object",
"description": "An override whose value is not of the type its field holds. A field declared by a\n`currency` attribute `x` takes `x` as a number, `x_decimal` as a non-empty string and\n`x_currency` as one of the attribute's currency codes, in any case. A field declared\nby a `number` attribute takes a string, or a number where the attribute sets\n`data_type: number`. A field a capability manages that neither attribute type\ndeclares, such as `tiers`, is checked at any depth by the amount/decimal convention:\na key `K_decimal` is a non-empty string, and a `K` beside it is a number. No other\nvalue is checked, and a decimal string is not parsed.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"OVERRIDE_VALUE_INVALID"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"required": [
"path",
"expected"
],
"properties": {
"path": {
"type": "string",
"description": "Where the value sits, as a dotted path of the request's own keys, with array\nentries by index.\n",
"example": "values.tiers.0.unit_amount_decimal"
},
"expected": {
"type": "string",
"description": "What the value has to be, in prose.",
"example": "a non-empty string"
}
}
}
}
},
{
"type": "object",
"description": "The organization has not opted in to Conditional Pricing. Opting in is done once, by\nepilot, from the organization's settings; nothing in this API enables it.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"CONDITIONAL_PRICING_NOT_ENABLED"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"properties": {}
}
}
},
{
"type": "object",
"description": "The organization opted in, and its setup, which takes minutes, has not finished. No\nvariant can be created until it has; try again in a few minutes.\n",
"required": [
"code",
"details"
],
"properties": {
"code": {
"type": "string",
"enum": [
"CONDITIONAL_PRICING_NOT_READY"
]
},
"details": {
"type": "object",
"additionalProperties": false,
"properties": {}
}
}
},
{
"type": "object",
"description": "A refusal that carries no code: one the request validator raises before any handler\nruns, or a token that names no organization this API can act for. The message says\nwhat to fix, and no code is sent — which is how a client tells this member from the\ncoded ones.\n",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
},
"status": {
"type": "number"
},
"cause": {
"type": "string"
},
"error": {
"$ref": "#/components/schemas/ReportedError"
}
}
}
]
}
]
},
"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"
},
{
"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"
}
}
},
{
"oneOf": [
{
"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"
}
}
},
{
"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"
}
}
},
{
"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",
"description": "The description for the product"
},
"code": {
"type": "string",
"description": "The product code"
},
"type": {
"type": "string",
"description": "The type of Product:\n\n| type | description |\n|----| ----|\n| `product` | Represents a physical good |\n| `service` | Represents a service or virtual product |\n",
"enum": [
"product",
"service"
]
},
"name": {
"type": "string",
"description": "The product main name"
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "The product categories"
},
"feature": {
"type": "array",
"items": {
"type": "object",
"properties": {
"_tags": {
"type": "array",
"description": "An arbitrary set of tags attached to a feature",
"items": {
"type": "string"
}
},
"feature": {
"type": "string"
}
}
}
},
"product_images": {
"description": "Stores references to a set of file images of the product",
"oneOf": [
{
"type": "object",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRelation"
}
}
}
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/File"
}
}
]
},
"product_downloads": {
"description": "Stores references to a set of files downloadable from the product.\ne.g: tech specifications, quality control sheets, privacy policy agreements\n",
"oneOf": [
{
"type": "object",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRelation"
}
}
}
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/File"
}
}
]
},
"is_conditional": {
"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": {
"type": "array",
"description": "Stores references to the availability files that define where this product is available.\nThese files are used when interacting with products via epilot Journeys, thought the AvailabilityCheck block.\n",
"items": {
"$ref": "#/components/schemas/File"
}
},
"_id": {
"type": "string",
"description": "The product id"
},
"_title": {
"type": "string",
"description": "The autogenerated product title"
},
"_org_id": {
"type": "string",
"description": "The organization id the product belongs to"
},
"_created_at": {
"type": "string",
"description": "The product creation date",
"readOnly": true
},
"_updated_at": {
"type": "string",
"description": "The product last update date",
"readOnly": true
}
}
},
"Product": {
"type": "object",
"description": "The product entity, its relations as stored.",
"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": []
}
]
},
"product_images": {
"$relation": [
{
"entity_id": "37bdeaaa-65fe-403e-9894-65b01cd277f1"
},
{
"entity_id": "56dde657-795c-41bb-bf53-98fd586b7e6e"
}
]
},
"product_downloads": {
"$relation": [
{
"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": [
{
"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": {
"$relation_ref": [
{
"entity_id": "69bf4355-9c1e-498a-b87e-6c873668194d",
"path": "address.25"
}
]
},
"_id": "319a274b-0477-45e3-9d58-1f46c82d4604",
"_org": "728",
"_created_at": "2022-06-03T15:26:14.006Z",
"_updated_at": "2022-06-03T15:26:14.006Z"
},
"properties": {
"opportunity_number": {
"type": "string",
"description": "The opportunity id number for the customer (autogenerated if left blank)"
},
"opportunity_title": {
"type": "string",
"description": "The opportunity title for the opportunity"
},
"description": {
"type": "string",
"description": "A description to frame this opportunity within its sales process"
},
"status": {
"type": "string",
"description": "The opportunity status (defined by the opportunity workflow)"
},
"due_date": {
"type": "string",
"description": "The expiration date"
},
"assignee": {
"description": "The opportunity assignees",
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"email": {
"type": "string"
},
"display_name": {
"type": "string"
},
"token": {
"type": "string"
},
"image_uri": {
"type": "string"
},
"organization_id": {
"type": "string"
},
"department": {
"type": "string"
},
"preferred_language": {
"type": "string"
},
"status": {
"type": "string"
},
"phone": {
"type": "string"
},
"email_notification_settings": {
"type": "object"
},
"is_signature_enabled": {
"type": "boolean"
},
"created_at": {
"type": "string"
}
}
}
},
"customer": {
"type": "object",
"description": "A list of customers related with the opportunity",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRelation"
}
}
}
},
"dates": {
"type": "array",
"description": "A set of dates associated with the opportunity",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"_tags": {
"type": "array",
"description": "The date tags",
"items": {
"type": "string"
}
},
"value": {
"description": "The date value",
"type": "string"
}
}
}
]
}
},
"billing_address": {
"description": "The billing address",
"type": "object",
"properties": {
"$relation_ref": {
"description": "The relation from which a field is being referenced",
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"entity_id": {
"description": "The id of the referenced entity",
"type": "string"
},
"path": {
"description": "The path to the target attribute being referenced",
"type": "string"
}
}
}
]
}
}
}
},
"delivery_address": {
"description": "The delivery address",
"type": "object",
"properties": {
"$relation_ref": {
"description": "The relation from which a field is being referenced",
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"entity_id": {
"description": "The id of the referenced entity",
"type": "string"
},
"path": {
"description": "The path to the target attribute being referenced",
"type": "string"
}
}
}
]
}
}
}
},
"address": {
"description": "A list of additional addresses",
"type": "object",
"properties": {
"$relation_ref": {
"description": "The relation from which a field is being referenced",
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"entity_id": {
"description": "The id of the referenced entity",
"type": "string"
},
"path": {
"description": "The path to the target attribute being referenced",
"type": "string"
}
}
}
]
}
}
}
},
"items": {
"type": "object",
"description": "The order relations items, representing quotes or orders associated with the opportunity",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrderRelation"
}
}
}
},
"_org_id": {
"type": "string",
"description": "Organization Id the order belongs to"
},
"_id": {
"type": "string",
"description": "The opportunity id",
"readOnly": true
},
"_created_at": {
"type": "string",
"description": "The opportunity creation date",
"readOnly": true
},
"_updated_at": {
"type": "string",
"description": "The opportunity last update date",
"readOnly": true
},
"source_type": {
"type": "string",
"description": "Type of source, e.g. journey or manual",
"example": "journey"
},
"source_id": {
"type": "string",
"description": "Identifier for source e.g. journey ID",
"example": "ce99875f-fba9-4fe2-a8f9-afaf52059051"
},
"source": {
"$ref": "#/components/schemas/OpportunitySource"
},
"_tags": {
"type": "array",
"description": "An arbitrary set of tags attached to the opportunity",
"items": {
"type": "string"
}
}
}
},
"Order": {
"type": "object",
"description": "The order entity",
"additionalProperties": true,
"example": {
"order_number": "OR 2022/742701",
"status": "quote",
"source": {
"title": "manual",
"href": null
},
"source_type": "manual",
"_schema": "order",
"_title": "OR 2022/742701",
"expires_at": "2022-06-30T16:17:00.000Z",
"line_items": [
{
"price_id": "9c36c23b-1574-4193-beff-b1b5e1124bc7",
"product_id": "a7f4771a-6368-4d77-bb01-71f1e4902de5",
"pricing_model": "per_unit",
"is_composite_price": false,
"taxes": [
{
"tax": {
"_id": "24641e82-0690-4135-8b43-ef12a9b1c5dc",
"rate": 19,
"_schema": "tax",
"_org": "728",
"_created_at": "2021-09-24T15:06:13.859Z",
"_updated_at": "2022-04-04T17:36:15.273Z",
"_title": "Tax Standard",
"type": "VAT",
"active": true,
"region": "DE",
"description": "Standard"
},
"amount": 255462
}
],
"_price": {
"_id": "9c36c23b-1574-4193-beff-b1b5e1124bc7",
"unit_amount": 100000,
"unit_amount_currency": "EUR",
"unit_amount_decimal": "1000",
"sales_tax": "standard",
"is_tax_inclusive": true,
"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,
"pricing_model": "per_unit",
"is_composite_price": false,
"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"
},
"_product": {
"_id": "a7f4771a-6368-4d77-bb01-71f1e4902de5",
"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": []
}
]
},
"product_images": {
"$relation": [
{
"entity_id": "37bdeaaa-65fe-403e-9894-65b01cd277f1"
},
{
"entity_id": "56dde657-795c-41bb-bf53-98fd586b7e6e"
}
]
},
"product_downloads": {
"$relation": [
{
"entity_id": "64211361-8759-414b-81c0-afbf24f83aa9"
}
]
},
"_org": "728",
"_created_at": "2022-06-03T15:52:27.512Z",
"_updated_at": "2022-06-03T16:05:15.029Z",
"price_options": {
"$relation": [
{
"entity_id": "9c36c23b-1574-4193-beff-b1b5e1124bc7",
"_tags": []
},
{
"entity_id": "146aa2cc-f267-4d5e-bda4-cbe2669b7741",
"_tags": []
}
]
}
},
"quantity": 16,
"currency": "EUR",
"description": "Solar Panel Module",
"unit_amount": 100000,
"unit_amount_net": 84034,
"amount_subtotal": 1344538,
"amount_total": 1600000
},
{
"price_id": "146aa2cc-f267-4d5e-bda4-cbe2669b7741",
"product_id": "a7f4771a-6368-4d77-bb01-71f1e4902de5",
"pricing_model": "per_unit",
"is_composite_price": false,
"taxes": [
{
"tax": {
"_id": "24641e82-0690-4135-8b43-ef12a9b1c5dc",
"rate": 19,
"_schema": "tax",
"_org": "728",
"_created_at": "2021-09-24T15:06:13.859Z",
"_updated_at": "2022-04-04T17:36:15.273Z",
"_title": "Tax Standard",
"type": "VAT",
"active": true,
"region": "DE",
"description": "Standard"
},
"amount": 31933
}
],
"_price": {
"_id": "146aa2cc-f267-4d5e-bda4-cbe2669b7741",
"unit_amount": 50000,
"unit_amount_currency": "EUR",
"unit_amount_decimal": "500",
"sales_tax": "standard",
"is_tax_inclusive": true,
"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": "Battery Module 500amps",
"description": "Battery Module 500amps",
"active": true,
"pricing_model": "per_unit",
"is_composite_price": false,
"tax": {
"$relation": [
{
"entity_id": "24641e82-0690-4135-8b43-ef12a9b1c5dc"
}
]
},
"_org": "728",
"_created_at": "2022-06-03T16:05:04.391Z",
"_updated_at": "2022-06-03T16:05:04.391Z"
},
"_product": {
"_id": "a7f4771a-6368-4d77-bb01-71f1e4902de5",
"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": []
}
]
},
"product_images": {
"$relation": [
{
"entity_id": "37bdeaaa-65fe-403e-9894-65b01cd277f1"
},
{
"entity_id": "56dde657-795c-41bb-bf53-98fd586b7e6e"
}
]
},
"product_downloads": {
"$relation": [
{
"entity_id": "64211361-8759-414b-81c0-afbf24f83aa9"
}
]
},
"_org": "728",
"_created_at": "2022-06-03T15:52:27.512Z",
"_updated_at": "2022-06-03T16:05:15.029Z",
"price_options": {
"$relation": [
{
"entity_id": "9c36c23b-1574-4193-beff-b1b5e1124bc7",
"_tags": []
},
{
"entity_id": "146aa2cc-f267-4d5e-bda4-cbe2669b7741",
"_tags": []
}
]
}
},
"quantity": 4,
"currency": "EUR",
"description": "Battery Module 500amps",
"unit_amount": 50000,
"unit_amount_net": 42017,
"amount_subtotal": 168067,
"amount_total": 200000
},
{
"price_id": "d88a8763-3e3d-4fc7-a7a5-2bc9117148bf",
"product_id": "065d6618-cc59-45f4-8e3a-700edf6813c3",
"pricing_model": "per_unit",
"is_composite_price": false,
"_price": {
"_id": "d88a8763-3e3d-4fc7-a7a5-2bc9117148bf",
"unit_amount": 12055,
"type": "recurring",
"billing_period": "monthly",
"billing_duration_amount": 8,
"billing_duration_unit": "years",
"notice_time_amount": 3,
"notice_time_unit": "months",
"termination_time_amount": 2,
"termination_time_unit": "months",
"renewal_duration_amount": 1,
"renewal_duration_unit": "years",
"active": true,
"sales_tax": "reduced",
"is_tax_inclusive": true,
"description": "Monthly",
"billing_scheme": "per_unit",
"_schema": "price",
"_org": "728",
"_created_at": "2021-11-10T14:40:27.695Z",
"_updated_at": "2021-12-14T18:16:33.248Z",
"_title": "Monthly",
"unit_amount_currency": "EUR",
"unit_amount_decimal": "120.55456634",
"pricing_model": "per_unit",
"is_composite_price": false
},
"_product": {
"_id": "065d6618-cc59-45f4-8e3a-700edf6813c3",
"name": "Smartmeter: Schneider Electric PM5000 LCD Energiemessgerät / 3-phasig",
"code": "1312378123",
"_tags": [
"wallbox",
"review demo",
"1"
],
"categories": [
"Power"
],
"type": "product",
"active": true,
"feature": [
{
"_tags": [],
"feature": "Bis zu 11 kW Ladeleistung (5x schneller laden)"
},
{
"_tags": [],
"feature": "Integrierter MID Zähler für eine kilowattstundengenaue Abrechnung*"
},
{
"_tags": [],
"feature": "Konfigurierbare Ladeleistung"
},
{
"_tags": [],
"feature": "Zugangskontrolle über RFID-Karten"
},
{
"_tags": [],
"feature": "Kommunikation über LAN"
},
{
"_tags": [],
"feature": "New feature"
}
],
"_schema": "product",
"_org": "728",
"_created_at": "2021-11-30T11:05:19.484Z",
"_updated_at": "2022-01-13T09:18:29.944Z",
"_title": "Smartmeter: Schneider Electric PM5000 LCD Energiemessgerät / 3-phasig",
"price_options": {
"$relation": [
{
"entity_id": "5264b089-fc6a-4a91-9a2a-80c673958faa"
},
{
"entity_id": "d88a8763-3e3d-4fc7-a7a5-2bc9117148bf"
}
]
},
"product_images": {
"$relation": [
{
"entity_id": "16729e60-c527-44ef-93c9-c68b6acf1224"
}
]
}
},
"quantity": 1,
"currency": "EUR",
"description": "Monthly",
"unit_amount": 12055,
"unit_amount_net": 11267,
"amount_subtotal": 11267,
"amount_total": 12055,
"taxes": [
{
"rate": "reduced",
"amount": 789
}
]
},
{
"price_id": "e1ddf75a-d0d1-40b4-a07e-56e292867c88",
"product_id": "5b9f05b7-f0f8-49c2-8a8d-0f8f923d6382",
"pricing_model": "per_unit",
"is_composite_price": false,
"_price": {
"_id": "e1ddf75a-d0d1-40b4-a07e-56e292867c88",
"unit_amount": 9900,
"unit_amount_currency": "EUR",
"unit_amount_decimal": "99",
"sales_tax": "standard",
"is_tax_inclusive": true,
"price_display_in_journeys": "show_price",
"type": "recurring",
"billing_period": "yearly",
"billing_duration_unit": "months",
"notice_time_unit": "months",
"termination_time_unit": "months",
"renewal_duration_unit": "months",
"_schema": "price",
"_title": "Yearly payment",
"description": "Yearly payment",
"active": true,
"pricing_model": "per_unit",
"is_composite_price": false,
"_org": "728",
"_created_at": "2022-02-07T22:58:39.884Z",
"_updated_at": "2022-02-07T22:58:39.884Z"
},
"_product": {
"_id": "5b9f05b7-f0f8-49c2-8a8d-0f8f923d6382",
"_schema": "product",
"_title": "Yearly Payment Product",
"name": "Yearly Payment Product",
"type": "product",
"active": true,
"price_options": {
"$relation": [
{
"entity_id": "e1ddf75a-d0d1-40b4-a07e-56e292867c88",
"_tags": []
}
]
},
"_org": "728",
"_created_at": "2022-02-07T22:58:44.162Z",
"_updated_at": "2022-02-08T09:34:08.026Z",
"description": "Hier steht die Produktbeschreibung die sich auf dem Dokument, was generiert wird, gezogen wird."
},
"quantity": 1,
"currency": "EUR",
"description": "Yearly payment",
"unit_amount": 9900,
"unit_amount_net": 8319,
"amount_subtotal": 8319,
"amount_total": 9900,
"taxes": [
{
"rate": "standard",
"amount": 1581
}
]
}
],
"amount_subtotal": 1532191,
"amount_total": 1821955,
"total_details": {
"amount_tax": 289764,
"breakdown": {
"taxes": [
{
"tax": {
"_id": "24641e82-0690-4135-8b43-ef12a9b1c5dc",
"rate": 19,
"_schema": "tax",
"_org": "728",
"_created_at": "2021-09-24T15:06:13.859Z",
"_updated_at": "2022-04-04T17:36:15.273Z",
"_title": "Tax Standard",
"type": "VAT",
"active": true,
"region": "DE",
"description": "Standard"
},
"amount": 287395
}
],
"recurrences": [
{
"type": "one_time",
"amount_subtotal": 1512605,
"amount_subtotal_decimal": "15126.05",
"amount_total": 1800000,
"amount_total_decimal": "18000.00",
"amount_tax": 287395,
"amount_tax_decimal": "2873.95"
},
{
"type": "recurring",
"billing_period": "monthly",
"amount_subtotal": 11267,
"amount_subtotal_decimal": "112.67",
"amount_total": 12055,
"amount_total_decimal": "120.55",
"amount_tax": 789,
"amount_tax_decimal": "7.89"
},
{
"type": "recurring",
"billing_period": "yearly",
"amount_subtotal": 8319,
"amount_subtotal_decimal": "83.19",
"amount_total": 9900,
"amount_total_decimal": "99.00",
"amount_tax": 1581,
"amount_tax_decimal": "15.81"
}
]
}
},
"currency": "EUR",
"payment_method": [
{
"type": "IBAN",
"details": {}
}
],
"billing_contact": {
"$relation": [
{
"entity_id": "1834a54e-b68f-4f7f-a98a-fe16f11bc2a5",
"_tags": []
}
]
},
"billing_first_name": "Joao",
"billing_last_name": "Pinho",
"billing_email": "j.pinho@epilot.cloud",
"billing_company_name": "epilot cloud",
"billing_address": [
{
"_tags": [],
"street": "Im Media Park",
"street_number": "8a",
"postal_code": "52000",
"city": "Cologne",
"country": "DE",
"additional_info": ""
}
],
"delivery_address": [],
"dates": [
{
"_tags": [
"Instalation Date"
],
"dates": "",
"value": "2022-06-30T16:29:00.000Z"
}
],
"_id": "4c7c9562-f8f0-4af0-a3a6-6aebc5571a6e",
"_org": "728",
"_created_at": "2022-06-03T16:29:46.303Z",
"_updated_at": "2022-06-03T16:29:46.303Z"
},
"properties": {
"order_number": {
"type": "string",
"description": "The order number (customer facing)"
},
"cart_id": {
"type": "string",
"description": "The cart id that originated or is associated with the this order"
},
"status": {
"$ref": "#/components/schemas/OrderStatus"
},
"source_type": {
"type": "string",
"description": "Type of source, e.g. journey or manual",
"example": "journey"
},
"source_id": {
"type": "string",
"description": "Identifier for source e.g. journey ID",
"example": "ce99875f-fba9-4fe2-a8f9-afaf52059051"
},
"source": {
"$ref": "#/components/schemas/OrderSource"
},
"metadata": {
"$ref": "#/components/schemas/MetaData"
},
"customer": {
"type": "object",
"description": "A list of customers related with the opportunity",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRelation"
}
}
}
},
"billing_first_name": {
"type": "string",
"description": "The billing contact first name"
},
"billing_last_name": {
"type": "string",
"description": "The billing contact last name"
},
"billing_company_name": {
"type": "string",
"description": "The billing account name"
},
"billing_vat": {
"type": "string",
"description": "The billing account VAT"
},
"billing_email": {
"type": "string",
"description": "The billing email"
},
"billing_phone": {
"type": "string",
"description": "The billing phone"
},
"billing_address": {
"type": "array",
"description": "The billing address",
"items": {
"$ref": "#/components/schemas/Address"
}
},
"currency": {
"description": "The order main currency",
"oneOf": [
{
"$ref": "#/components/schemas/Currency"
}
]
},
"delivery_address": {
"type": "array",
"description": "The delivery address",
"items": {
"$ref": "#/components/schemas/Address"
}
},
"payment_method": {
"type": "array",
"description": "The payment method details for the order",
"items": {
"$ref": "#/components/schemas/PaymentMethod"
}
},
"line_items": {
"$ref": "#/components/schemas/PriceItems"
},
"products": {
"type": "object",
"description": "The product entities referenced from within `line_items`",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRelation"
}
}
}
},
"prices": {
"type": "object",
"description": "The price entities referenced from within `line_items`",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRelation"
}
}
}
},
"coupons": {
"type": "object",
"description": "The coupons referenced from within `line_items`",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRelation"
}
}
}
},
"amount_subtotal": {
"readOnly": true,
"type": "integer",
"description": "Total of all items before (discounts or) taxes are applied."
},
"amount_total": {
"readOnly": true,
"type": "integer",
"description": "Total of all items after (discounts and) taxes are applied."
},
"total_details": {
"$ref": "#/components/schemas/TotalDetails"
},
"_org_id": {
"type": "string",
"description": "Organization Id the order belongs to"
},
"_id": {
"type": "string",
"description": "The order id",
"readOnly": true
},
"_created_at": {
"type": "string",
"description": "The order creation date",
"readOnly": true
},
"_updated_at": {
"type": "string",
"description": "The order last update date",
"readOnly": true
},
"_tags": {
"type": "array",
"description": "An arbitrary set of tags attached to the order",
"items": {
"type": "string"
}
}
}
},
"Price": {
"allOf": [
{
"$ref": "#/components/schemas/PriceConditions"
}
],
"type": "object",
"description": "The price entity schema for simple pricing",
"example": {
"unit_amount": 100000,
"unit_amount_currency": "EUR",
"unit_amount_decimal": "1000",
"sales_tax": "standard",
"is_tax_inclusive": true,
"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,
"_id": "9c36c23b-1574-4193-beff-b1b5e1124bc7",
"_org": "728",
"_created_at": "2022-06-03T16:04:10.369Z",
"_updated_at": "2022-06-03T16:04:10.369Z",
"pricing_model": "per_unit",
"is_composite_price": false
},
"additionalProperties": true,
"readOnly": true,
"properties": {
"active": {
"type": "boolean",
"description": "Whether the price can be used for new purchases."
},
"is_composite_price": {
"description": "The flag for prices that contain price components.",
"type": "boolean",
"enum": [
false
]
},
"is_conditional": {
"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": {
"type": "string",
"description": "Describes how to compute the price per period. Either `per_unit`, `tiered_graduated` or `tiered_volume`.\n- `per_unit` indicates that the fixed amount (specified in unit_amount or unit_amount_decimal) will be charged per unit in quantity\n- `tiered_graduated` indicates that the unit pricing will be computed using tiers attribute. The customer pays the price per unit in every range their purchase rises through.\n- `tiered_volume` indicates that the unit pricing will be computed using tiers attribute. The customer pays the same unit price for all purchased units.\n- `tiered_flatfee` While similar to tiered_volume, tiered flat fee charges for the same price (flat) for the entire range instead using the unit price to multiply the quantity.\n - `dynamic_tariff` indicates that the price is dynamically dependend on the (quarter)-hourly spot market price.\n- `external_getag` indicates that the price is influenced by aquisition fees provided by GetAG.\n",
"enum": [
"per_unit",
"tiered_graduated",
"tiered_volume",
"tiered_flatfee",
"dynamic_tariff",
"external_getag"
]
},
"tiers": {
"description": "Defines an array of tiers. Each tier has an upper bound, an unit amount and a flat fee.\n",
"type": "array",
"items": {
"$ref": "#/components/schemas/PriceTier"
}
},
"description": {
"type": "string",
"description": "A brief description of the price."
},
"long_description": {
"type": "string",
"description": "A detailed description of the price. This is shown on the order document and order table."
},
"sales_tax": {
"deprecated": true,
"description": "The default tax rate applicable to the product.\nThis field is deprecated, use the new `tax` attribute.\n",
"oneOf": [
{
"$ref": "#/components/schemas/SalesTax"
}
]
},
"tax": {
"description": "The default tax rate applied to the price",
"oneOf": [
{
"type": "object",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRelation"
}
}
}
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Tax"
}
}
]
},
"is_tax_inclusive": {
"type": "boolean",
"description": "Specifies whether the price is considered `inclusive` of taxes or not."
},
"type": {
"type": "string",
"description": "One of `one_time` or `recurring` depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.",
"enum": [
"one_time",
"recurring"
]
},
"billing_period": {
"description": "For recurring prices `billing_period` defines the default extent of the recurrence.",
"oneOf": [
{
"$ref": "#/components/schemas/BillingPeriod"
}
]
},
"unit_amount": {
"description": "The unit amount in cents to be charged, represented as a whole integer if possible.",
"type": "number"
},
"unit_amount_decimal": {
"description": "The unit amount in eur to be charged, represented as a decimal string with at most 12 decimal places.",
"type": "string"
},
"unit_amount_currency": {
"description": "Three-letter ISO currency code, in lowercase.",
"oneOf": [
{
"$ref": "#/components/schemas/Currency"
}
]
},
"price_display_in_journeys": {
"description": "Defines the way the price amount is display in epilot journeys.",
"type": "string",
"enum": [
"show_price",
"show_as_starting_price",
"show_as_on_request",
"estimated_price"
]
},
"variable_price": {
"description": "The flag for prices that can be influenced by external variables such as user input.",
"type": "boolean"
},
"unit": {
"description": "The unit of measurement used for display purposes and possibly for calculations when the price is variable.",
"anyOf": [
{
"type": "string",
"description": "built-in units",
"enum": [
"kw",
"kwh",
"m",
"m2",
"l",
"cubic-meter",
"cubic-meter-h",
"ls",
"a",
"kva",
"w",
"wp",
"kwp"
]
},
{
"type": "string",
"description": "user custom unit"
}
]
},
"get_ag": {
"$ref": "#/components/schemas/PriceGetAg"
},
"dynamic_tariff": {
"$ref": "#/components/schemas/PriceDynamicTariff"
},
"_created_at": {
"description": "The price creation date",
"type": "string"
},
"_id": {
"description": "The price id",
"type": "string"
},
"_title": {
"description": "The price autogenerated title",
"type": "string"
},
"_updated_at": {
"description": "The price last update date",
"type": "string"
},
"_org_id": {
"type": "string",
"description": "The organization id the price belongs to"
},
"_tags": {
"type": "array",
"description": "An arbitrary set of tags attached to the price",
"items": {
"type": "string"
}
}
},
"required": [
"pricing_model"
]
},
"BaseCompositePrice": {
"allOf": [
{
"$ref": "#/components/schemas/PriceConditions"
}
],
"type": "object",
"description": "The common properties for a composite price entity, without the price components",
"example": {
"_id": "c2a95ca9-7a50-41a4-a73c-b5fb1a57d40f",
"_schema": "price",
"_title": "My Composite Price",
"description": "My Composite Price",
"_org": "739224",
"_created_at": "2022-02-18T10:10:26.439Z",
"_updated_at": "2022-02-18T11:53:04.191Z",
"active": true,
"is_composite_price": true,
"price_components": {
"$relation": [
{
"entity_id": "comp1-2a95ca9-7a50-41a4-a73c-b5fb1a57d40f",
"_schema": "price",
"_product_id": "target-price-product-id",
"quantity": 1,
"item": {
"_id": "comp1-2a95ca9-7a50-41a4-a73c-b5fb1a57d40f",
"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",
"_schema": "price",
"_title": "Test 1",
"description": "Test 1",
"tax": {
"$relation": [
{
"entity_id": "18bbbc2e-2c37-4f91-924a-07ae60d830e4"
}
]
},
"_org": "739224",
"_created_at": "2022-02-18T10:10:26.439Z",
"_updated_at": "2022-02-18T11:53:04.191Z",
"active": true,
"billing_period": "weekly",
"billing_duration_unit": "months",
"notice_time_unit": "months",
"termination_time_unit": "months",
"renewal_duration_unit": "months",
"is_composite_price": false
}
},
{
"entity_id": "comp2-2a95ca9-7a50-41a4-a73c-b5fb1a57d40f",
"_schema": "price",
"_product_id": "target-price-product-id",
"quantity": 2,
"item": {
"_id": "comp2-2a95ca9-7a50-41a4-a73c-b5fb1a57d40f",
"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",
"_schema": "price",
"_title": "Test 1",
"description": "Test 1",
"tax": {
"$relation": [
{
"entity_id": "18bbbc2e-2c37-4f91-924a-07ae60d830e4"
}
]
},
"_org": "739224",
"_created_at": "2022-02-18T10:10:26.439Z",
"_updated_at": "2022-02-18T11:53:04.191Z",
"active": true,
"billing_period": "weekly",
"billing_duration_unit": "months",
"notice_time_unit": "months",
"termination_time_unit": "months",
"renewal_duration_unit": "months",
"is_composite_price": false
}
}
]
}
},
"additionalProperties": true,
"readOnly": true,
"required": [
"is_composite_price"
],
"properties": {
"active": {
"type": "boolean",
"description": "Whether the price can be used for new purchases."
},
"description": {
"type": "string",
"description": "A brief description of the price."
},
"price_components": {
"description": "A set of [price](/api/pricing#tag/simple_price_schema) components that define the composite price.",
"oneOf": [
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Price"
}
},
{
"type": "object",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PriceComponentRelation"
}
}
}
}
]
},
"unit_amount_currency": {
"description": "Three-letter ISO currency code, in lowercase.",
"oneOf": [
{
"$ref": "#/components/schemas/Currency"
}
]
},
"is_composite_price": {
"description": "The flag for prices that contain price components.",
"type": "boolean",
"enum": [
true
]
},
"is_conditional": {
"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": {
"description": "The price creation date",
"type": "string"
},
"_id": {
"description": "The price id",
"type": "string"
},
"_title": {
"description": "The price autogenerated title",
"type": "string"
},
"_updated_at": {
"description": "The price last update date",
"type": "string"
},
"_org_id": {
"type": "string",
"description": "The organization id the price belongs to"
},
"_tags": {
"type": "array",
"description": "An arbitrary set of tags attached to the composite price",
"items": {
"type": "string"
}
}
}
},
"NonHydratedCompositePrice": {
"allOf": [
{
"$ref": "#/components/schemas/BaseCompositePrice"
}
],
"type": "object",
"description": "The composite price entity",
"properties": {
"price_components": {
"description": "A set of [price](/api/pricing#tag/simple_price_schema) components that define the composite price.",
"type": "object",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PriceComponentRelation"
}
}
}
}
}
},
"HydratedCompositePrice": {
"allOf": [
{
"$ref": "#/components/schemas/BaseCompositePrice"
}
],
"type": "object",
"description": "The composite price entity",
"properties": {
"price_components": {
"description": "A set of [price](/api/pricing#tag/simple_price_schema) components that define the composite price.",
"type": "array",
"items": {
"$ref": "#/components/schemas/Price"
}
}
}
},
"CompositePrice": {
"anyOf": [
{
"$ref": "#/components/schemas/NonHydratedCompositePrice"
},
{
"$ref": "#/components/schemas/HydratedCompositePrice"
}
],
"description": "The composite price entity",
"example": {
"_id": "c2a95ca9-7a50-41a4-a73c-b5fb1a57d40f",
"_schema": "price",
"_title": "My Composite Price",
"description": "My Composite Price",
"_org": "739224",
"_created_at": "2022-02-18T10:10:26.439Z",
"_updated_at": "2022-02-18T11:53:04.191Z",
"active": true,
"is_composite_price": true,
"price_components": {
"$relation": [
{
"entity_id": "comp1-2a95ca9-7a50-41a4-a73c-b5fb1a57d40f",
"_schema": "price",
"_product_id": "target-price-product-id",
"quantity": 1,
"item": {
"_id": "comp1-2a95ca9-7a50-41a4-a73c-b5fb1a57d40f",
"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",
"_schema": "price",
"_title": "Test 1",
"description": "Test 1",
"tax": {
"$relation": [
{
"entity_id": "18bbbc2e-2c37-4f91-924a-07ae60d830e4"
}
]
},
"_org": "739224",
"_created_at": "2022-02-18T10:10:26.439Z",
"_updated_at": "2022-02-18T11:53:04.191Z",
"active": true,
"billing_period": "weekly",
"billing_duration_unit": "months",
"notice_time_unit": "months",
"termination_time_unit": "months",
"renewal_duration_unit": "months",
"is_composite_price": false
}
},
{
"entity_id": "comp2-2a95ca9-7a50-41a4-a73c-b5fb1a57d40f",
"_schema": "price",
"_product_id": "target-price-product-id",
"quantity": 2,
"item": {
"_id": "comp2-2a95ca9-7a50-41a4-a73c-b5fb1a57d40f",
"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",
"_schema": "price",
"_title": "Test 1",
"description": "Test 1",
"tax": {
"$relation": [
{
"entity_id": "18bbbc2e-2c37-4f91-924a-07ae60d830e4"
}
]
},
"_org": "739224",
"_created_at": "2022-02-18T10:10:26.439Z",
"_updated_at": "2022-02-18T11:53:04.191Z",
"active": true,
"billing_period": "weekly",
"billing_duration_unit": "months",
"notice_time_unit": "months",
"termination_time_unit": "months",
"renewal_duration_unit": "months",
"is_composite_price": false
}
}
]
}
}
},
"PriceComponentRelation": {
"type": "object",
"properties": {
"entity_id": {
"description": "The id of the price component",
"type": "string"
},
"quantity": {
"description": "By default, the quantity is set to 1, when greater than 1 this value is used as a multiplicative factor.\nE.g: 16 x Solar Modules - Premium price.\n",
"type": "number"
},
"_tags": {
"type": "array",
"description": "An arbitrary set of tags attached to the composite price - component relation",
"items": {
"type": "string"
}
}
}
},
"MetaData": {
"description": "A set of key-value pairs used to store meta data information about an entity.",
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"description": "Key value pair entry",
"properties": {
"key": {
"type": "string",
"description": "Item key"
},
"value": {
"type": "string",
"description": "Item value"
}
}
}
]
}
},
"PriceInputMappings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PriceInputMapping"
},
"example": [
{
"price_id": "589B011B-F8D9-4F8E-AD71-BACE4B543C0F",
"frequency_unit": "weekly",
"value": 1000.245,
"name": "avg consumption",
"metadata": {
"journey_title": "energy journey",
"step_name": "avg consumption picker"
}
}
]
},
"PriceInputMapping": {
"type": "object",
"properties": {
"price_id": {
"type": "string"
},
"frequency_unit": {
"type": "string",
"enum": [
"weekly",
"monthly",
"every_quarter",
"every_6_months",
"yearly",
"one_time"
]
},
"name": {
"type": "string"
},
"value": {
"type": "number"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
},
"example": {
"price_id": "589B011B-F8D9-4F8E-AD71-BACE4B543C0F",
"frequency_unit": "weekly",
"value": 1000.245,
"name": "avg consumption",
"metadata": {
"journey_title": "energy journey",
"step_name": "avg consumption picker"
}
}
},
"PriceConditions": {
"type": "object",
"properties": {
"billing_duration_amount": {
"description": "The billing period duration",
"type": "number",
"nullable": true
},
"billing_duration_unit": {
"description": "The billing period duration unit",
"type": "string",
"enum": [
"days",
"weeks",
"months",
"years"
],
"nullable": true
},
"notice_time_amount": {
"description": "The notice period duration",
"type": "number",
"nullable": true
},
"notice_time_unit": {
"description": "The notice period duration unit",
"type": "string",
"enum": [
"days",
"weeks",
"months",
"years"
],
"nullable": true
},
"termination_time_amount": {
"description": "The termination period duration",
"type": "number",
"nullable": true
},
"termination_time_unit": {
"description": "The termination period duration unit",
"type": "string",
"enum": [
"days",
"weeks",
"months",
"years"
],
"nullable": true
},
"renewal_duration_amount": {
"description": "The renewal period duration",
"type": "number",
"nullable": true
},
"renewal_duration_unit": {
"description": "The renewal period duration unit",
"type": "string",
"enum": [
"days",
"weeks",
"months",
"years"
],
"nullable": true
}
}
},
"ExternalFeeMetadata": {
"allOf": [
{
"$ref": "#/components/schemas/ComputePriceResult"
}
],
"type": "object",
"properties": {
"inputs": {
"type": "object",
"additionalProperties": true
}
}
},
"ExternalLocationMetadata": {
"allOf": [
{
"$ref": "#/components/schemas/Provider"
}
],
"type": "object",
"properties": {
"inputs": {
"type": "object",
"additionalProperties": true
}
}
},
"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": {
"price_components": {
"type": "array",
"items": {
"anyOf": [
{
"allOf": [
{
"$ref": "#/components/schemas/Price"
},
{
"$ref": "#/components/schemas/ResolvedVariant"
}
]
},
{
"$ref": "#/components/schemas/Price"
}
]
}
}
}
},
"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": [
{
"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"
}
}
}
}
}
]
},
"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": {
"product": {
"$ref": "#/components/schemas/CatalogReferenceMember"
},
"price": {
"$ref": "#/components/schemas/CatalogReferenceMember"
},
"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"
}
},
"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": {
"product": {
"id": "product-pv-2027",
"variant": "var-46045"
},
"price": {
"id": "price-composite-9f2",
"variant": "var-46046"
},
"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"
}
}
},
"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": {
"id": {
"type": "string",
"description": "The entity's id.",
"example": "price-sp26d1yo"
},
"variant": {
"type": "string",
"description": "The variant checkout prices this member from.",
"example": "var-46045"
}
}
},
"SearchProvidersParams": {
"description": "A search providers payload",
"type": "object",
"properties": {
"type": {
"description": "The provider type (power or gas)",
"type": "string",
"enum": [
"power",
"gas"
]
},
"postal_code": {
"description": "The postal code to search for providers",
"type": "string"
},
"city": {
"description": "The city to search for providers",
"type": "string",
"nullable": true
},
"street": {
"description": "The street to search for providers",
"type": "string",
"nullable": true
},
"street_number": {
"description": "The street number to search for providers",
"type": "string",
"nullable": true
}
},
"required": [
"type",
"postal_code"
]
},
"SearchStreetsParams": {
"description": "A search streets payload",
"type": "object",
"properties": {
"postal_code": {
"description": "The postal code to search for providers",
"type": "string"
},
"city": {
"description": "The city to search for providers",
"type": "string",
"nullable": true
}
},
"required": [
"city",
"postal_code"
]
},
"AvailabilityCheckParams": {
"description": "Availability check request payload",
"type": "object",
"properties": {
"products": {
"description": "Products to check availability",
"type": "array",
"items": {
"type": "string",
"description": "Product under availability check"
}
},
"filters": {
"$ref": "#/components/schemas/AvailabilityFilters"
}
},
"required": [
"products",
"filters"
]
},
"AvailabilityResult": {
"description": "The product availability check result payload",
"type": "object",
"properties": {
"available_products": {
"type": "array",
"items": {
"type": "string",
"description": "Available Products"
}
},
"check_results": {
"description": "The check result details",
"type": "array",
"items": {
"type": "object",
"properties": {
"product_id": {
"type": "string"
},
"matching_hits": {
"description": "The number of rules matched",
"type": "number"
},
"matching_error": {
"description": "A set of matching errors when checking availability",
"type": "object",
"additionalProperties": true
}
},
"required": [
"product_id"
]
}
}
},
"required": [
"available_products"
],
"example": {
"available_products": [],
"check_results": [
{
"product_id": "my-product-id-123-1",
"matching_hits": 0
},
{
"product_id": "my-product-id-123-2",
"matching_hits": 0
}
]
}
},
"ValidateAvailabilityFileError": {
"description": "The availability rule error",
"type": "object",
"properties": {
"line": {
"description": "The line number where the error was found",
"type": "number"
},
"msg": {
"description": "The error message",
"type": "string"
},
"data": {
"description": "Data related to the error",
"type": "string"
}
},
"required": [
"msg"
]
},
"IntegrationCredentialsResult": {
"$ref": "#/components/schemas/IntegrationAuthCredentials"
},
"SaveIntegrationCredentialsParams": {
"$ref": "#/components/schemas/IntegrationAuthCredentials"
},
"ComputePriceParamsBase": {
"type": "object",
"properties": {
"postal_code": {
"description": "The postal code to search for providers",
"type": "string"
},
"consumption_type": {
"description": "The consumption type",
"type": "string",
"default": "household",
"enum": [
"household",
"heating_pump",
"night_storage_heating",
"night_storage_heating_common_meter"
]
},
"consumption": {
"description": "(DEPRECATED - use consumption_HT) The yearly consumption to compute the price in kWh",
"type": "number"
},
"consumption_HT": {
"description": "The yearly HT consumption to compute the price in kWh",
"type": "number"
},
"consumption_NT": {
"description": "The yearly NT consumption to compute the price in kWh",
"type": "number"
},
"association_id": {
"description": "The association id",
"type": "string"
},
"billing_period": {
"description": "The billing period (defaults to monthly)",
"type": "string",
"enum": [
"weekly",
"monthly",
"every_quarter",
"every_6_months",
"yearly",
"one_time"
],
"default": "monthly"
},
"reference_date": {
"description": "The optional reference date for the price computation (ISO 8601 format)",
"type": "string",
"format": "date"
},
"city": {
"description": "The city the postal code belongs to. Not used for price computation,\nonly echoed back in `inputs` for display purposes.\n",
"type": "string"
}
},
"required": [
"type",
"postal_code"
]
},
"ComputePriceParamsPower": {
"allOf": [
{
"$ref": "#/components/schemas/ComputePriceParamsBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of energy to compute the price",
"enum": [
"power"
]
},
"meter_type": {
"$ref": "#/components/schemas/PowerMeterType"
}
},
"description": "The compute price payload for power"
}
]
},
"ComputePriceParamsGas": {
"allOf": [
{
"$ref": "#/components/schemas/ComputePriceParamsBase"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "The type of energy to compute the price",
"enum": [
"gas"
]
},
"concession_type": {
"$ref": "#/components/schemas/GasConcessionType"
}
},
"description": "The compute price payload for gas"
}
]
},
"SignatureMeta": {
"type": "object",
"description": "Signature meta data payload",
"properties": {
"signature": {
"description": "The signature hash of the payload",
"type": "string"
},
"timestamp": {
"description": "Timestamp of the signature",
"type": "number"
}
},
"required": [
"timestamp",
"signature"
]
},
"ComputedBasePrice": {
"type": "object",
"description": "The computed price",
"properties": {
"amount": {
"description": "The computed price",
"type": "number"
},
"amount_decimal": {
"description": "The computed price as decimal",
"type": "string"
},
"unit_amount": {
"description": "The computed unit price",
"type": "number"
},
"unit_amount_decimal": {
"description": "The computed unit price as decimal",
"type": "string"
}
},
"required": [
"amount",
"amount_decimal"
]
},
"ComputePriceParams": {
"description": "The compute price payload",
"oneOf": [
{
"$ref": "#/components/schemas/ComputePriceParamsPower"
},
{
"$ref": "#/components/schemas/ComputePriceParamsGas"
}
]
},
"GasConcessionType": {
"description": "The concession type for gas",
"type": "string",
"enum": [
"standard",
"special"
]
},
"PowerMeterType": {
"type": "string",
"description": "The meter type for power",
"enum": [
"classic",
"smart",
"digital"
]
},
"DynamicTariffMode": {
"description": "The mode of the dynamic tariff. `day_ahead_market` uses the Day-Ahead spot market price as base.",
"type": "string",
"enum": [
"day_ahead_market",
"manual"
]
},
"DynamicTariffInterval": {
"description": "The interval of the tariff if a spot market price is used as base.",
"type": "string",
"enum": [
"hourly",
"monthly_average"
]
},
"ComputedPriceBreakdown": {
"type": "object",
"description": "Price breakdown",
"properties": {
"static": {
"$ref": "#/components/schemas/ComputedPriceComponents"
},
"variable": {
"$ref": "#/components/schemas/ComputedPriceComponents"
},
"variable_ht": {
"$ref": "#/components/schemas/ComputedPriceComponents"
},
"variable_nt": {
"$ref": "#/components/schemas/ComputedPriceComponents"
}
}
},
"ComputedPriceComponents": {
"type": "object",
"description": "The computed price components",
"additionalProperties": {
"$ref": "#/components/schemas/ComputedBasePrice"
}
},
"ComputePriceResult": {
"type": "object",
"properties": {
"amount_total": {
"description": "The computed total price",
"type": "number"
},
"amount_total_decimal": {
"description": "The computed total price as decimal",
"type": "string"
},
"amount_static": {
"description": "The computed static price",
"type": "number"
},
"amount_static_decimal": {
"description": "The computed static price as decimal"
},
"amount_variable_ht": {
"description": "The computed variable price, for the day period",
"type": "number"
},
"amount_variable_decimal_ht": {
"description": "The computed variable price, for the day period, as decimal",
"type": "string"
},
"unit_amount_variable_ht": {
"description": "The computed unit price, for the day period",
"type": "number"
},
"unit_amount_variable_decimal_ht": {
"description": "The computed unit price, for the day period, as decimal",
"type": "string"
},
"amount_variable_nt": {
"description": "The computed variable price, for the night period",
"type": "number"
},
"amount_variable_decimal_nt": {
"description": "The computed variable price, for the night period, as decimal",
"type": "string"
},
"unit_amount_variable_nt": {
"description": "The computed unit price, for the night period",
"type": "number"
},
"unit_amount_variable_decimal_nt": {
"description": "The computed unit price, for the night period, as decimal",
"type": "string"
},
"currency": {
"description": "The currency of the computed price (three-letter ISO currency code)",
"oneOf": [
{
"$ref": "#/components/schemas/Currency"
}
]
},
"billing_period": {
"description": "The billing period",
"type": "string",
"enum": [
"weekly",
"monthly",
"every_quarter",
"every_6_months",
"yearly",
"one_time"
]
},
"breakdown": {
"$ref": "#/components/schemas/ComputedPriceBreakdown"
},
"inputs": {
"description": "A snapshot of the parameters this price was computed from, for display purposes\n(e.g. showing \"computed for 3,500 kWh/year\"). Included in the `_meta` signature.\n",
"allOf": [
{
"$ref": "#/components/schemas/ComputePriceInputs"
}
]
},
"_meta": {
"$ref": "#/components/schemas/SignatureMeta"
}
},
"required": [
"amount_total",
"amount_total_decimal",
"currency",
"billing_period",
"breakdown"
]
},
"ComputePriceInputs": {
"type": "object",
"description": "Echo of the request parameters used to compute the price, in the caller-facing shape.",
"properties": {
"type": {
"$ref": "#/components/schemas/ProductCategory"
},
"consumptionHT": {
"type": "number"
},
"consumptionNT": {
"type": "number"
},
"consumptionType": {
"$ref": "#/components/schemas/ConsumptionTypeGetAg"
},
"zipCode": {
"type": "string"
},
"city": {
"type": "string"
},
"providerId": {
"type": "string"
},
"billingPeriod": {
"type": "string",
"enum": [
"weekly",
"monthly",
"every_quarter",
"every_6_months",
"yearly",
"one_time"
]
},
"referenceDate": {
"type": "string",
"format": "date"
}
},
"additionalProperties": true
},
"SpotMarketBiddingZone": {
"description": "The bidding zone for a spot market price.",
"type": "string",
"enum": [
"AT",
"DE-LU"
]
},
"SpotMarketType": {
"description": "The market for a spot market price.",
"type": "string",
"enum": [
"day_ahead"
]
},
"SpotMarketDataFrequency": {
"description": "The aggregation frequency for a series of spot market price data.",
"type": "string",
"enum": [
"PT15M",
"PT1H",
"P1D",
"P1M"
]
},
"HistoricMarketPricesResult": {
"type": "object",
"properties": {
"market": {
"$ref": "#/components/schemas/SpotMarketType"
},
"bidding_zone": {
"$ref": "#/components/schemas/SpotMarketBiddingZone"
},
"prices": {
"type": "array",
"items": {
"$ref": "#/components/schemas/HistoricMarketPriceRecord"
}
}
},
"required": [
"market",
"bidding_zone",
"prices"
]
},
"AverageMarketPriceResult": {
"type": "object",
"properties": {
"market": {
"$ref": "#/components/schemas/SpotMarketType"
},
"bidding_zone": {
"$ref": "#/components/schemas/SpotMarketBiddingZone"
},
"price": {
"$ref": "#/components/schemas/AverageMarketPriceRecord"
},
"_meta": {
"$ref": "#/components/schemas/SignatureMeta"
}
},
"required": [
"market",
"bidding_zone",
"price"
]
},
"AverageMarketPriceRecord": {
"description": "An average market price over a given period in time.",
"allOf": [
{
"$ref": "#/components/schemas/BaseMarketPriceRecord"
},
{
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"description": "An ISO 8601 interval in the format 'start/end'.",
"example": "2025-01-01T00:00:00Z/2025-01-31T23:59:59Z"
}
}
}
]
},
"HistoricMarketPriceRecord": {
"description": "A market price at a given point in time.",
"allOf": [
{
"$ref": "#/components/schemas/BaseMarketPriceRecord"
},
{
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of the price record in UTC."
}
}
}
]
},
"BaseMarketPriceRecord": {
"type": "object",
"properties": {
"unit_amount": {
"type": "number",
"description": "Cost in Cents, e.g. 12.3 for 12,3 Cents = 0.123€.",
"example": 12.3
},
"unit_amount_decimal": {
"type": "string",
"description": "Cost in decimal format, e.g. 0.123€.",
"example": "0.123"
},
"unit_amount_currency": {
"$ref": "#/components/schemas/Currency"
}
},
"required": [
"timestamp",
"unit_amount",
"unit_amount_decimal",
"unit_amount_currency"
]
},
"OAuthCredentials": {
"type": "object",
"properties": {
"client_id": {
"description": "The OAuth client ID",
"type": "string",
"example": "client_id_123"
},
"client_secret": {
"description": "The OAuth client secret",
"type": "string",
"example": "client_secret_456"
},
"authorization_url": {
"description": "The URL to obtain OAuth tokens",
"type": "string",
"example": "https://api.example.com/oauth/token"
},
"grant_type": {
"description": "The OAuth grant type",
"type": "string",
"enum": [
"client_credentials"
],
"default": "client_credentials"
},
"scope": {
"description": "The OAuth scope",
"type": "string",
"example": "read:user write:user"
},
"access_token": {
"description": "The OAuth access token",
"type": "string",
"example": "access_token_789"
},
"access_token_expires_in": {
"description": "The expiration time of the OAuth access token in seconds",
"type": "number",
"example": 3600
},
"access_token_expires_at": {
"description": "The expiration time of the OAuth access token",
"type": "number",
"example": 1715731200
}
},
"required": [
"client_id",
"client_secret",
"authorization_url",
"grant_type"
]
},
"BasicAuthCredentials": {
"type": "object",
"properties": {
"username": {
"description": "The username",
"type": "string",
"example": "username"
},
"password": {
"description": "The password",
"type": "string",
"example": "123456"
}
},
"required": [
"username",
"password"
]
},
"BasicAuthIntegration": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BasicAuthCredentials"
},
{
"type": "object",
"properties": {
"auth_type": {
"type": "string",
"enum": [
"basic_auth"
]
},
"base_url": {
"description": "The base URL",
"type": "string",
"example": "https://api.example.com"
}
}
}
]
},
"OAuthIntegration": {
"type": "object",
"properties": {
"auth_type": {
"type": "string",
"enum": [
"oauth"
]
},
"oauth": {
"$ref": "#/components/schemas/OAuthCredentials"
},
"base_url": {
"description": "The base URL",
"type": "string",
"example": "https://api.example.com"
}
},
"required": [
"auth_type",
"oauth"
]
},
"IntegrationAuthCredentials": {
"description": "The auth credentials for external integrations",
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/BasicAuthIntegration"
},
{
"$ref": "#/components/schemas/OAuthIntegration"
}
]
},
"SearchStreetsResult": {
"description": "The search providers payload",
"type": "array",
"items": {
"$ref": "#/components/schemas/Street"
}
},
"SearchProvidersResult": {
"description": "The search providers payload",
"type": "array",
"items": {
"$ref": "#/components/schemas/Provider"
}
},
"Provider": {
"description": "The provider entity",
"type": "object",
"properties": {
"name": {
"description": "The provider name",
"type": "string"
},
"code": {
"description": "The provider code",
"type": "string"
},
"type": {
"description": "The type of product",
"type": "string",
"enum": [
"gas",
"power"
]
},
"additionalData": {
"$ref": "#/components/schemas/AdditionalProviderData"
},
"_meta": {
"$ref": "#/components/schemas/SignatureMeta"
}
},
"required": [
"name",
"code",
"type",
"additionalData"
]
},
"AdditionalProviderData": {
"description": "Additional data included in the provider entity",
"type": "object",
"properties": {
"gridOperators": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/MarketParticipant"
},
{
"description": "The grid operator"
}
]
}
},
"defaultSuppliers": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/MarketParticipant"
},
{
"description": "The default supplier"
}
]
}
},
"marketAreaDetails": {
"oneOf": [
{
"$ref": "#/components/schemas/GasMarketAreaDetails"
},
{
"$ref": "#/components/schemas/PowerMarketAreaDetails"
}
]
}
},
"required": [
"gridOperators",
"defaultSuppliers",
"marketAreaDetails"
]
},
"MarketParticipant": {
"description": "Market participant data",
"type": "object",
"properties": {
"name": {
"description": "The name of the participant",
"type": "string"
},
"codeNumber": {
"description": "The BDEW/DVGW code number of the participant",
"type": "string"
},
"validFrom": {
"description": "The date from which this data is valid from",
"type": "string",
"format": "date"
},
"validUntil": {
"description": "The date until which this data is valid to",
"type": "string",
"format": "date"
}
},
"required": [
"name",
"codeNumber"
]
},
"GasMarketAreaDetails": {
"description": "Market area details for gas",
"type": "object",
"additionalProperties": false,
"properties": {
"gasType": {
"description": "The type of gas used",
"type": "string",
"enum": [
"L-Gas",
"H-Gas"
]
},
"marketArea": {
"description": "The name of the market area",
"type": "string"
},
"virtualTradingPoint": {
"description": "The vritual trading point identifier",
"type": "string"
}
}
},
"PowerMarketAreaDetails": {
"description": "Market area details for power",
"type": "object",
"additionalProperties": false,
"properties": {
"controlZone": {
"description": "The EIC of the control zone",
"type": "string"
},
"balancingZone": {
"description": "The EIC of the balancing zone",
"type": "string"
}
}
},
"Street": {
"description": "The street entity",
"type": "object",
"properties": {
"street": {
"description": "The street name",
"type": "string"
}
},
"required": [
"street"
]
},
"ValidateAvailabilityFileResult": {
"description": "The availability map file result payload",
"type": "object",
"properties": {
"status": {
"description": "The status of the validation",
"type": "string",
"enum": [
"success",
"error"
]
},
"rules_parsed_count": {
"description": "The number of rules successfully parsed",
"type": "number"
},
"errors": {
"description": "The errors found on the file",
"type": "array",
"items": {
"$ref": "#/components/schemas/ValidateAvailabilityFileError"
}
}
},
"required": [
"status",
"rules_parsed_count",
"errors"
],
"example": {
"status": "success",
"rules_parsed_count": 10,
"errors": []
}
},
"CartDto": {
"description": "A valid cart payload from a client.",
"properties": {
"metadata": {
"$ref": "#/components/schemas/MetaData"
},
"customer": {
"$ref": "#/components/schemas/Customer"
},
"billing_address": {
"$ref": "#/components/schemas/Address"
},
"delivery_address": {
"$ref": "#/components/schemas/Address"
},
"source_type": {
"type": "string",
"description": "type of source, e.g. journey or manual",
"example": "journey"
},
"source_id": {
"type": "string",
"description": "identifier for source e.g. journey ID",
"example": "ce99875f-fba9-4fe2-a8f9-afaf52059051"
},
"source": {
"$ref": "#/components/schemas/OrderSource"
},
"additional_addresses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Address"
}
},
"payment_method": {
"$ref": "#/components/schemas/PaymentMethod"
},
"line_items": {
"$ref": "#/components/schemas/PriceItemsDto"
},
"files": {
"type": "array",
"description": "An array of file IDs, already upload into the File API, that are related with this cart",
"items": {
"type": "string",
"description": "a string representing a file ID as received from the File API"
}
},
"status": {
"$ref": "#/components/schemas/OrderStatus"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"journey_data": {
"type": "object",
"additionalProperties": true
},
"consents": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"line_items"
]
},
"CheckoutCart": {
"type": "object",
"description": "The cart checkout request payload",
"properties": {
"cart": {
"anyOf": [
{
"description": "the cart id",
"type": "string"
},
{
"$ref": "#/components/schemas/CartDto"
}
]
},
"redeemed_promos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RedeemedPromo"
}
},
"mode": {
"$ref": "#/components/schemas/CheckoutMode"
}
}
},
"CheckoutCartResult": {
"type": "object",
"description": "The cart checkout result",
"properties": {
"order": {
"$ref": "#/components/schemas/Order"
}
}
},
"CheckoutMode": {
"type": "string",
"description": "The checkout mode for the cart checkout.",
"enum": [
"create_order",
"create_invoice",
"create_quote"
]
},
"OrderStatus": {
"type": "string",
"enum": [
"draft",
"quote",
"placed",
"cancelled",
"completed"
],
"description": "\n| status | description |\n|-------------|-------|\n| `draft` | Starting state for all orders, at this point we can still edit the order |\n| `quote` | The order is in a quoting phase, bound to an expiration date |\n| `placed` | The order has been paid and can now be fulfilled (shipped, delivered, complete) or canceled |\n| `cancelled` | The order has been cancelled |\n| `completed` | The order is now closed and finalized |\n"
},
"BasePriceItemCommon": {
"description": "Represents the common keys in BasePriceItem and BasePriceItemDto",
"type": "object",
"properties": {
"metadata": {
"$ref": "#/components/schemas/MetaData"
},
"quantity": {
"type": "number",
"description": "The quantity of products being purchased."
},
"product_id": {
"type": "string",
"description": "The id of the product."
},
"price_id": {
"type": "string",
"description": "The id of the price."
},
"description": {
"type": "string",
"description": "An arbitrary string attached to the price item. Often useful for displaying to users. Defaults to product name."
},
"product_description": {
"type": "string",
"description": "The description for the product."
},
"product_name": {
"type": "string",
"description": "The name for the product."
},
"price_mappings": {
"$ref": "#/components/schemas/PriceInputMappings"
},
"is_tax_inclusive": {
"type": "boolean",
"description": "Specifies whether the price is considered `inclusive` of taxes or not."
},
"_product": {
"description": "The snapshot of the product.",
"allOf": [
{
"$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"
}
]
}
}
},
"PriceItemDtoUnion": {
"anyOf": [
{
"$ref": "#/components/schemas/PriceItemDto"
},
{
"$ref": "#/components/schemas/CompositePriceItemDto"
}
],
"discriminator": {
"propertyName": "is_composite_price",
"mapping": {
"false": "#/components/schemas/PriceItemDto",
"true": "#/components/schemas/CompositePriceItemDto"
}
}
},
"PriceItemsDto": {
"description": "A valid set of product prices, quantities, (discounts) and taxes from a client.",
"type": "array",
"items": {
"$ref": "#/components/schemas/PriceItemDtoUnion"
}
},
"BasePriceItemDto": {
"description": "Represents a valid base price item from a client.",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BasePriceItemCommon"
}
],
"properties": {
"external_fees_mappings": {
"$ref": "#/components/schemas/ExternalFeeMappings"
},
"external_fees_metadata": {
"$ref": "#/components/schemas/ExternalFeeMetadata"
},
"external_location_metadata": {
"$ref": "#/components/schemas/ExternalLocationMetadata"
},
"external_price_metadata": {
"$ref": "#/components/schemas/ExternalPriceMetadata"
},
"_immutable_pricing_details": {
"$ref": "#/components/schemas/PricingDetails"
},
"coupon_ids": {
"type": "array",
"description": "The ids of the coupons applicable to the price item",
"items": {
"type": "string",
"description": "The id of the coupon"
}
},
"taxes": {
"type": "array",
"description": "The taxes applied to the price item.",
"readOnly": true,
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TaxAmountDto"
}
]
}
},
"recurrences": {
"type": "array",
"description": "The taxes applied to the price item.",
"readOnly": true,
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/RecurrenceAmountDto"
}
]
}
},
"_coupons": {
"type": "array",
"description": "The coupons applicable to the price item",
"readOnly": true,
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/CouponItem"
}
]
}
}
}
},
"PriceItemDto": {
"description": "Represents a price input to the pricing library.",
"allOf": [
{
"$ref": "#/components/schemas/BasePriceItemDto"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "One of `one_time` or `recurring` depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.",
"enum": [
"one_time",
"recurring"
]
},
"billing_period": {
"description": "The price billing period.",
"oneOf": [
{
"$ref": "#/components/schemas/BillingPeriod"
}
]
},
"unit_amount": {
"type": "integer",
"description": "The unit amount value"
},
"unit_amount_gross": {
"type": "integer",
"description": "The unit gross amount value."
},
"unit_amount_currency": {
"$ref": "#/components/schemas/Currency"
},
"unit_amount_decimal": {
"description": "The unit amount in eur to be charged, represented as a decimal string with at most 12 decimal places.",
"type": "string"
},
"is_composite_price": {
"description": "The flag for prices that contain price components.",
"type": "boolean",
"enum": [
false
]
},
"pricing_model": {
"type": "string",
"description": "Describes how to compute the price per period. Either `per_unit`, `tiered_graduated` or `tiered_volume`.\n- `per_unit` indicates that the fixed amount (specified in unit_amount or unit_amount_decimal) will be charged per unit in quantity\n- `tiered_graduated` indicates that the unit pricing will be computed using tiers attribute. The customer pays the price per unit in every range their purchase rises through.\n- `tiered_volume` indicates that the unit pricing will be computed using tiers attribute. The customer pays the same unit price for all purchased units.\n- `tiered_flatfee` indicates that the unit pricing will be computed using tiers attribute. The customer pays the same unit price for all purchased units.\n- `dynamic_tariff` indicates that the price is dynamically dependend on the (quarter)-hourly spot market price.\n- `external_getag` indicates that the price is influenced by aquisition fees provided by GetAG.\n",
"enum": [
"per_unit",
"tiered_graduated",
"tiered_volume",
"tiered_flatfee",
"dynamic_tariff",
"external_getag"
]
},
"_price": {
"description": "The snapshot of the price linked to the price item.",
"allOf": [
{
"$ref": "#/components/schemas/Price"
}
]
}
}
}
]
},
"CompositePriceItemDto": {
"description": "Represents a composite price input to the pricing library.",
"allOf": [
{
"$ref": "#/components/schemas/BasePriceItemDto"
},
{
"type": "object",
"required": [
"is_composite_price"
],
"properties": {
"is_composite_price": {
"description": "The flag for prices that contain price components.",
"type": "boolean",
"enum": [
true
]
},
"item_components": {
"type": "array",
"description": "Contains price item configurations, per price component, when the main price item is a [composite price](/api/pricing#tag/dynamic_price_schema).",
"items": {
"$ref": "#/components/schemas/PriceItemDto"
}
},
"selected_price_component_ids": {
"type": "array",
"description": "The ids of the price components that should be selected for the price calculation.",
"items": {
"type": "string",
"description": "The id of the price component"
}
},
"price_component_coupon_ids": {
"type": "object",
"description": "The map of coupon ids applicable to the price components",
"additionalProperties": {
"type": "array",
"items": {
"type": "string",
"description": "The id of the coupon"
}
}
},
"_price": {
"$ref": "#/components/schemas/CompositePrice"
}
}
}
]
},
"TaxAmountDto": {
"type": "object",
"description": "A valid tax rate from a client.",
"properties": {
"rate": {
"type": "string",
"deprecated": true,
"description": "The deprecated tax rate applied.\nThis field has been deprecated in favor of the new Tax Management. You should use the new tax fields pointing to a proper tax entity.\n"
},
"tax": {
"oneOf": [
{
"$ref": "#/components/schemas/Tax"
},
{
"$ref": "#/components/schemas/TaxItem"
}
]
}
}
},
"OrderSource": {
"type": "object",
"description": "The order generation source",
"properties": {
"http": {
"type": "string",
"description": "Link path for the source",
"example": "/app/v2/journey-builder/editor/db7f6940-994b-11ec-a46d-9f1824ff2939"
},
"title": {
"type": "string",
"description": "Title for the source",
"example": "Journey: PH Journey"
}
}
},
"OpportunitySource": {
"type": "object",
"description": "The opportunity generation source",
"properties": {
"http": {
"type": "string",
"description": "Link path for the source",
"example": "/app/v2/journey-builder/editor/db7f6940-994b-11ec-a46d-9f1824ff2939"
},
"title": {
"type": "string",
"description": "Title for the source",
"example": "Journey: PH Journey"
}
}
},
"RecurrenceAmountDto": {
"type": "object",
"description": "An amount associated with a specific recurrence.",
"allOf": [
{
"$ref": "#/components/schemas/Amounts"
}
],
"properties": {
"type": {
"type": "string",
"description": "The price type."
},
"billing_period": {
"description": "The price billing period.",
"oneOf": [
{
"$ref": "#/components/schemas/BillingPeriod"
}
]
},
"unit_amount_gross": {
"type": "integer",
"description": "The unit gross amount value."
},
"unit_amount_net": {
"type": "integer",
"description": "The unit net amount value."
},
"amount_tax": {
"type": "integer",
"description": "Total of all items taxes, with same recurrence."
}
},
"required": [
"amount_subtotal",
"amount_total",
"amount_subtotal_decimal",
"amount_total_decimal"
]
},
"Currency": {
"type": "string",
"description": "Three-letter ISO currency code, in lowercase. Must be a supported currency.\nISO 4217 CURRENCY CODES as specified in the documentation: https://www.iso.org/iso-4217-currency-codes.html\n",
"example": "EUR"
},
"OrderRelation": {
"type": "object",
"description": "An order relation reference",
"properties": {
"entity_id": {
"type": "string",
"description": "The relation order id"
},
"_tags": {
"type": "array",
"items": {
"type": "string",
"description": "The tags array associated with the relation"
}
}
}
},
"OrderPayload": {
"type": "object",
"description": "Order Entity Payload",
"additionalProperties": true,
"properties": {
"status": {
"$ref": "#/components/schemas/OrderStatus"
},
"line_items": {
"$ref": "#/components/schemas/PriceItemsDto"
},
"source_type": {
"type": "string",
"description": "type of source, e.g. journey or manual",
"example": "journey"
},
"currency": {
"$ref": "#/components/schemas/Currency"
},
"contact": {
"readOnly": true,
"type": "string",
"description": "The id of an existing contact."
},
"billing_first_name": {
"type": "string"
},
"billing_last_name": {
"type": "string"
},
"billing_company_name": {
"type": "string"
},
"billing_vat": {
"type": "string"
},
"billing_email": {
"type": "string"
},
"billing_phone": {
"type": "string"
},
"billing_address": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Address"
}
},
"delivery_address": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Address"
}
},
"payment_method": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PaymentMethod"
}
},
"redeemed_promos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RedeemedPromo"
}
},
"_tags": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"PriceItems": {
"description": "Tracks a set of product prices, quantities, (discounts) and taxes.",
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/PriceItem"
},
{
"$ref": "#/components/schemas/CompositePriceItem"
}
]
}
},
"CompositePriceItem": {
"allOf": [
{
"$ref": "#/components/schemas/BasePriceItem"
}
],
"description": "Represents a composite price input to the pricing library.",
"type": "object",
"required": [
"is_composite_price"
],
"properties": {
"is_composite_price": {
"description": "The flag for prices that contain price components.",
"type": "boolean",
"enum": [
true
]
},
"item_components": {
"type": "array",
"description": "Contains price item configurations, per price component, when the main price item is a [composite price](/api/pricing#tag/dynamic_price_schema).",
"items": {
"$ref": "#/components/schemas/PriceItem"
}
},
"total_details": {
"$ref": "#/components/schemas/TotalDetails"
},
"_price": {
"description": "The price snapshot data.",
"anyOf": [
{
"$ref": "#/components/schemas/CompositePrice"
}
]
},
"_coupons": {
"type": "array",
"description": "The coupons applicable to the composite price item + related (cashback) amounts",
"readOnly": true,
"items": {
"allOf": [
{
"$ref": "#/components/schemas/CouponItem"
},
{
"$ref": "#/components/schemas/CashbackAmounts"
}
]
}
}
}
},
"BasePriceItem": {
"description": "Represents a price item",
"type": "object",
"example": {
"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": [
{
"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"
}
}
],
"unit_amount": 10000,
"unit_amount_net": 10000,
"pricing_model": "per_unit",
"_price": {
"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"
}
]
},
"_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
"_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"
}
},
"allOf": [
{
"$ref": "#/components/schemas/Amounts"
},
{
"$ref": "#/components/schemas/BasePriceItemCommon"
}
],
"properties": {
"_id": {
"type": "string",
"description": "price item id",
"readOnly": true
},
"unit_amount": {
"type": "integer",
"description": "The unit amount value",
"readOnly": true
},
"unit_amount_decimal": {
"description": "The unit amount in eur to be charged, represented as a decimal string with at most 12 decimal places.",
"type": "string",
"readOnly": true
},
"before_discount_unit_amount": {
"type": "integer",
"description": "The unit amount before any discount is applied",
"readOnly": true
},
"before_discount_unit_amount_decimal": {
"type": "string",
"description": "The unit amount before any discount is applied, represented as a decimal string with at most 12 decimal places.",
"readOnly": true
},
"before_discount_unit_amount_gross": {
"type": "integer",
"description": "The unit gross amount before any discount is applied",
"readOnly": true
},
"before_discount_unit_amount_gross_decimal": {
"type": "string",
"description": "The unit gross amount before any discount is applied, represented as a decimal string with at most 12 decimal places.",
"readOnly": true
},
"before_discount_unit_amount_net": {
"type": "integer",
"description": "The unit net amount before any discount is applied",
"readOnly": true
},
"before_discount_unit_amount_net_decimal": {
"type": "string",
"description": "The unit net amount before any discount is applied, represented as a decimal string with at most 12 decimal places.",
"readOnly": true
},
"unit_discount_amount": {
"type": "integer",
"description": "The discount amount applied for each unit",
"readOnly": true
},
"unit_discount_amount_decimal": {
"type": "string",
"description": "The discount amount applied for each unit represented as a decimal string",
"readOnly": true
},
"unit_amount_gross": {
"type": "integer",
"description": "The unit gross amount value.",
"readOnly": true
},
"unit_amount_gross_decimal": {
"type": "string",
"description": "The unit gross amount value.",
"readOnly": true
},
"unit_amount_net": {
"type": "integer",
"description": "Net unit amount without taxes or discounts.",
"readOnly": true
},
"unit_amount_net_decimal": {
"type": "string",
"description": "Net unit amount without taxes or discounts.",
"readOnly": true
},
"unit_discount_amount_net": {
"type": "integer",
"description": "The net discount amount applied for each unit",
"readOnly": true
},
"unit_discount_amount_net_decimal": {
"type": "string",
"description": "The net discount amount applied for each unit represented as a decimal string",
"readOnly": true
},
"tax_discount_amount": {
"type": "integer",
"description": "The discount amount applied to the tax",
"readOnly": true
},
"tax_discount_amount_decimal": {
"type": "string",
"description": "The discount amount applied to the tax represented as a decimal string",
"readOnly": true
},
"discount_amount_net": {
"type": "integer",
"description": "The net discount amount applied",
"readOnly": true
},
"discount_amount_net_decimal": {
"type": "string",
"description": "The net discount amount applied represented as a decimal string",
"readOnly": true
},
"amount_tax": {
"type": "integer",
"description": "Total tax amount for this line item."
},
"before_discount_tax_amount": {
"type": "integer",
"description": "The tax amount before any discount is applied",
"readOnly": true
},
"before_discount_tax_amount_decimal": {
"type": "string",
"description": "The tax amount before any discount is applied represented as a decimal string",
"readOnly": true
},
"currency": {
"$ref": "#/components/schemas/Currency"
},
"taxes": {
"type": "array",
"description": "The taxes applied to the price item.",
"readOnly": true,
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TaxAmount"
}
]
}
},
"recurrences": {
"type": "array",
"description": "The sum of amounts of the price items by recurrence.",
"readOnly": true,
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/RecurrenceAmount"
}
]
}
},
"_coupons": {
"type": "array",
"description": "The coupons applicable to the price item",
"readOnly": true,
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/CouponItem"
}
]
}
},
"on_request_approved": {
"type": "boolean",
"description": "When set to true on a `_price` displayed as OnRequest (`show_as_on_request: 'on_request'`) this flag means the price has been approved and can now be displayed to the customer. This flag is only valid for prices shown as 'on_request'."
}
}
},
"CashbackAmounts": {
"type": "object",
"properties": {
"cashback_amount": {
"type": "integer",
"description": "The cashback amount.",
"readOnly": true
},
"cashback_amount_decimal": {
"type": "string",
"description": "The cashback amount as a string with all the decimal places.",
"readOnly": true
},
"cashback_period": {
"$ref": "#/components/schemas/CashbackPeriod"
},
"after_cashback_amount_total": {
"type": "integer",
"description": "Total amount after cashback is applied.",
"readOnly": true
},
"after_cashback_amount_total_decimal": {
"type": "string",
"description": "Total amount after cashback is applied as a string with all the decimal places.",
"readOnly": true
}
}
},
"DiscountAmounts": {
"type": "object",
"properties": {
"discount_amount": {
"type": "integer",
"description": "The discount amount.",
"readOnly": true
},
"discount_amount_decimal": {
"type": "string",
"description": "The discount amount as a string with all the decimal places.",
"readOnly": true
},
"discount_percentage": {
"type": "integer",
"description": "The discount percentage, if the applied coupon had a percentage type.",
"readOnly": true
},
"before_discount_amount_total": {
"type": "integer",
"description": "Total amount before discount is applied.",
"readOnly": true
},
"before_discount_amount_total_decimal": {
"type": "string",
"description": "Total amount before discount is applied as a string with all the decimal places.",
"readOnly": true
},
"before_discount_amount_subtotal": {
"type": "integer",
"description": "Total amount before discount is applied, excluding taxes.",
"readOnly": true
},
"before_discount_amount_subtotal_decimal": {
"type": "string",
"description": "Total amount before discount is applied, excluding taxes, as a string with all the decimal places.",
"readOnly": true
}
}
},
"PriceAmounts": {
"type": "object",
"properties": {
"amount_subtotal": {
"type": "integer",
"description": "Total of all items before (discounts or) taxes are applied."
},
"amount_subtotal_decimal": {
"type": "string",
"description": "Total of all items before (discounts or) taxes are applied, as a string with all the decimal places."
},
"amount_total": {
"type": "integer",
"description": "Total of all items after (discounts and) taxes are applied."
},
"amount_total_decimal": {
"type": "string",
"description": "Total of all items after (discounts and) taxes are applied, as a string with all the decimal places."
}
}
},
"Amounts": {
"allOf": [
{
"$ref": "#/components/schemas/PriceAmounts"
},
{
"$ref": "#/components/schemas/CashbackAmounts"
},
{
"$ref": "#/components/schemas/DiscountAmounts"
}
]
},
"PriceItem": {
"allOf": [
{
"$ref": "#/components/schemas/BasePriceItem"
}
],
"description": "Represents a price item",
"type": "object",
"example": {
"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": [
{
"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"
}
}
],
"unit_amount": 10000,
"unit_amount_net": 10000,
"pricing_model": "per_unit",
"_price": {
"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"
}
]
},
"_id": "7e24ff5d-d580-4136-a32f-19191eed039a",
"_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"
}
},
"properties": {
"type": {
"type": "string",
"description": "One of `one_time` or `recurring` depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.",
"enum": [
"one_time",
"recurring"
]
},
"is_composite_price": {
"description": "The flag for prices that contain price components.",
"type": "boolean",
"enum": [
false
]
},
"billing_period": {
"description": "The price billing period.",
"oneOf": [
{
"$ref": "#/components/schemas/BillingPeriod"
}
]
},
"pricing_model": {
"$ref": "#/components/schemas/PricingModel"
},
"tiers_details": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TierDetails"
}
},
"get_ag": {
"$ref": "#/components/schemas/PriceGetAg"
},
"dynamic_tariff": {
"$ref": "#/components/schemas/PriceDynamicTariff"
},
"_price": {
"description": "The price snapshot data.",
"anyOf": [
{
"$ref": "#/components/schemas/Price"
}
]
}
},
"required": [
"pricing_model"
]
},
"TaxAmount": {
"type": "object",
"description": "A tax amount associated with a specific tax rate.",
"readOnly": true,
"properties": {
"amount": {
"type": "integer",
"description": "The tax amount."
},
"rate": {
"type": "string",
"description": "The tax rate applied. With the release of the tax management feature this field is being deprecated in favor of the tax field.",
"deprecated": true
},
"rateValue": {
"type": "number",
"description": "The tax rate value applied (represented as an integer percentage, e.g, 19 or 7).\nWith the release of the tax management feature this field is being deprecated in favor of the tax field.\n",
"example": 19,
"deprecated": true
},
"tax": {
"description": "The tax applied.",
"oneOf": [
{
"$ref": "#/components/schemas/Tax"
},
{
"$ref": "#/components/schemas/TaxItem"
}
]
}
}
},
"TaxAmountBreakdown": {
"type": "object",
"description": "A tax amount associated with a specific tax rate.",
"readOnly": true,
"properties": {
"amount": {
"type": "integer",
"description": "The tax amount."
},
"rate": {
"type": "string",
"description": "The tax rate applied. With the release of the tax manager feature this field is being deprecated in favor of the tax field.",
"deprecated": true
},
"rateValue": {
"type": "number",
"description": "The tax rate value applied. With the release of the tax manager feature this field is being deprecated in favor of the tax field.",
"deprecated": true
},
"tax": {
"$ref": "#/components/schemas/TaxBreakdownInfo"
}
}
},
"RecurrenceAmount": {
"type": "object",
"description": "An amount associated with a specific recurrence.",
"readOnly": true,
"allOf": [
{
"$ref": "#/components/schemas/Amounts"
}
],
"properties": {
"type": {
"type": "string",
"description": "The price type."
},
"billing_period": {
"description": "The price billing period.",
"oneOf": [
{
"$ref": "#/components/schemas/BillingPeriod"
}
]
},
"unit_amount_gross": {
"type": "integer",
"description": "The unit gross amount value."
},
"unit_amount_net": {
"type": "integer",
"description": "The unit net amount value."
},
"amount_tax": {
"type": "integer",
"description": "Total of all items taxes, with same recurrence."
},
"amount_tax_decimal": {
"type": "string",
"description": "Total of all items taxes, with same recurrence, as a string with all the decimal places."
},
"currency": {
"$ref": "#/components/schemas/Currency"
}
},
"required": [
"amount_subtotal",
"amount_total",
"amount_subtotal_decimal",
"amount_total_decimal"
]
},
"CashbackAmount": {
"type": "object",
"description": "A detail associated with a specific cashback.",
"properties": {
"cashback_name": {
"type": "string",
"description": "The name of the cashback."
},
"cashback_period": {
"$ref": "#/components/schemas/CashbackPeriod"
},
"amount_total": {
"type": "integer",
"description": "The sum of all cashbacks for a specific cashback period"
}
},
"required": [
"cashback_period",
"amount_total"
]
},
"RecurrenceAmountWithTax": {
"type": "object",
"description": "An amount associated with a specific recurrence.",
"properties": {
"type": {
"type": "string",
"description": "The price type."
},
"billing_period": {
"description": "The price billing period.",
"oneOf": [
{
"$ref": "#/components/schemas/BillingPeriod"
}
]
},
"amount_total": {
"type": "integer",
"description": "Total amount of items with same recurrence."
},
"amount_subtotal": {
"type": "integer",
"description": "Total amount of items with same recurrence, excluding taxes."
},
"amount_tax": {
"type": "integer",
"description": "Total tax amount of items with same recurrence."
},
"tax": {
"$ref": "#/components/schemas/TaxAmountBreakdown"
}
},
"required": [
"amount_subtotal",
"amount_total"
]
},
"TotalDetails": {
"type": "object",
"description": "The total details with tax (and discount) aggregated totals.",
"readOnly": true,
"properties": {
"amount_shipping": {
"type": "integer",
"description": "This is the sum of all the price item shipping amounts."
},
"amount_tax": {
"type": "integer",
"description": "This is the sum of all the price item tax amounts."
},
"breakdown": {
"type": "object",
"description": "Breakdown of individual tax (and discount) amounts that add up to the totals.",
"properties": {
"taxes": {
"type": "array",
"description": "The aggregated price items tax amount per rate.",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TaxAmountBreakdown"
}
]
}
},
"recurrences": {
"type": "array",
"description": "The aggregated price items tax amount per rate.",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/RecurrenceAmount"
}
]
}
},
"cashbacks": {
"type": "array",
"description": "The list of cashbacks applied.",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/CashbackAmount"
}
]
}
},
"recurrencesByTax": {
"type": "array",
"description": "The aggregated price items recurrences by tax rate",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/RecurrenceAmountWithTax"
}
]
}
}
}
}
}
},
"PricingDetails": {
"type": "object",
"description": "The result from the calculation of a set of price items.",
"properties": {
"items": {
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/PriceItem"
},
{
"$ref": "#/components/schemas/CompositePriceItem"
}
]
}
},
"amount_subtotal": {
"type": "integer",
"description": "Total of all items before (discounts or) taxes are applied."
},
"amount_total": {
"type": "integer",
"description": "Total of all items after (discounts and) taxes are applied."
},
"unit_amount_gross": {
"type": "integer",
"description": "The unit gross amount value."
},
"unit_amount_net": {
"type": "integer",
"description": "The unit net amount value."
},
"amount_tax": {
"type": "integer",
"description": "This is the sum of all the price item tax amounts."
},
"total_details": {
"$ref": "#/components/schemas/TotalDetails"
},
"currency": {
"$ref": "#/components/schemas/Currency"
},
"redeemed_promos": {
"type": "array",
"items": {
"$ref": "#/components/schemas/RedeemedPromo"
}
}
}
},
"PromoCodeValidationResponse": {
"type": "object",
"description": "The result from the validation of a set of promo codes.",
"properties": {
"matched_coupons": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CouponWithoutPromoCodes"
}
}
}
},
"PricingDetailsResponse": {
"type": "object",
"description": "The result from the calculation of a set of price items.",
"allOf": [
{
"$ref": "#/components/schemas/PricingDetails"
}
]
},
"BillingPeriod": {
"type": "string",
"enum": [
"weekly",
"monthly",
"every_quarter",
"every_6_months",
"yearly"
]
},
"CashbackPeriod": {
"type": "string",
"description": "The cashback period, for now it's limited to either 0 months or 12 months",
"enum": [
"0",
"12"
],
"nullable": true
},
"SalesTax": {
"type": "string",
"enum": [
"nontaxable",
"reduced",
"standard"
]
},
"AvailabilityLocation": {
"type": "object",
"properties": {
"street": {
"type": "string",
"description": "The first line of the address. Typically the street address or PO Box number."
},
"street_number": {
"type": "string",
"description": "The second line of the address. Typically the number of the apartment, suite, or unit."
},
"postal_code": {
"type": "string",
"description": "The postal code for the address."
},
"city": {
"type": "string",
"description": "The name of the city, district, village, or town."
},
"country": {
"type": "string",
"description": "The name of the country."
}
}
},
"AvailabilityFilters": {
"description": "Availability filters dimensions",
"type": "object",
"properties": {
"location": {
"$ref": "#/components/schemas/AvailabilityLocation"
},
"available_date": {
"type": "string",
"format": "date",
"example": "2017-07-21",
"description": "A value to be matched against the availability window (start & end date)"
}
},
"required": [
"location"
]
},
"Address": {
"type": "object",
"additionalProperties": true,
"properties": {
"_tags": {
"type": "array",
"items": {
"type": "string"
},
"example": [
"billing"
]
},
"street": {
"type": "string",
"description": "The first line of the address. Typically the street address or PO Box number.",
"nullable": true
},
"street_number": {
"type": "string",
"description": "The second line of the address. Typically the number of the apartment, suite, or unit.",
"nullable": true
},
"postal_code": {
"type": "string",
"description": "The postal code for the address.",
"nullable": true
},
"city": {
"type": "string",
"description": "The name of the city, district, village, or town.",
"nullable": true
},
"country": {
"type": "string",
"description": "The two-letter code for the country of the address.",
"nullable": true
},
"additional_info": {
"type": "string",
"description": "An additional description for the address",
"nullable": true
},
"company_name": {
"type": "string",
"description": "the company name, usually used as extra delivery instructions",
"nullable": true
},
"first_name": {
"type": "string",
"description": "the first name of the recipient, usually used as extra delivery instructions",
"nullable": true
},
"last_name": {
"type": "string",
"description": "the last name of the recipient, usually used as extra delivery instructions",
"nullable": true
},
"salutation": {
"type": "string",
"description": "the salutation of the recipient, usually used as extra delivery instructions",
"nullable": true
},
"title": {
"type": "string",
"description": "the title of the recipient, usually used as extra delivery instructions",
"nullable": true
}
}
},
"PaymentMethod": {
"type": "object",
"description": "A PaymentMethod represent your customer's payment instruments.\n",
"properties": {
"type": {
"type": "string",
"description": "The type of the PaymentMethod."
},
"details": {
"type": "object",
"description": "Contains relevant data associated with the payment method type.",
"additionalProperties": true
}
}
},
"Customer": {
"type": "object",
"properties": {
"first_name": {
"type": "string"
},
"last_name": {
"type": "string"
},
"company_name": {
"type": "string"
},
"vat_id": {
"type": "string"
},
"email": {
"type": "string",
"description": "A valid email identifying the customer."
},
"phone": {
"type": "string"
}
}
},
"File": {
"type": "object",
"additionalProperties": true,
"properties": {
"_id": {
"type": "string"
},
"filename": {
"type": "string"
},
"mime_type": {
"type": "string"
},
"versions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true,
"properties": {
"s3ref": {
"type": "object",
"properties": {
"bucket": {
"type": "string"
},
"key": {
"type": "string"
}
},
"required": [
"bucket",
"key"
]
}
},
"required": [
"s3ref"
]
}
},
"_schema": {
"type": "string"
},
"_org": {
"type": "string"
},
"_created_at": {
"type": "string",
"format": "date-time"
},
"_updated_at": {
"type": "string",
"format": "date-time"
},
"_title": {
"type": "string"
},
"$relation": {
"$ref": "#/components/schemas/EntityRelation"
}
},
"required": [
"versions",
"_id",
"_schema",
"_created_at",
"_updated_at",
"_org",
"mime_type",
"filename"
]
},
"EntityId": {
"type": "string",
"format": "uuid"
},
"EntityItem": {
"type": "object",
"properties": {
"_id": {
"$ref": "#/components/schemas/EntityId"
},
"_title": {
"type": "string",
"description": "Title of entity"
},
"_org": {
"type": "string",
"description": "Organization Id the entity belongs to"
},
"_schema": {
"type": "string"
},
"_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"_created_at": {
"type": "string",
"format": "date-time"
},
"_updated_at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"_id",
"_title",
"_org",
"_schema",
"_created_at",
"_updated_at"
],
"example": {
"_id": "73f857a4-0fbc-4aa6-983f-87c0d6d410a6",
"_title": "Cool box",
"_org": "728",
"_schema": "order",
"_created_at": "2022-06-03T16:04:10.000Z",
"_updated_at": "2022-06-03T16:04:10.000Z",
"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": [
{
"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"
}
}
],
"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"
}
}
},
"EntityRelation": {
"type": "object",
"additionalProperties": true,
"properties": {
"entity_id": {
"type": "string"
},
"_tags": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"Tax": {
"type": "object",
"description": "the tax configuration",
"additionalProperties": true,
"required": [
"type",
"rate",
"_id",
"_title",
"_org",
"_schema",
"_created_at",
"_updated_at"
],
"properties": {
"_id": {
"$ref": "#/components/schemas/EntityId"
},
"_title": {
"type": "string",
"description": "Title of entity"
},
"_org": {
"type": "string",
"description": "Organization Id the entity belongs to"
},
"_schema": {
"type": "string"
},
"_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"_created_at": {
"type": "string",
"format": "date-time"
},
"_updated_at": {
"type": "string",
"format": "date-time"
},
"type": {
"type": "string",
"enum": [
"VAT",
"GST",
"Custom"
]
},
"description": {
"type": "string"
},
"rate": {
"type": "number",
"nullable": true
},
"active": {
"type": "boolean"
},
"region": {
"type": "string"
},
"region_label": {
"type": "string"
}
},
"example": {
"rate": 19,
"_title": "Tax Standard",
"_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "VAT",
"description": "Tax description",
"active": true,
"region": "DE",
"region_label": "Germany",
"_org": "123",
"_schema": "tax",
"_tags": [
"example",
"mock"
],
"_created_at": "2021-02-09T12:41:43.662Z",
"_updated_at": "2021-02-09T12:41:43.662Z"
}
},
"TaxItem": {
"type": "object",
"description": "A minimal, ad-hoc tax rate for line items with no backing tax entity\nin the catalog (e.g. a fully custom/composite price component built\nby a client with no product/price reference to resolve tax from).\nMirrors how PriceItem relates to Price: unlike Tax, this has no\nentity identity — it isn't persisted and can't be looked up by _id,\nso it can't be shared/reused across price items the way a catalog\nTax can.\n",
"additionalProperties": false,
"required": [
"type",
"rate"
],
"properties": {
"type": {
"type": "string",
"enum": [
"VAT",
"GST",
"Custom"
]
},
"rate": {
"type": "number",
"nullable": true
},
"description": {
"type": "string"
}
},
"example": {
"rate": 19,
"type": "VAT",
"description": "Custom 19% VAT"
}
},
"TaxBreakdownInfo": {
"type": "object",
"properties": {
"rate": {
"type": "number",
"nullable": true
},
"type": {
"type": "string",
"enum": [
"VAT",
"GST",
"Custom"
]
},
"_id": {
"type": "string"
}
}
},
"BaseCouponCommon": {
"type": "object",
"description": "The shared properties for the coupon entity and coupon item entity",
"additionalProperties": true,
"required": [
"name",
"_id",
"_title",
"_org",
"_schema",
"_created_at",
"_updated_at",
"type",
"category"
],
"properties": {
"_id": {
"$ref": "#/components/schemas/EntityId"
},
"_title": {
"type": "string",
"description": "The auto-generated title for the title",
"readOnly": true
},
"_org": {
"type": "string",
"description": "Organization Id the entity belongs to",
"readOnly": true
},
"_schema": {
"type": "string",
"enum": [
"coupon"
],
"readOnly": true,
"description": "The schema of the entity, for coupons it is always `coupon`"
},
"_tags": {
"type": "array",
"items": {
"type": "string"
}
},
"_created_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "The creation date for the opportunity"
},
"_updated_at": {
"type": "string",
"format": "date-time",
"readOnly": true,
"description": "The date the coupon was last updated"
},
"name": {
"type": "string",
"nullable": true
},
"description": {
"type": "string",
"nullable": true
},
"type": {
"type": "string",
"enum": [
"fixed",
"percentage"
]
},
"category": {
"type": "string",
"enum": [
"discount",
"cashback"
]
},
"percentage_value": {
"type": "string",
"description": "Use if type is set to percentage. The percentage to be discounted, represented as a whole integer.",
"nullable": true
},
"fixed_value": {
"description": "Use if type is set to fixed. The fixed amount in cents to be discounted, represented as a whole integer.",
"type": "number"
},
"fixed_value_decimal": {
"description": "Use if type is set to fixed. The unit amount in eur to be discounted, represented as a decimal string with at most 12 decimal places.",
"type": "string"
},
"fixed_value_currency": {
"description": "Use if type is set to fixed. Three-letter ISO currency code, in lowercase.",
"oneOf": [
{
"$ref": "#/components/schemas/Currency"
}
]
},
"cashback_period": {
"$ref": "#/components/schemas/CashbackPeriod"
},
"active": {
"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`, or from a journey with `POST /v2/public/catalog`.\n",
"type": "boolean"
},
"requires_promo_code": {
"type": "boolean",
"description": "Whether the coupon requires a promo code to be applied"
}
}
},
"CouponWithoutPromoCodes": {
"type": "object",
"description": "The base for the coupon entity without promo codes",
"allOf": [
{
"$ref": "#/components/schemas/BaseCouponCommon"
}
],
"properties": {
"prices": {
"description": "The prices associated with the coupon. Will hold price entities if hydrated, relations otherwise.",
"oneOf": [
{
"type": "object",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRelation"
}
}
}
},
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Price"
}
}
]
}
},
"example": {
"_id": "123e4567-e89b-12d3-a456-426614174000",
"_schema": "coupon",
"_org": "org_12345",
"_created_at": "2024-01-15T10:00:00.000Z",
"_updated_at": "2024-01-20T12:00:00.000Z",
"_title": "Sample Coupon",
"name": "Sample Coupon",
"type": "fixed",
"fixed_value": 555,
"fixed_value_currency": "USD",
"fixed_value_decimal": "5.55",
"active": true,
"category": "cashback",
"prices": {
"$relation": [
{
"entity_id": "abc12345-def6-7890-gh12-ijklmnopqrst",
"_tags": [
"discount",
"special"
],
"_schema": "price"
}
]
}
}
},
"Coupon": {
"description": "The coupon entity",
"allOf": [
{
"$ref": "#/components/schemas/CouponWithoutPromoCodes"
}
],
"type": "object",
"properties": {
"promo_codes": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PromoCode"
}
},
"promo_code_usage": {
"type": "object",
"additionalProperties": {
"type": "number"
},
"description": "Map of ids of promo codes with their usage count"
}
}
},
"CouponItem": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/BaseCouponCommon"
}
]
},
"PromoCode": {
"type": "object",
"required": [
"id",
"code"
],
"properties": {
"id": {
"type": "string",
"description": "The id of the promo code"
},
"code": {
"type": "string",
"description": "The code of the promo code"
},
"has_usage_limit": {
"type": "boolean",
"description": "Whether the promo code has a usage limit"
},
"usage_limit": {
"type": "number",
"nullable": true,
"description": "The usage limit of the promo code"
}
},
"example": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"code": "123456",
"has_usage_limit": true,
"usage_limit": 10
}
},
"RedeemedPromo": {
"type": "object",
"required": [
"code",
"coupons"
],
"properties": {
"code": {
"description": "The promocode inserted by the customer to redeem the promotion",
"type": "string"
},
"coupons": {
"description": "The coupons that got redeemed with received the code",
"type": "array",
"items": {
"$ref": "#/components/schemas/CouponWithoutPromoCodes"
}
}
}
},
"PriceTier": {
"type": "object",
"properties": {
"up_to": {
"type": "number",
"nullable": true
},
"flat_fee_amount": {
"type": "number"
},
"flat_fee_amount_decimal": {
"type": "string"
},
"unit_amount": {
"type": "number"
},
"unit_amount_decimal": {
"type": "string"
},
"display_mode": {
"$ref": "#/components/schemas/PriceTierDisplayMode"
}
}
},
"PriceTierDisplayMode": {
"type": "string",
"enum": [
"hidden",
"on_request"
]
},
"PricingModel": {
"type": "string",
"description": "Describes how to compute the price per period. Either `per_unit`, `tiered_graduated` or `tiered_volume`.\n- `per_unit` indicates that the fixed amount (specified in unit_amount or unit_amount_decimal) will be charged per unit in quantity\n- `tiered_graduated` indicates that the unit pricing will be computed using tiers attribute. The customer pays the price per unit in every range their purchase rises through.\n- `tiered_volume` indicates that the unit pricing will be computed using tiers attribute. The customer pays the same unit price for all purchased units.\n- `tiered_flatfee` While similar to tiered_volume, tiered flat fee charges for the same price (flat) for the entire range instead using the unit price to multiply the quantity.\n- `dynamic_tariff` indicates that the price is dynamically dependend on the (quarter)-hourly spot market price.\n- `external_getag` indicates that the price is influenced by aquisition fees provided by GetAG.\n",
"enum": [
"per_unit",
"tiered_graduated",
"tiered_volume",
"tiered_flatfee",
"dynamic_tariff",
"external_getag"
]
},
"MarkupPricingModel": {
"type": "string",
"description": "Describes how to compute the markup per period. Either `per_unit`, `tiered_volume` or `tiered_flatfee`.\n- `per_unit` indicates that the fixed amount (specified in unit_amount or unit_amount_decimal) will be charged per unit in quantity\n- `tiered_volume` indicates that the unit pricing will be computed using tiers attribute. The customer pays the same unitary price for all purchased units.\n- `tiered_flatfee` While similar to tiered_volume, tiered flat fee charges for the same price (flat) for the entire range instead using the unit price to multiply the quantity.\n",
"enum": [
"per_unit",
"tiered_volume",
"tiered_flatfee"
]
},
"TypeGetAg": {
"type": "string",
"enum": [
"base_price",
"work_price"
]
},
"TariffTypeGetAg": {
"type": "string",
"enum": [
"HT",
"NT"
]
},
"ConsumptionTypeGetAg": {
"type": "string",
"enum": [
"household",
"heating_pump",
"night_storage_heating",
"night_storage_heating_common_meter"
]
},
"ProductCategory": {
"type": "string",
"enum": [
"power",
"gas"
]
},
"PriceGetAg": {
"type": "object",
"properties": {
"category": {
"$ref": "#/components/schemas/ProductCategory"
},
"markup_pricing_model": {
"$ref": "#/components/schemas/MarkupPricingModel"
},
"type": {
"$ref": "#/components/schemas/TypeGetAg"
},
"tariff_type": {
"$ref": "#/components/schemas/TariffTypeGetAg"
},
"consumption_type": {
"$ref": "#/components/schemas/ConsumptionTypeGetAg"
},
"concession_type": {
"oneOf": [
{
"$ref": "#/components/schemas/GasConcessionType"
}
]
},
"meter_type": {
"oneOf": [
{
"$ref": "#/components/schemas/PowerMeterType"
}
]
},
"markup_tiers": {
"description": "Defines an array of tiers. Each tier has an upper bound, an unit amount and a flat fee.\n",
"type": "array",
"items": {
"$ref": "#/components/schemas/PriceTier"
}
},
"markup_amount": {
"type": "number"
},
"markup_amount_decimal": {
"type": "string"
},
"markup_amount_net": {
"type": "number"
},
"markup_amount_net_decimal": {
"type": "string"
},
"markup_amount_gross": {
"type": "number"
},
"markup_amount_gross_decimal": {
"type": "string"
},
"markup_total_amount_net": {
"type": "number"
},
"markup_total_amount_net_decimal": {
"type": "string"
},
"markup_total_amount_gross": {
"type": "number"
},
"markup_total_amount_gross_decimal": {
"type": "string"
},
"additional_markups_enabled": {
"type": "boolean",
"description": "Whether the additional markups are enabled"
},
"additional_markups": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"amount_decimal": {
"type": "string"
},
"amount": {
"type": "number"
},
"amount_net": {
"type": "number"
},
"amount_net_decimal": {
"type": "string"
},
"amount_gross": {
"type": "number"
},
"amount_gross_decimal": {
"type": "string"
}
},
"required": [
"amount_decimal",
"amount"
]
}
},
"unit_amount_gross": {
"type": "number"
},
"unit_amount_gross_decimal": {
"type": "string"
},
"unit_amount_net": {
"type": "number"
},
"unit_amount_net_decimal": {
"type": "string"
}
},
"required": [
"category",
"markup_amount",
"markup_amount_decimal",
"unit_amount_gross",
"unit_amount_net"
]
},
"PriceDynamicTariff": {
"type": "object",
"properties": {
"mode": {
"$ref": "#/components/schemas/DynamicTariffMode"
},
"interval": {
"$ref": "#/components/schemas/DynamicTariffInterval"
},
"average_price": {
"type": "number"
},
"average_price_decimal": {
"type": "string"
},
"markup_amount": {
"type": "number",
"description": "The markup amount, configured in Epilot, in cents."
},
"markup_amount_decimal": {
"type": "string",
"description": "The markup amount, configured in Epilot, as a string with full precision."
},
"markup_amount_net": {
"type": "number",
"description": "The markup amount net, configured in Epilot, in cents."
},
"markup_amount_net_decimal": {
"type": "string",
"description": "The markup amount net, configured in Epilot, as a string with full precision."
},
"markup_amount_gross": {
"type": "number",
"description": "The markup amount gross, configured in Epilot, in cents."
},
"markup_amount_gross_decimal": {
"type": "string",
"description": "The markup amount gross, configured in Epilot, as a string with full precision."
},
"unit_amount_net": {
"type": "number",
"description": "The unit amount net for the energy price in cents, it's provided by an external provider."
},
"unit_amount_net_decimal": {
"type": "string",
"description": "The unit amount net for the energy price as a string with full precision, it's provided by an external provider."
},
"unit_amount_gross": {
"type": "number",
"description": "The unit amount gross for the energy price in cents, it's provided by an external provider."
},
"unit_amount_gross_decimal": {
"type": "string",
"description": "The unit amount gross for the energy price as a string with full precision, it's provided by an external provider."
}
},
"required": [
"mode",
"markup",
"markup_decimal",
"average_price",
"average_price_decimal"
]
},
"TierDetails": {
"type": "object",
"properties": {
"quantity": {
"type": "number"
},
"unit_amount": {
"type": "number"
},
"unit_amount_gross": {
"type": "number"
},
"unit_amount_net": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"unit_amount_decimal": {
"type": "string"
}
},
"required": [
"quantity",
"unit_amount",
"unit_amount_gross",
"unit_amount_net",
"amount_total",
"amount_subtotal",
"amount_tax",
"unit_amount_decimal"
]
},
"SearchExternalCatalogParams": {
"type": "object",
"properties": {
"context": {
"anyOf": [
{
"$ref": "#/components/schemas/JourneyContext"
}
]
}
},
"additionalProperties": false,
"required": [
"context"
]
},
"ExternalCatalogRequest": {
"description": "The request payload for the external catalog service.",
"allOf": [
{
"$ref": "#/components/schemas/ExternalCatalogConfigurationRequest"
},
{
"oneOf": [
{
"$ref": "#/components/schemas/ExternalCatalogJourneyRequest"
},
{
"$ref": "#/components/schemas/ExternalCatalogPortalRequest"
},
{
"$ref": "#/components/schemas/ExternalCatalogCustomRequest"
}
]
}
],
"discriminator": {
"propertyName": "origin",
"mapping": {
"journey": "#/components/schemas/ExternalCatalogJourneyRequest",
"portal": "#/components/schemas/ExternalCatalogPortalRequest",
"custom": "#/components/schemas/ExternalCatalogCustomRequest"
}
},
"example": {
"config": {
"appId": "1234567890",
"componentId": "1234567890",
"hookId": "1234567890"
},
"origin": "journey",
"context": {
"journey_id": "8d0a2235-97ce-42d0-88a3-e374634ca44e",
"entity_id": "9e1b3346-a8df-53e1-99b4-f485745db55f",
"journey_name": "Product Selection Journey",
"journey_tags": [
"electricity",
"residential"
],
"journey_url_params": {
"utm_source": "google",
"utm_campaign": "spring2024"
},
"current_step_name": "Product Selection",
"current_block_name": "Energy Products",
"steps_data": [
{
"step_name": "Address Information",
"step_index": 0,
"blocks": {
"Adresse": {
"countryCode": "DE",
"city": "Koblenz",
"zipCode": "56068",
"streetName": "Am Alten Hospital",
"houseNumber": "123"
}
}
}
]
}
}
},
"ExternalCatalogConfigurationRequest": {
"type": "object",
"description": "The request payload for the external catalog configuration service.",
"properties": {
"config": {
"type": "object",
"properties": {
"appId": {
"type": "string",
"description": "The app id.",
"example": "1234567890"
},
"componentId": {
"type": "string",
"description": "The component id.",
"example": "1234567890"
},
"hookId": {
"type": "string",
"description": "The hook id. If not provided, the first valid hook will be used.",
"example": "1234567890"
}
},
"required": [
"appId",
"componentId"
]
}
},
"example": {
"config": {
"appId": "1234567890",
"componentId": "1234567890",
"hookId": "1234567890"
}
}
},
"ExternalCatalogJourneyRequest": {
"type": "object",
"description": "The request payload for the external catalog service with a journey context.",
"properties": {
"origin": {
"type": "string",
"description": "The origin of the request.",
"enum": [
"journey"
],
"example": "journey"
},
"context": {
"$ref": "#/components/schemas/JourneyContext"
}
},
"required": [
"origin",
"context"
]
},
"ExternalCatalogPortalRequest": {
"type": "object",
"description": "The request payload for the external catalog service with a portal context.",
"properties": {
"origin": {
"type": "string",
"description": "The origin of the request.",
"enum": [
"portal"
],
"example": "portal"
},
"context": {
"$ref": "#/components/schemas/PortalContext"
}
},
"required": [
"origin",
"context"
]
},
"ExternalCatalogCustomRequest": {
"type": "object",
"description": "The request payload for the external catalog service with a custom context. E.g. for requests from the Portal.",
"properties": {
"origin": {
"type": "string",
"description": "The origin of the request.",
"enum": [
"custom"
],
"example": "custom"
},
"context": {
"$ref": "#/components/schemas/CustomContext"
}
},
"required": [
"origin",
"context"
]
},
"CustomContext": {
"type": "object",
"description": "A custom context object. E.g. for Portal context.",
"additionalProperties": true,
"example": {
"custom_context_key": "custom_context_value"
}
},
"JourneyContext": {
"type": "object",
"additionalProperties": false,
"properties": {
"journey_id": {
"type": "string",
"description": "The ID of the journey.",
"example": "8d0a2235-97ce-42d0-88a3-e374634ca44e"
},
"entity_id": {
"type": "string",
"description": "The ID of the entity.",
"example": "8d0a2235-97ce-42d0-88a3-e374634ca44e"
},
"journey_name": {
"type": "string",
"description": "The name of the journey.",
"example": "journey name"
},
"journey_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "The tags of the journey."
},
"journey_url_params": {
"type": "object",
"description": "The URL parameters of the journey.",
"additionalProperties": true
},
"current_step_name": {
"description": "The name of the step where the products selection is happening.",
"type": "string",
"example": "step name"
},
"current_block_name": {
"type": "string",
"example": "block name",
"description": "The name of the block where the products selection is happening."
},
"steps_data": {
"type": "array",
"description": "The steps of the journey.",
"items": {
"type": "object",
"properties": {
"step_name": {
"type": "string",
"description": "The name of the step."
},
"step_index": {
"type": "integer",
"description": "The index of the step."
},
"blocks": {
"type": "object",
"description": "The data of the blocks.",
"additionalProperties": true,
"example": {
"Adresse": {
"countryCode": "DE",
"city": "Koblenz",
"zipCode": "56068",
"streetName": "Am Alten Hospital",
"houseNumber": "123"
}
}
}
},
"additionalProperties": false,
"required": [
"step_name",
"step_index",
"blocks"
]
}
}
},
"required": [
"journey_id",
"journey_name",
"current_step_name",
"current_block_name",
"steps_data"
]
},
"PortalContext": {
"type": "object",
"additionalProperties": true,
"properties": {
"contract": {
"type": "object",
"description": "The contract information.",
"additionalProperties": true
},
"contact": {
"type": "object",
"description": "The contact information.",
"additionalProperties": true
},
"availability_address": {
"type": "object",
"description": "Address to use for product availability checks. Include when the catalog should filter products by serviceable area (e.g. postal code coverage).\n",
"properties": {
"postal_code": {
"type": "string",
"description": "Postal Code"
},
"city": {
"type": "string",
"description": "City"
},
"street": {
"type": "string",
"description": "Street"
},
"street_number": {
"type": "string",
"description": "Street Number"
},
"journey_target_block": {
"type": "string",
"description": "The journey target block of the availability address /"
}
}
},
"variable_inputs": {
"type": "array",
"description": "Variable inputs (e.g. energy or water consumption) extracted/provided by the portal so the external catalog service can compute amounts for variable prices.\n",
"items": {
"type": "object",
"properties": {
"value": {
"type": "number",
"description": "The value of the variable input"
},
"unit": {
"type": "string",
"description": "The unit of the variable input"
},
"frequency_unit": {
"type": "string",
"description": "The frequency unit of the variable input",
"enum": [
"weekly",
"monthly",
"every_quarter",
"every_6_months",
"yearly",
"one_time"
]
},
"journey_target_block": {
"type": "string",
"description": "The journey target block of the variable input /"
}
}
}
}
},
"required": [
"contract",
"contact"
]
},
"SearchExternalCatalogResult": {
"type": "object",
"properties": {
"hits": {
"type": "number",
"description": "The number of results returned."
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExternalCatalogItem"
}
}
},
"required": [
"results",
"hits"
]
},
"SearchExternalCatalogRecommendationsResult": {
"type": "object",
"properties": {
"source": {
"$ref": "#/components/schemas/ExternalCatalogItem"
},
"offers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ExternalCatalogItem"
}
}
},
"required": [
"source",
"offers"
]
},
"ExternalCatalogItem": {
"type": "object",
"description": "An external product & price information (already computed) from an external catalog.",
"properties": {
"pricing_details": {
"$ref": "#/components/schemas/PricingDetails"
},
"_meta": {
"$ref": "#/components/schemas/SignatureMeta"
}
},
"required": [
"pricing_details",
"_meta"
]
},
"ProductRecommendationSearch": {
"description": "Product recommendations request payload",
"type": "object",
"properties": {
"product_recommendation_ids": {
"type": "array",
"items": {
"type": "string",
"description": "Product recommendation id"
}
},
"catalog_item": {
"type": "object",
"description": "The catalog item to be used as source for the recommendation",
"properties": {
"product_id": {
"type": "string",
"description": "Product id"
},
"price_id": {
"type": "string",
"description": "Product id"
}
}
},
"contract_id": {
"type": "string",
"description": "The contract id to be used as source for the recommendation"
},
"filters": {
"$ref": "#/components/schemas/AvailabilityFilters"
}
}
},
"ProductRecommendationResponse": {
"description": "Product recommendations request payload",
"type": "object",
"properties": {
"hits": {
"type": "number",
"description": "The number of results returned."
},
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProductRecommendation"
}
},
"source": {
"type": "object",
"description": "Context about what the recommendations were searched against.",
"properties": {
"item": {
"description": "The first line item of the contract used as source for the recommendation.\nCarries the amounts the customer currently pays; only present when searching by contract_id.\n",
"anyOf": [
{
"$ref": "#/components/schemas/PriceItem"
},
{
"$ref": "#/components/schemas/CompositePriceItem"
}
]
}
}
}
},
"required": [
"results",
"hits"
]
},
"OfferHighlightConfig": {
"type": "object",
"properties": {
"unique_selling_point": {
"type": "string"
},
"unique_selling_point_icon": {
"type": "string"
},
"total": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"format": {
"type": "string",
"enum": [
"absolute",
"relative"
]
},
"only_if_better": {
"type": "boolean"
}
}
}
}
},
"Offer": {
"type": "object",
"properties": {
"target_id": {
"type": "string"
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"price_id": {
"type": "string"
},
"product_id": {
"type": "string"
},
"highlight_config": {
"$ref": "#/components/schemas/OfferHighlightConfig"
}
},
"required": [
"price_id",
"product_id"
]
}
}
}
},
"ProductRecommendation": {
"allOf": [
{
"$ref": "#/components/schemas/EntityItem"
}
],
"type": "object",
"properties": {
"source_price": {
"type": "object",
"description": "Price being used as source",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRelation"
}
}
}
},
"source_product": {
"type": "object",
"description": "Product being used as source",
"properties": {
"$relation": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntityRelation"
}
}
}
},
"type": {
"type": "string",
"description": "Type of product recommendation",
"enum": [
"change",
"cross-sell",
"up-sell"
]
},
"offers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Offer"
}
}
}
}
},
"examples": {
"checkout-with-transient-cart": {
"value": {
"mode": "create_order",
"cart": {
"customer": {
"first_name": "john",
"last_name": "doe",
"company_name": "company limited",
"vat_id": "123892321",
"email": "johndoe@company.com",
"phone": "+44233242423"
},
"billing_address": {
"street1": "wallstreet",
"street2": 1,
"city": "new york city",
"country": "united states",
"country_code": "US",
"additional_info": "headquarters office"
},
"delivery_address": {
"street1": "berverly hills avenue",
"street2": "block 1",
"city": "berverly hills",
"country": "california",
"country_code": "CA",
"additional_info": "remote cowork place"
},
"line_items": [
{
"quantity": 3,
"product_id": "b7185fb7-b10f-4875-bda7-288631446555",
"price_id": "df240bab-9f71-4a9a-a9e1-59f18827dbf9",
"is_composite_price": false
},
{
"quantity": 2,
"product_id": "607d2952-8f3e-484f-a82b-4880528b7f55",
"price_id": "7b028fdf-0b0a-4077-a8f1-d0cbbd14b7cf",
"is_composite_price": false
}
]
}
}
},
"checkout-result": {
"value": {
"order": {
"_id": "d1ZoC1FwZ6",
"type": "Draft",
"cart_id": "p0ZoB1FwH6",
"order_number": "20201021-234324",
"_org_id": "123",
"metadata": [
{
"key": "journey-id",
"value": "8d0a2235-97ce-42d0-88a3-e374634ca44e"
}
],
"billing_first_name": "john",
"billing_last_name": "doe",
"billing_company_name": "i me and myself",
"billing_vat": "234823948",
"billing_email": "johndoe@nowhere.com",
"currency": "EUR",
"billing_phone": "+1234234545",
"billing_contact": "villy or zilly",
"line_items": [
{
"id": "mSjGCTfn8w",
"pricing_model": "per_unit",
"is_composite_price": false,
"metadata": [
{
"cart_id": "p0ZoB1FwH6"
}
],
"description": "Wallbox Premium - Premium Price",
"currency": "EUR",
"unit_amount": 78900,
"amount_subtotal": 50000,
"amount_total": 61500,
"quantity": 1,
"product_id": "b7185fb7-b10f-4875-bda7-288631446555",
"price_id": "df240bab-9f71-4a9a-a9e1-59f18827dbf9",
"taxes": [
{
"amount": 11500,
"rate": "MwSt. 23%"
}
],
"_price": {
"_id": "df240bab-9f71-4a9a-a9e1-59f18827dbf9",
"unit_amount": 78900,
"unit_amount_currency": "EUR",
"unit_amount_decimal": "789",
"type": "one_time",
"active": true,
"sales_tax": "standard",
"is_tax_inclusive": true,
"description": "Winter Sale",
"_created_at": "2021-11-10T18:02:58.318Z",
"_updated_at": "2021-11-10T18:02:58.318Z",
"_title": "Winter Sale",
"pricing_model": "per_unit",
"is_composite_price": false
}
},
{
"id": "mZkGCTfn6p",
"metadata": [
{
"cart_id": "p0ZoB1FwH6"
}
],
"description": "Wallbox Basic with Full Add-ons - Basic Price",
"currency": "EUR",
"unit_amount": 78900,
"amount_subtotal": 50000,
"amount_total": 53500,
"quantity": 1,
"product_id": "zzzzzz-b10f-4875-bda7-288631446555",
"price_id": "zzzzz-9f71-4a9a-a9e1-59f18827dbf9",
"pricing_model": "per_unit",
"is_composite_price": false,
"taxes": [
{
"amount": 3500,
"rate": "MwSt. 7%"
}
],
"_price": {
"_id": "zzzzz-9f71-4a9a-a9e1-59f18827dbf9",
"unit_amount": 78900,
"unit_amount_decimal": "789",
"unit_amount_currency": "EUR",
"type": "one_time",
"active": true,
"sales_tax": "standard",
"is_tax_inclusive": true,
"description": "Winter Sale",
"billing_scheme": "per_unit",
"_created_at": "2021-11-10T18:02:58.318Z",
"_updated_at": "2021-11-10T18:02:58.318Z",
"_title": "Winter Sale",
"pricing_model": "per_unit",
"is_composite_price": false
}
}
],
"amount_subtotal": 100000,
"amount_total": 115000,
"total_details": {
"amount_shipping": 10000,
"amount_tax": 15000,
"breakdown": {
"taxes": [
{
"tax": {
"_id": "936db2a1-3748-45b6-bb9d-04943280ceeb",
"_title": "VAT 23%",
"_org": "728",
"_schema": "tax",
"_created_at": "2021-09-24T15:06:13.859Z",
"_updated_at": "2021-09-24T15:06:13.859Z",
"type": "VAT",
"rate": 23
},
"amount": 11500
},
{
"tax": {
"_id": "936db2a1-3748-45b6-bb9d-04943280cee4",
"_title": "VAT 7%",
"_org": "728",
"_schema": "tax",
"_created_at": "2021-09-24T15:06:13.859Z",
"_updated_at": "2021-09-24T15:06:13.859Z",
"type": "VAT",
"rate": 7
},
"amount": 3500
}
]
}
},
"_created_at": "2021-11-10T18:02:58.318Z",
"_updated_at": "2021-11-10T18:02:58.318Z"
}
}
}
}
}
}