{ "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": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/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": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/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": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/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": "Invalid payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/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" } } } } } } }, "/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", "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" } } } } } } } } }, "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: the situations a\nconditional Product, Price or Coupon is commonly varied by, ready to be copied into that\nschema's `conditions` array and extended or modified from there.\n\nWhich sets exist depends on the schema — an offer window is a Product's dimension, a delivery\narea is a Price's and a Coupon's — so only the sets built in for `slug` are returned.\n\nStatic, read-only reference data. The catalog is the same for every organization and is not\napplied to any schema by this endpoint — adding conditions to a schema stays an Entity API\nwrite.\n", "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" } } } } } } }, "/v1/conditional-pricing:resolve": { "post": { "description": "Resolves which of a conditional entity's variants apply, and returns each one composed: the\nbase entity overlaid with the values of the version in effect at `as_of`.\n\nResolution is two selections in a fixed order — the variant, then the version by `as_of`. It\nis always scoped to one logical entity, so it stays a cheap, predictable lookup rather than\nan open search.\n\n**The variant is selected one of two ways, and the body says which.** A `context` describes a\nsituation and is matched against the conditions each variant pins. A `variant_id` names one\nvariant and skips matching entirely. Exactly one of the two: a body carrying both, or\nneither, is a `400`.\n\nMatching follows two rules worth knowing before assembling a context. A condition a variant\ndoes **not** pin matches any value, which is what lets a condition be added to a schema\nwithout breaking the variants that already exist. A condition **missing from `context`**,\nhowever, does not satisfy one a variant pinned: an incomplete integration resolves to\nnothing rather than silently matching another segment's variants.\n\nWhen nothing matches, the entity's `default` variant is returned if it has one. There is no\nimplicit fallback to the unmodified base entity: an empty `results` means nothing applies to\nthis situation, and the base entity's values are not an answer to it. A pin does not reach\nthat fallback at all: it asks for one variant by name, and answers with it or with a 404.\n\n`options.hydrate` returns the entities a relation attribute references in place of the\nreferences, on either branch.\n\nAvailability is a separate mechanism and is never consulted here.\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": "What an order shows — the numbers the customer agreed to", "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 shows — what is billable 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 nothing\napplies and the entity has no `default` variant. With `resolve_one`, exactly one result;\nwith a pin, exactly one or a 404.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolvedVariants" }, "examples": { "A hydrated composite price": { "summary": "`price_components` holds 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" }, { "_id": "price-kwh-46045", "_schema": "price", "unit_amount": 32, "unit_amount_currency": "EUR" } ] } ] } }, "A variant carrying overrides that did not apply": { "summary": "`unit_amount_currency` reads as the entity's own value rather than the variant's, 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": "The context is not usable against this schema: it names an undefined condition\n(`CONDITION_UNDEFINED`), applies an operator the condition's type does not support\n(`OPERATOR_UNSUPPORTED`), carries a value malformed for its type (`CONTEXT_FORMAT_INVALID`),\nor selects more variants than one response may carry (`TOO_MANY_MATCHES`).\n\nOr the body did not pick a branch: it carries both `context` and `variant_id`, or\nneither, or sends `resolve_one` beside a pin. Those are request-validation failures, so\nthey carry a message and neither `code` nor `details` — testing `code` for absence is how\na client tells one from the four coded failures above.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`) or entity (`ENTITY_NOT_FOUND`).\n\nOn the pinned branch: the entity has no such variant, or the variant belongs to another\nentity (`VARIANT_NOT_FOUND`), or it has no version in effect at `as_of` because its first\none is later (`NO_ACTIVE_VERSION`, carrying the instant in `details.as_of`). Context\nmatching drops such a variant from the results instead — a set may lose a member where a\npin naming one cannot answer with silence. It is not `VERSION_NOT_FOUND`: a pin names no\n`valid_from`, and the variant's versions all exist — none is in effect yet.\n\nOn the context branch, with `resolve_one`: nothing applied to the context and the entity\nhas no `default` variant (`NO_MATCHES`). That says the addressing was right and nothing\nserves this situation; without `resolve_one` it is a `200` carrying an empty `results`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "409": { "description": "Several variants apply while a single result was requested (`AMBIGUOUS_RESOLUTION`); the\ncandidates are in `details`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "501": { "description": "A field published ahead of its behaviour was used: `variant_id`, or `options.hydrate` set\nto `true`. Declining it is how a deployed stage says the field exists and does not work\nyet, rather than quietly returning the `default` variant or unhydrated references.\n\nAnswered ahead of every other check, so a body that also names a schema that does not\nexist gets this rather than a `404`.\n\nRead `message`. The body is the shared `Error` shape rather than\n`ConditionalPricingError` — there is no code for \"not built yet\" — as it is on every 501\nthis API answers, so one branch covers all of them.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/conditional-pricing/{slug}/entities/{entity_id}/variants": { "post": { "description": "Creates one variant of a conditional entity, together with the first version carrying its\nvalues: a variant always has at least one version.\n\nThe body pins the situation the variant applies to. Pins are exact values only — predicates\nare a read-side concept and are rejected here — and are stored canonicalized for their\ncondition's type, so two spellings of one instant, or one town written two ways, are one\nvariant rather than two that no context can tell apart.\n\nThree write rules are worth knowing before the first call:\n\n- A variant must pin at least one condition or be marked `default`. A variant pinning nothing\n would be a universal wildcard matching every resolve, which is a far more dangerous thing\n than a fallback and far easier to create by accident.\n- `default` is a property of the variant, set by the `default` flag, and is never a value in\n `conditions` — not even `false`. A `default` variant cannot pin anything else, and an entity\n can have only one; a second is refused as `TUPLE_CONFLICT`. Any entity may have one;\n nothing is declared in the schema to allow it.\n- Condition values are immutable afterwards. A variant's identity is the situation it applies\n to, and orders and contracts pin it. **A condition added to a schema that already has\n variants is effectively one-way**: every existing variant is a wildcard on the new\n dimension, but the first variant that pins it is ambiguous against all of them, and\n retro-pinning the others is blocked by this same rule.\n\nAttribute values are applied only for attributes currently carrying `overridable_attribute`.\nMetadata and non-overridable fields present in the body are not applied rather than rejected,\nand every one but the metadata is named in the response's `warnings`, so a client working from\na slightly stale schema snapshot still succeeds and still learns which fields did not land.\nMetadata is never named, since a client echoing back a payload it read carries it in every\nbody.\n\n`variant_id` is always server-generated and returned, and is not accepted in the body — the\nrequest schema admits no such property. It is the durable key orders and contracts pin.\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 `values` holds what was stored, so the two attributes the warning names are absent from it", "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": "The variant cannot be created as described: it pins nothing and is not the default\n(`VARIANT_UNPINNED`), pins a condition the schema does not declare\n(`CONDITION_UNDEFINED`), pins a `select` value the condition's vocabulary does not admit\n(`CONDITION_VALUE_INVALID`), carries a value malformed for its condition's type\n(`PIN_FORMAT_INVALID`), or the entity already holds every variant it may hold\n(`VARIANT_LIMIT_REACHED`).\n\nSeveral refusals on this response carry no code, and testing `code` for absence is how\nthey are told from the five above: pinning the fallback marker directly under either of\nits names (`default` or `_default`), marking a variant `default` while it also pins a\nreal condition, pinning a condition whose declared type this deploy cannot read, and a\n`valid_from` this store cannot sort by. Each is an integration mistake rather than one\nbad row in a source file.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`), or no such entity under it (`ENTITY_NOT_FOUND`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "409": { "description": "Another variant of this entity already pins this exact combination of condition values\n(`TUPLE_CONFLICT`, naming it in `details.conflicting_variant_id`) — which is also how a\nsecond `default` variant is refused — or the entity's items are being written\nconcurrently (`WRITE_CONFLICT`, retryable).\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 — the browse, filter\nand search read behind the Entity UI's variant screens.\n\nA `POST` because the condition filter is a structured object and needs a body; nothing is\nwritten. Every property in that body is optional, so `{}` is the whole of \"the first ten\nvariants, in `variant_id` order\" — but the body itself is required, so send `{}` rather than\nnothing at all.\n\nThree ways to narrow, and they combine. `conditions` filters on the pins themselves and takes\nthe same seven predicates a resolve context does; `search` is free text over pinned values;\n`sort` orders by one pin. **A variant matches the filter only where it pins the condition** —\nthe one place a filter and a resolve context differ: asking for the variants pinning postal\ncode 46045 does not return every variant that pins no postal code at all.\n\nRows report what is *stored*, not what resolves: no version data, no `_revision` and no\n`_inert_overrides`.\n\nPaging is by offset for the first pages and by an opaque `cursor` beyond them. `size` defaults\nto 10 and is clamped at 1000; a `from` past the offset window is refused rather than clamped,\nand the refusal names the cursor to continue with.\n\n**Published ahead of the behaviour.** No handler serves this yet, so a deployed stage answers\n`501`. The examples below are what a consumer builds against in the meantime.\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 — at most one per entity", "value": { "conditions": { "default": true } } }, "Filter, search and sort together": { "summary": "The 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": "The listing cannot be served as described.\n\nThe filter is checked against the schema exactly as a resolve context is, by the same\ncode, so it reports the same three codes: a condition the schema does not declare\n(`CONDITION_UNDEFINED`), a predicate the condition's type does not support\n(`OPERATOR_UNSUPPORTED`), or a value malformed for its type (`CONTEXT_FORMAT_INVALID`).\n\nTwo paging refusals carry codes of their own, and the fix for each is a different request:\na `from` plus `size` reaching past the offset window (`OFFSET_WINDOW_EXCEEDED`, naming all\nthree numbers in `details`; page on with the last response's `next` instead), and a\n`cursor` that is malformed or was issued for a different listing (`CURSOR_INVALID`; start\nthe listing again without one).\n\nA `sort` naming something other than a `conditions.` of a sortable type carries a\nmessage and neither `code` nor `details`, as does a body this schema rejects outright.\nTesting `code` for absence is how those are told from the five above.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`), or no such entity under it (`ENTITY_NOT_FOUND`).\n\nAn entity that exists and has no variants is a `200` carrying an empty `results` and\n`hits: 0` — having none is an answer, not a missing resource.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "501": { "description": "Published ahead of the behaviour. This operation is declared and not yet dispatched, so\nevery request to it is answered here until the listing behaviour lands — which is how a\ndeployed stage says \"this exists and does not work yet\" rather than answering with an\nempty page a client would read as an empty entity.\n\nRead `message`. The body is the shared `Error` shape, as it is on every 501 this API\nanswers, so one \"not built yet\" branch covers all of them.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/conditional-pricing/{slug}/entities/{entity_id}/variants:tree": { "post": { "description": "The variants list, each row carrying the version in effect at `as_of` — the Entity UI's main\nediting screen in one call rather than one call per row.\n\nEverything the variants list accepts, filtering, search, sort and paging alike, means the same\nhere. Three differences, all from the version lookup each row costs: the body takes an\n`as_of`, `size` is clamped at 100 rather than 1000, and a variant with no version to show is\nomitted from `results` (see `VariantTree`).\n\nEvery row carries a `version`, and a `status` saying which one it got. A variant always has at\nleast one version, so at any instant either a version is in effect (`active`) or every\nversion of that variant is still ahead of it (`scheduled`) — in which case `version` is that\nupcoming first one, which is what makes a staged variant visible on the screen rather than\nblank.\n\nThe version on a row carries no `_revision`. An editing screen re-reads the one version it is\nabout to write through that version's own `GET`, which is strongly consistent, and writes with\nthe revision it returns.\n\nThe base entity is not part of this response. The screen's standard-price row is an ordinary\nentity read, and a variant's full timeline is the versions list.\n\n**Published ahead of the behaviour.** No handler serves this yet, so a deployed stage answers\n`501`.\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": "What the table will look like 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": "The listing cannot be served as described — the variants list's `400` word for word, plus\nan `as_of` that is not a timestamp this API can read.\n\nThe filter is checked against the schema exactly as a resolve context is, by the same\ncode, so it reports the same three codes: a condition the schema does not declare\n(`CONDITION_UNDEFINED`), a predicate the condition's type does not support\n(`OPERATOR_UNSUPPORTED`), or a value malformed for its type (`CONTEXT_FORMAT_INVALID`).\n\nTwo paging refusals carry codes of their own, and the fix for each is a different request:\na `from` plus `size` reaching past the offset window (`OFFSET_WINDOW_EXCEEDED`, naming all\nthree numbers in `details`; page on with the last response's `next` instead), and a\n`cursor` that is malformed or was issued for a different listing (`CURSOR_INVALID`; start\nthe listing again without one).\n\nA `sort` naming something other than a `conditions.` of a sortable type carries a\nmessage and neither `code` nor `details`, as does a body this schema rejects outright.\nTesting `code` for absence is how those are told from the five above.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`), or no such entity under it (`ENTITY_NOT_FOUND`).\n\nAn entity that exists and has no variants is a `200` carrying an empty `results` and\n`hits: 0` — having none is an answer, not a missing resource.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "501": { "description": "Published ahead of the behaviour. This operation is declared and not yet dispatched, so\nevery request to it is answered here until the listing behaviour lands — which is how a\ndeployed stage says \"this exists and does not work yet\" rather than answering with an\nempty page a client would read as an empty entity.\n\nRead `message`. The body is the shared `Error` shape, as it is on every 501 this API\nanswers, so one \"not built yet\" branch covers all of them.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/conditional-pricing/{slug}/entities/{entity_id}/variants/{variant_id}": { "get": { "description": "Returns the version of this variant that is currently in effect — the one with the latest\n`valid_from` at or before now.\n\nThe \"open this variant\" read: no date arithmetic is asked of the caller, and what comes back\ncarries the `_revision` a write to that version has to be sent with, so an editing screen can\nload and save without working out which version it is looking at.\n\nWhat is returned is the version's own attribute overrides, not the base entity overlaid with\nthem. Composing the two is what `:resolve` answers.\n\nA variant staged ahead of its launch has versions but none of them in effect, and is reported\nas having none rather than as not existing — the two are fixed differently.\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": "Invalid request, e.g. the slug names no conditional entity type.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No entity with that id (`ENTITY_NOT_FOUND`), no such variant under it\n(`VARIANT_NOT_FOUND`), or it has no version in effect at the instant addressed\n(`NO_ACTIVE_VERSION`). A variant whose versions are all still\nscheduled has none in effect, which is reported as such rather than as a missing\nvariant. Selecting the\nversion in effect and reading it are two reads, so a delete landing between them is\nanswered `VERSION_NOT_FOUND`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } } } }, "put": { "description": "Replaces the values of the version currently in effect, wholesale.\n\nThe body is the complete set of attribute overrides: an attribute the variant may override and\nthat is absent from it stops being overridden. Attributes the variant may **not** override are\nnot applied where the body carries them, and their stored value is kept rather than dropped.\n\nEditing the version in effect is the ordinary way a live price is corrected, and warns about\nnothing: what changes is what that version *says*, not which version is in effect.\n\nNeither `valid_from` nor `conditions` can be changed here. Both are accepted when they match\nwhat is stored, so a client building its body from the version it loaded need not strip them\nout first, and both are refused when they name something else.\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": "The write cannot be applied as described: it would move the version it addresses to another\n`valid_from`, or change the conditions its variant is pinned to — both identity rather than\ncontent, and both fixed at creation. Also when `_revision` is missing or is not a revision\nmarker.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`), no entity with that id (`ENTITY_NOT_FOUND`), no such\nvariant under it (`VARIANT_NOT_FOUND`), or the variant has no version in effect at the\ninstant addressed (`NO_ACTIVE_VERSION`). A\nvariant whose versions are all still scheduled has none in effect, which is reported as\nsuch rather than as a missing variant. Selecting the\nversion in effect and reading it are two reads, so a delete landing between them is\nanswered `VERSION_NOT_FOUND`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "409": { "description": "The version has been written since `_revision` was read (`WRITE_CONFLICT`, retryable after\nre-reading the version).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } } } }, "patch": { "description": "Changes only the fields it names on the version currently in effect.\n\nEverything the body does not mention is left as stored — the \"just nudge this number\" write. A\n`null` is a value like any other rather than a deletion; a client that wants an attribute to\nstop being overridden sends the complete snapshot without it through `PUT`.\n\nAttempting to change a pinned condition value is refused, as on every version write: a\nvariant's conditions are fixed at creation.\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": "The write cannot be applied as described: it would move the version it addresses to another\n`valid_from`, or change the conditions its variant is pinned to — both identity rather than\ncontent, and both fixed at creation. Also when `_revision` is missing or is not a revision\nmarker.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`), no entity with that id (`ENTITY_NOT_FOUND`), no such\nvariant under it (`VARIANT_NOT_FOUND`), or the variant has no version in effect at the\ninstant addressed (`NO_ACTIVE_VERSION`). A\nvariant whose versions are all still scheduled has none in effect, which is reported as\nsuch rather than as a missing variant. Selecting the\nversion in effect and reading it are two reads, so a delete landing between them is\nanswered `VERSION_NOT_FOUND`.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "409": { "description": "The version has been written since `_revision` was read (`WRITE_CONFLICT`, retryable after\nre-reading the version).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } } } }, "delete": { "description": "Removes one variant of a conditional entity: the condition tuple it holds, its registration\nin the search index, and every version it accumulated.\n\nTwo phases. The first frees the tuple and deregisters the variant, and is what makes the\ncombination of condition values immediately reusable — the second removes the version rows in\nbatches afterwards. A response arrives only once both have finished for this request, but the\ntuple is reusable from the moment the first completes, whether or not the second did: a\nvariant with more versions than one transaction can carry is the ordinary case, not an edge\none. An interrupted delete is safe to send again; it picks up where it stopped.\n\nNothing is archived. A variant an order or contract pins stops resolving, and hydration drops\nthe reference leniently rather than failing the read.\n\nThis removes the **variant**, not one of its versions. To remove a single version, name it on\n`…/variants/{variant_id}/versions/{valid_from}` — including the one currently in effect, which\nhas no shorthand delete: a delete names the version it removes.\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": "Invalid request, e.g. the slug names no conditional entity type.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No entity with that id (`ENTITY_NOT_FOUND`), or it has no such variant\n(`VARIANT_NOT_FOUND`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "409": { "description": "The variant's items are being written concurrently (`WRITE_CONFLICT`, retryable).", "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 — its whole timeline, oldest first, which is what expanding a row\nof the tree loads.\n\nIts paging differs from the two variant reads: cursor paging only, no `from` and no `size`,\nand **no `hits`**.\n\nTwo paging facts a client gets wrong if it assumes otherwise. **A page may be shorter than\n`limit`, or empty, and still carry a `next`**, so a client pages until `next` is absent rather\nthan until a page looks short. And **a cursor belongs to one variant and one `order`**:\nreplaying one against another variant, or against the opposite order, is a `400` rather than a\nplausible-looking wrong page.\n\nVersions carry no `_revision` here. An editing screen re-reads the one version it is about to\nwrite through that version's own `GET`, which is strongly consistent, and writes with the\nrevision it returns.\n\n**Published ahead of the behaviour.** No handler serves this yet, so a deployed stage answers\n`501`.\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\nsilently. A variant's timeline is usually short enough to fit one page.\n", "schema": { "type": "integer", "minimum": 1, "default": 100 }, "required": false, "example": 100 }, { "in": "query", "name": "order", "description": "Which end of the timeline to read from: `asc` oldest first, `desc` newest first. Defaults\nto `asc`.\n\nBaked into every cursor this read issues: a cursor resumes one direction, and replaying it\nagainst the other is a `400`.\n", "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: it encodes the position and the order\nit was issued for, and nothing a client should read or construct.\n", "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 page shorter than `limit` says nothing about whether 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 only reliable 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": "A `cursor` that is malformed, belongs to another variant, or was issued for the opposite\norder is `CURSOR_INVALID`, with `details.reason` saying which. The fix is the same for all\nthree: read the timeline again without a cursor.\n\nA `limit` below 1 and an `order` that is neither `asc` nor `desc` carry a message and\nneither `code` nor `details`; testing `code` for absence is how they are told from the one\nabove.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`), no such entity under it (`ENTITY_NOT_FOUND`), or the\nentity has no such variant (`VARIANT_NOT_FOUND`) — which is also the answer for a variant\nbelonging to a *different* entity: a variant id alone addresses nothing.\n\nThe entity is established before the timeline is read, so a caller who mistyped the entity\nid is never sent to fix the variant id, and one who sent the wrong slug hears about the\nslug.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "501": { "description": "Published ahead of the behaviour. This operation is declared and not yet dispatched, so\nevery request to it is answered here until the listing behaviour lands — which is how a\ndeployed stage says \"this exists and does not work yet\" rather than answering with an\nempty page a client would read as an empty entity.\n\nRead `message`. The body is the shared `Error` shape, as it is on every 501 this API\nanswers, so one \"not built yet\" branch covers all of them.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "description": "Appends a version to a variant: a new set of values taking effect at its own instant.\n\nThis is how a price changes. No version carries an end date and nothing is superseded\nexplicitly — the version in effect at an instant is simply the one with the latest `valid_from`\nat or before it, so appending a later version is the whole of \"this is the new price from then\non\". A version dated in the future is staged and excluded from resolution until its date.\n\n**A version is never refused for being late.** A `valid_from` in the past is written like any\nother and answered with warnings in `warnings` naming what it moved — what resolves now, what a\npast-dated read returns, or both. Correcting a price that took effect last week is ordinary\nwork.\n\nWhat is refused is appending at a `valid_from` the variant already has: that write means either\n\"replace it\" or \"and also this\", and only the caller knows which. The two operations both\nexist, on the dated version path.\n\nThe variant's `conditions` are its identity and are fixed at creation; they may be sent back\nunchanged but never changed.\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": "The version cannot be appended as described: the body would change the variant's conditions,\nor `valid_from` is not a timestamp this store can sort by.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`), no entity with that id (`ENTITY_NOT_FOUND`), or no\nsuch variant under it (`VARIANT_NOT_FOUND`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "409": { "description": "The variant already has a version at that `valid_from` (`VERSION_CONFLICT`) — append means\nappend, never an implicit overwrite. Replace or patch that version instead.\n", "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 specific version of a variant, by the instant it takes effect — what a form editing\nthat version loads.\n\nExact, never nearest: an instant the variant has no version at is a not-found rather than the\nversion that would be in effect at it. That question is the shorthand read's, or `:resolve`'s.\n", "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.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision. Written any accepted way: it is\ncanonicalized before it is matched, so the spelling a read returned and the spelling a\nhuman typed address the same version.\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": "Invalid request, e.g. a `valid_from` that is not a timestamp this store can sort by.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No entity with that id (`ENTITY_NOT_FOUND`), no such variant under this schema\n(`VARIANT_NOT_FOUND`), or no version at that instant (`VERSION_NOT_FOUND`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } } } }, "put": { "description": "Replaces one version's values wholesale, addressed by its `valid_from`.\n\nEditable whatever its date, scheduled or past. Writing a superseded version is answered with a\nwarning naming what a past-dated read now returns; it is not refused.\n\nAttributes the variant may not override are not applied where the body carries them, and their\nstored value is preserved rather than dropped.\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.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision. Written any accepted way: it is\ncanonicalized before it is matched, so the spelling a read returned and the spelling a\nhuman typed address the same version.\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": "The write cannot be applied as described: it would move the version it addresses to another\n`valid_from`, or change the conditions its variant is pinned to — both identity rather than\ncontent, and both fixed at creation. Also when `_revision` is missing or is not a revision\nmarker.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`), no entity with that id (`ENTITY_NOT_FOUND`), no such\nvariant under it (`VARIANT_NOT_FOUND`), or no version at that instant\n(`VERSION_NOT_FOUND`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "409": { "description": "The version has been written since `_revision` was read (`WRITE_CONFLICT`, retryable after\nre-reading the version).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } } } }, "patch": { "description": "Changes only the fields it names on one version, addressed by its `valid_from`.\n\nEverything the body does not mention is left as stored. A partial update that tries to change a\npinned condition value is refused: condition values are immutable after a variant is created.\n", "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.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision. Written any accepted way: it is\ncanonicalized before it is matched, so the spelling a read returned and the spelling a\nhuman typed address the same version.\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": "The write cannot be applied as described: it would move the version it addresses to another\n`valid_from`, or change the conditions its variant is pinned to — both identity rather than\ncontent, and both fixed at creation. Also when `_revision` is missing or is not a revision\nmarker.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`), no entity with that id (`ENTITY_NOT_FOUND`), no such\nvariant under it (`VARIANT_NOT_FOUND`), or no version at that instant\n(`VERSION_NOT_FOUND`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "409": { "description": "The version has been written since `_revision` was read (`WRITE_CONFLICT`, retryable after\nre-reading the version).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } } } }, "delete": { "description": "Removes one version of a variant.\n\nWithdrawing a scheduled adjustment is what this is for, and deleting a future version warns\nabout nothing — nothing that has resolved, or could have resolved, changes. Deleting a version\nthat has taken effect is allowed too and answered with a warning: it changes what a past-dated\nread returns, and if it was the version in effect it changes what resolves now.\n\n**A variant's last remaining version cannot be deleted.** Such a variant would still hold its\ncondition tuple and still be selectable, and then resolve to nothing — which is a variant delete\nwearing a version delete's clothes. Delete the variant instead; that frees the tuple too.\n\nThe variant itself is untouched: it keeps its conditions, its tuple and its place in the index.\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.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision. Written any accepted way: it is\ncanonicalized before it is matched, so the spelling a read returned and the spelling a\nhuman typed address the same version.\n", "schema": { "type": "string" }, "required": true, "example": "2027-01-01T00:00:00.000Z" }, { "in": "query", "name": "_revision", "description": "The revision marker read from the version being deleted. The delete is refused if the\nversion has been written since.\n\nThe same marker the write bodies carry as `_revision`.\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": "The version cannot be removed because it is the variant's only one\n(`LAST_VERSION_UNDELETABLE`) — such a variant would keep its condition tuple, stay\nselectable and resolve to nothing, so delete the variant instead, which frees the tuple\ntoo.\n\nThe refusals around it carry no code, and testing `code` for absence is how they are told\nfrom it: a missing or unreadable `_revision`, a `valid_from` this store cannot sort by,\nand an id this store cannot key by.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No entity with that id (`ENTITY_NOT_FOUND`), no such variant under this schema\n(`VARIANT_NOT_FOUND`), or no version at that instant (`VERSION_NOT_FOUND`).\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "409": { "description": "The version has been written since `_revision` was read (`WRITE_CONFLICT`, retryable after\nre-reading the version).\n", "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 — the endpoint a bulk importer drives a\nrefresh cycle through, so hundreds of thousands of keys are a stream of calls rather than a\ncall per key.\n\n**One schema in the path, one entity per item.** A single call may name several entities, so\nit can refresh a whole tariff hierarchy — a composite price and its components together —\nand the entity id rides each item instead of the path.\n\n**An item addresses a condition tuple, never a `variant_id`.** An upsert creates a variant\nthat has no id yet. The id it created, or found, is on the result entry.\n\nEach item's outcome is derived from what is stored, with no mode for the caller to declare,\nin this order: an unknown tuple is `variant_created`, a known tuple with no version at the\nitem's `valid_from` is `version_created`, and an existing version at that exact instant is\n`updated` — or `skipped`, which is reserved for a write whose values are identical to what is\nstored, so re-running an unchanged import still reads as a no-op. `version_created` is\ndistinct from `variant_created` so an importer's counts can tell \"new postal codes appeared\"\nfrom \"existing variants got their scheduled adjustment\".\n\nAn item without `valid_from` is a current-state, last-write-wins write, and has no `skipped`\ndetection. A `valid_from` in the past changes nothing about the outcome — it is written like\nany other and answered with the timeline warnings on that item. An importer stamping one\n`valid_from` across a batch therefore sees backdate warnings on every item; omitting the\nfield is how it avoids them.\n\n**Items addressing the same variant apply in array order; items addressing different\nvariants are processed in parallel.** Here \"the same variant\" is the same `(entity_id,\ncondition tuple)`, so two items sharing a tuple and a `valid_from` apply in order and the\nlast one wins. There is no cross-item rollback.\n\n**This write is unguarded.** No `_revision` is accepted on an item or returned on an entry;\nan editing screen that needs a guard re-reads the one version it is about to write through\nits own `GET`.\n\nThree refusals a client would otherwise expect do not occur here. `VERSION_CONFLICT` never\ndoes: an existing `valid_from` is a replacement rather than a collision. A tuple-uniqueness\nguard lost to a concurrent writer is not reported as `TUPLE_CONFLICT` either — the item is\nre-read against current state and re-derived through the same outcome order above, which is\ncontent-aware. `WRITE_CONFLICT` marks the case that is genuinely worth retrying: transient\ncontention on one entity's rows.\n\n**Published ahead of the behaviour.** No handler serves this yet, so a deployed stage answers\n`501`. The examples below are what an importer builds against in the meantime.\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.\n\n`200` whatever the per-item outcomes: a batch that processed 100 items and failed 99 did\nits job, and `counts` says what happened.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchUpsertResult" }, "examples": { "Every outcome once": { "summary": "The five items above, in order — the created variant's id is the one an order pins, and item five failed on its own without touching the rest", "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 at all: more than 100 items, an empty `items`, a slug\nthat names no conditional entity type, or a body this schema rejects outright.\n\nAll of those are request-validation failures, so they carry a message and neither `code`\nnor `details`. Every failure of an individual item is on that item's result entry\ninstead, `ENTITY_NOT_FOUND` included — the entity id is on the item and not in the path,\nso one wrong id in a source file cannot fail the other 99 rows. `ENTITY_TYPE_MISMATCH`\nand `ENTITY_NOT_CONDITIONAL` are per item for the same reason: each item names its own\nentity, and each entity is checked against the slug and for `is_conditional` on its own.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`) — the one lookup the whole call depends on, since it\nis what the items are validated against.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "501": { "description": "Published ahead of the behaviour. This operation is declared and not yet dispatched, so\nevery request to it is answered here until the batch write behaviour lands — which is how\na deployed stage says \"this exists and does not work yet\" rather than answering with\ncounts a client would read as a completed import.\n\nRead `message`. The body is the shared `Error` shape, as it is on every 501 this API\nanswers, so one \"not built yet\" branch covers all of them.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/conditional-pricing/{slug}/variants:batchDelete": { "post": { "description": "Removes up to 100 variants or versions in one call — the symmetric bulk withdrawal, so\nretiring a generation of variants, or a scheduled adjustment across many of them, is as\ncheap as creating it was.\n\nThe noun is `variants` on both batch endpoints, although an item carrying `valid_from`\nremoves one **version** rather than the variant: an item without it removes the whole variant\n— its condition tuple, its registration in the index, and every version it accumulated — and\nan item with it removes exactly that version, under the single-item rules. A future version\nand a superseded one are both deletable and both answered with the warnings that say what\nmoved; a variant's last remaining version is refused\n(`LAST_VERSION_UNDELETABLE`), because such a variant would still hold its tuple and still\nresolve to nothing. Delete the variant instead.\n\n**An item addresses its variant one of two ways, and never both**: by `variant_id`, or by the\ncondition tuple it pins. Use ids once the schema has drifted: a tuple naming a condition the\nschema no longer declares cannot be canonicalized, so it addresses nothing. An item naming\nboth fails validation and is an envelope `400`, not a per-item error: the request validator\nrejects the body before any item runs.\n\n**`entity_id` is required beside a `variant_id`, and is not redundant.** A variant id alone\naddresses nothing in this API.\n\n**Items addressing the same variant apply in array order; items addressing different variants\nare processed in parallel.** Because an item addresses its variant two ways, \"the same\nvariant\" is decided after addressing, in three steps: every condition tuple is resolved to a\nvariant id, items are grouped by that id, and each group is applied in array order. So one\ncall may hold an item naming `var-46045` and an item naming the tuple that variant pins, and\nthe guarantee holds across both. There is no cross-item rollback.\n\n**An item that addresses nothing is `skipped` — but only when the variant or the version is\nwhat is missing.** A missing *entity* is a per-item `ENTITY_NOT_FOUND`.\n\nAn interrupted call is safe to send again. A whole-variant delete frees the tuple in its\nfirst phase and removes the version rows afterwards, so a re-run picks up where it stopped\nand reports `skipped` for what has already gone. Nothing is archived: a variant an order or\ncontract pins stops resolving, and a pinned `:resolve` naming it answers `VARIANT_NOT_FOUND`.\n\n**Published ahead of the behaviour.** No handler serves this yet, so a deployed stage answers\n`501`.\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.\n\n`200` whatever the per-item outcomes: the call did its job, and `counts` says what\nhappened.\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, so it names no variant to have skipped", "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 at all: more than 100 items, an empty `items`, a slug\nthat names no conditional entity type, an item naming both a `variant_id` and a condition\ntuple, or a body this schema rejects outright.\n\nAll of those are request-validation failures, so they carry a message and neither `code`\nnor `details`. Every failure of an individual item is on that item's result entry\ninstead, `ENTITY_NOT_FOUND` included, along with the per-entity `ENTITY_TYPE_MISMATCH`\nand `ENTITY_NOT_CONDITIONAL` — each item names its own entity, so each is checked on its\nown.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "404": { "description": "No such schema (`SCHEMA_NOT_FOUND`) — the one lookup the whole call depends on.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionalPricingError" } } } }, "501": { "description": "Published ahead of the behaviour. This operation is declared and not yet dispatched, so\nevery request to it is answered here until the batch delete behaviour lands — which is\nhow a deployed stage says \"this exists and does not work yet\" rather than answering with\ncounts a client would read as a completed cleanup.\n\nRead `message`. The body is the shared `Error` shape, as it is on every 501 this API\nanswers, so one \"not built yet\" branch covers all of them.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "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\nconditional-pricing route.\n", "enum": [ "product", "price", "coupon" ] }, "ConditionType": { "type": "string", "description": "The kind of value a condition holds, which decides how a variant's pinned value is matched\nagainst a resolve 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; both ends 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\nThere is no condition type for the fallback variant. Being the entity's fallback is a\nproperty of the variant, set by the `default` flag on a variant write, and needs nothing\ndeclared in the schema.\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\nverbatim.\n", "required": [ "id", "name", "label", "type" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Stable identity of the condition, round-tripped unchanged for the lifetime of the\ncondition: it is what tells a rename apart from a remove plus an add. The Entity API\nmints none of its own, so whoever creates a condition supplies one — a catalog condition\narrives with the identity the catalog gives it, the same in every org, and is copied into\nthe schema along with the rest of the object.\n", "example": "d5839b94-ba20-4225-a78e-76951d352bd6" }, "name": { "type": "string", "description": "How variants and resolve contexts refer to this condition. Independent of attribute\nnames: a value needed as an attribute too is duplicated onto the variant.\n\n`default`, and any name beginning with `_`, are reserved for the server: a condition\ndeclared under one is ignored, since nothing could pin it and no context could address it.\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 declared vocabulary of a `select` condition. Absent for every other type.\n\nThe same shape a `select` condition's `options` has on the Entity API, item for item: an\nentry is either the value itself or an object carrying that value and an optional display\n`title`. A `title` is never pinned by a variant and never matched — two entries differing\nonly in their title are one vocabulary entry.\n\nThe vocabulary is always closed: a condition carries no flag widening it, so a pinned\nvalue outside a declared vocabulary is rejected with `CONDITION_VALUE_INVALID`. A\nvocabulary that declares nothing is closed too — while `options` is absent or empty, or\nholds nothing this deploy can read, the condition admits no pin at all and the same code\nis returned with an empty `options`. It is *not* enforced on resolve — a vocabulary says\nwhat may be stored, not what may be asked for, so a context value outside it is a query\nthat simply 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": [ "zipcode", "zipcode_town" ] } } }, "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.\n", "items": { "$ref": "#/components/schemas/ConditionSet" } } } }, "ConditionalPricingErrorCode": { "type": "string", "description": "Machine-readable failure mode of a conditional-pricing operation, allowing clients\nto branch on the kind of failure instead of parsing the error message.\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` (400): 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): a resolve context, a listing filter or a variant's pins name a condition the entity's schema does not define\n- `OPERATOR_UNSUPPORTED` (400): the requested operator 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 the condition's `options` do not admit, including every pin on a condition whose `options` are absent, empty or unreadable\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` (400): 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` (400): the delete would leave the variant with no version at all\n\nIn a batch, the last four are the refusals an importer branches on: `VARIANT_LIMIT_REACHED`\nmeans stop the import, `PIN_FORMAT_INVALID` means one bad row, `LAST_VERSION_UNDELETABLE`\nmeans delete the variant instead.\n\nNot every refusal has a code. These carry a message and neither `code` nor `details`, and\neach operation's `400` names its own: a write pinning the reserved marker (`default` or\n`_default`), a variant marked `default` that also pins a real condition, a pin on a condition\nwhose declared type this deploy cannot read, an id this store cannot key by, a `valid_from`\nthis store cannot sort by, and a version write or delete with no `_revision`. Testing `code`\nfor absence is how a client tells them from the coded failures.\n\nFour of the 404s say that something the request addressed does not exist, and are fixed by\ncorrecting an id or accepting the thing is gone. The other two say the opposite: everything\naddressed exists and there is still nothing to serve — no variant applies to this situation,\nor none of a variant's versions is in effect yet. Those are ordinary business outcomes, told\napart from a wrong id by their code.\n\n`ENTITY_TYPE_MISMATCH` and `ENTITY_NOT_CONDITIONAL` are `400`s, not 404s: the entity the\nrequest addressed **was** found, and the fix is the slug beside it. A slug that names no\nconditional entity type at all is a `400` too.\n\nEach code is emitted with the HTTP status shown above, and only with that status, and each\none is pinned by a member of `ConditionalPricingError` — which is where the structured data\nthat code carries is declared.\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", "OPERATOR_UNSUPPORTED", "CONTEXT_FORMAT_INVALID", "CONDITION_VALUE_INVALID", "TOO_MANY_MATCHES", "WRITE_CONFLICT", "OFFSET_WINDOW_EXCEEDED", "CURSOR_INVALID", "VARIANT_LIMIT_REACHED", "PIN_FORMAT_INVALID", "VARIANT_UNPINNED", "LAST_VERSION_UNDELETABLE" ] }, "ResolveConditionalEntityRequest": { "description": "A resolve names one conditional entity, then says which of its variants it means — one of two\nways, and never both. `context` describes a situation and asks which variants apply to it;\n`variant_id` names one variant and skips matching entirely.\n\nA body carrying both, or neither, is a validation `400`. Asking for the default variant\nwithout knowing its id is `context: {}`, which matches nothing and therefore falls back to it.\n\nEverything below the variant selection is the same on both branches, `as_of` included.\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 than this is\nscheduled rather than applicable, and is excluded from resolution entirely.\n\nThat exclusion belongs to context matching only: a set of results may quietly drop a\nmember, where a pin naming one variant cannot answer with silence and is told\n`NO_ACTIVE_VERSION` instead.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond 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. What an\norder needs to show the numbers a customer agreed to, and what a contract needs to show what\nis billable now — the two differ only in whether `as_of` is supplied.\n", "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 entirely: no `context` is read, the\n`default` fallback does not apply, and `results` carries exactly one entry — a pin asks\nfor one variant by name.\n\nA `variant_id` this entity has no variant under is `VARIANT_NOT_FOUND`, and so is one\nnaming a variant of a different entity: a variant id alone addresses nothing.\n`SCHEMA_NOT_FOUND` and `ENTITY_NOT_FOUND` are still answered ahead of both.\n\n**Published ahead of the behaviour.** Until the pinned path is built, a body carrying\nthis field is answered `501`, ahead of every check above — the field exists so consumers\ncan build against it, and declining it is how a deployed stage says so rather than\nquietly returning the `default` variant.\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. The same selector, by the same rule, as on a context resolve:\nhow the variant was chosen is orthogonal to which of its versions applies, so a caller\nreplaying a recorded resolution instant supplies it here.\n\nA pinned variant whose first version is later than this is `NO_ACTIVE_VERSION`, carrying\nthe instant in `details.as_of`, rather than being dropped the way context matching drops\na scheduled variant.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision.\n", "example": "2027-03-15T00:00:00Z" }, "options": { "$ref": "#/components/schemas/PinnedResolveOptions" } } }, "ResolveContext": { "type": "object", "additionalProperties": true, "description": "The situation to resolve for: a flat map keyed by condition name, as the entity's schema\ndeclares them. A condition left out of the map is not a wildcard — it matches only variants\nthat leave that condition unpinned.\n\nEach value is either an exact value, typed by its condition, or a single-operator predicate\nobject:\n\n- `{ \"lt\": v }`, `{ \"lte\": v }`, `{ \"gt\": v }`, `{ \"gte\": v }` — order against a `number` or\n `date` condition.\n- `{ \"in\": [...] }` — membership, against a `string`, `select` or `number` condition.\n- `{ \"between\": \"2026-03-01\" }` — the explicit spelling of `daterange` containment; a plain\n date supplied for a `daterange` condition means the same thing.\n- `{ \"exists\": true }` — pinned to any value. `{ \"exists\": false }` says what leaving the key\n out says.\n\nAn `in` list carries at most 50,000 values; a longer one is `CONTEXT_FORMAT_INVALID`. To match\na condition whatever its value, send `{ \"exists\": true }` rather than enumerating its\nvocabulary.\n\nExact values are typed by their condition: a `string` or `select` matches exactly and\ncase-sensitively, with no trimming; a `location` of format `zipcode` is the postal code\nitself, and one of format `zipcode_town` an object carrying both, whose town is compared\ncase- and whitespace-insensitively while its postal code is not.\n\n`default`, and any name beginning with `_`, are reserved for the server and cannot be\nsupplied here.\n\nAn empty map is valid and means what it says: it supplies no value, so it matches no variant\nthat pins a condition, and the entity's `default` variant is what comes back. It is the only way to\nask for the default variant without knowing its id.\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 `AMBIGUOUS_RESOLUTION`\nrather than a set, and nothing applicable becomes `NO_MATCHES` rather than an empty one.\nThe response shape does not change: `results` simply carries exactly one entry.\n" }, "hydrate": { "type": "boolean", "default": false, "description": "Return the entities a relation attribute references in place of the references\nthemselves, one level deep, exactly as an entity read with hydration does.\n\nA fetch, not a second resolution: a referenced entity comes back as it is read, and one\nthat is itself conditional carries its own flag — acting on that is the consumer's\nchoice, and this API does not resolve it on their behalf.\n\nApplied after composition, so a relation attribute whose value this variant's version\nreplaced is hydrated too. That is what makes a composite price work: the override\nreferences different component *entities*, which exist only in the composed payload.\n\nA reference that cannot be fetched comes back exactly as entity hydration returns it —\nno drop, no failure, and no field reporting it. A resolved payload behaves as an entity\nof the same shape would, and the discriminators are the only difference.\n\nCosts one fetch per referenced entity per result, and carries no cap of its own: the\nper-attribute limits are entity hydration's, and the 100-result cap on the resolve itself\nis unchanged.\n\n**Published ahead of the behaviour.** Until hydration is built, `true` is answered `501`\nrather than served as unhydrated references; `false`, which asks for what this path\nalready does, resolves normally.\n" } } }, "PinnedResolveOptions": { "type": "object", "additionalProperties": false, "description": "The options a pinned resolve accepts — `hydrate` and nothing else. `resolve_one` has nothing\nto change on this branch, where the answer is exactly one result or a 404, so a body sending\nit is a validation `400`. `hydrate` means what `ResolveOptions.hydrate` means.\n", "properties": { "hydrate": { "type": "boolean", "default": false, "description": "Return the entities a relation attribute references in place of the references\nthemselves, one level deep, exactly as an entity read with hydration does.\n\nA fetch, not a second resolution: a referenced entity comes back as it is read, and one\nthat is itself conditional carries its own flag — acting on that is the consumer's\nchoice, and this API does not resolve it on their behalf.\n\nApplied after composition, so a relation attribute whose value this variant's version\nreplaced is hydrated too. That is what makes a composite price work: the override\nreferences different component *entities*, which exist only in the composed payload.\n\nA reference that cannot be fetched comes back exactly as entity hydration returns it —\nno drop, no failure, and no field reporting it. A resolved payload behaves as an entity\nof the same shape would, and the discriminators are the only difference.\n\nCosts one fetch per referenced entity per result, and carries no cap of its own: the\nper-attribute limits are entity hydration's, and the 100-result cap on the resolve itself\nis unchanged.\n\n**Published ahead of the behaviour.** Until hydration is built, `true` is answered `501`\nrather than served as unhydrated references; `false`, which asks for what this path\nalready does, resolves normally.\n" } } }, "ResolvedVariants": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "description": "One composed payload per applicable variant, capped at 100 — a context selecting more\nthan that is answered with `TOO_MANY_MATCHES` instead. No dominance or specificity\nordering is applied between them.\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 saying where the numbers\ncame from.\n\nWith `options.hydrate`, a relation attribute holds the entities it references rather than the\nreferences themselves. That changes what an attribute holds, not the payload's shape, so\nnothing is declared here for it.\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. Resolution never\nmints a new identity; a variant is a set of values for *this* entity, not another one.\n", "example": "price-sp26d1yo" }, "_variant_id": { "type": "string", "description": "The variant these values came from. Durable: this is what an order or a contract pins to\nread the same numbers back later.\n", "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.\n" }, "_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 — a client reads its length rather than branching on its\nabsence, the same way it reads a write's `warnings`.\n\nComputed per read from the schema as it stands, never stored, so granting or withdrawing\n`overridable_attribute` changes what resolves — and this list — without any data being\nrewritten. A version read reports what is stored and carries no such list; this is the\nonly surface that honours the schema.\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: the one served when no other variant applies.\n\nA property of the variant, never an entry in `conditions`. A default variant cannot pin\nanything else, and an entity can have at most one; a second is refused as\n`TUPLE_CONFLICT`.\n\nAvailable to every conditional entity: nothing has to be declared in the schema first.\n" }, "valid_from": { "type": "string", "description": "When the first version takes effect. Defaults to now.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision.\n", "example": "2027-01-01T00:00:00Z" }, "values": { "$ref": "#/components/schemas/VariantValues" } } }, "VariantConditions": { "type": "object", "additionalProperties": true, "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\n`default` is always present and always a boolean, so a client can branch on \"did I get the\nfallback?\" without knowing how one is stored. The reserved condition a fallback is actually\npinned under never appears here.\n", "properties": { "default": { "type": "boolean" } }, "example": { "postal_code": "46045", "default": false } }, "PinnedConditions": { "type": "object", "additionalProperties": true, "description": "The situation this variant applies to: a flat map keyed by condition name, as the entity's\nschema declares them. A condition left out is a wildcard — the variant applies whatever the\ncontext says for it, which is what makes adding a condition to a schema non-breaking for the\nvariants that already exist.\n\nExact values only. A predicate is a read-side thing — a resolve context or a listing's\ncondition filter — and is never stored: what a variant applies to is one situation, not a\nrange of them.\n\nValues are typed by their condition and stored canonicalized for that type: a `date` becomes\nmillisecond-precision UTC, a `daterange` an object carrying `from` and `until` where an empty\nstring is an open end, a `location` of format `zipcode` the postal code itself and one of\nformat `zipcode_town` an object carrying both. A `select` value must be a string, and must\nbe one the condition's `options` declare, which is always a closed vocabulary.\n\n`default`, and any name beginning with `_`, are reserved for the server and cannot be pinned\nhere. Whether a variant is the entity's fallback is set through the request's `default` flag.\n", "example": { "postal_code": "46045" } }, "VariantValues": { "type": "object", "additionalProperties": true, "description": "The attribute values this version overrides on the base entity, keyed by attribute name.\n\nOnly attributes currently declaring `overridable_attribute` are applied. Metadata fields\n(anything underscore-prefixed), readonly attributes, hidden attributes, computed attributes,\nattributes of a type no variant may override and non-overridable attributes present here are\nnot applied rather than rejected, and every one but the metadata is named in the write's\n`warnings`, so a client working from a slightly stale schema snapshot still succeeds instead\nof failing on fields it could not have known to drop, and still learns which of them did not\nland. Metadata is never named, since a client echoing back a payload it read carries it in\nevery body. An attribute's `render_condition` says when to show it and has no\nbearing on whether a variant may override it.\n\nNot applied means *not updated*, never *removed*: a value already stored for an attribute that\nis not currently overridable is preserved, so removing and restoring the flag deactivates and\nthen reactivates the same override. An append seeds the attributes the variant may not\noverride from the version in effect at its own `valid_from`, so its stored values are not a\npure function of the body that wrote it; a variant's first version, and an append dated before\nthe variant's earliest version, inherit nothing.\n\nA composite price's `price_components` is an ordinary overridable relation attribute. A\ncomposite variant's override references different component *entities*, never a variant or a\nversion of one, and holds whatever a relation attribute ordinarily holds — this API defines no\nreference shape of its own.\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, always, and never accepted from a client. This is the durable key orders\nand contracts pin.\n", "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 — the\nsame shape `_conditions` has on a resolved payload.\n" }, "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 to be accepted.\n", "readOnly": true }, "warnings": { "type": "array", "description": "Things worth knowing that did not stop the write. Empty in the ordinary case — a client\nreads its length rather than branching on its absence.\n", "items": { "$ref": "#/components/schemas/WriteWarning" } } } }, "WriteWarning": { "description": "Something worth knowing that did not stop a write.\n\nOne vocabulary for every write, so a client branches on what happened rather than on which\nendpoint it called. `code` and `message` are the only two fields every code shares; everything\nelse lives in a `details` object typed per code, so narrowing on `code` yields a payload the\nclient can read rather than an untyped bag. A write raises each code at most once, and in the\nordinary case raises none of them.\n", "oneOf": [ { "type": "object", "additionalProperties": false, "description": "This entity is nearing the number of variants it may hold. Surfaced rather than rejected,\nso an importer finds out with a whole run's notice instead of discovering the limit\nhalfway through a refresh.\n", "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, the same value for every\norganization on it.\n" } } } } }, { "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. The version in effect is one of those whenever its own date has\npassed, which is the ordinary case — it covers every instant from that date until now. A\nversion dated now or later covers no past instant and is not reported here.\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, whatever the reason.\nThe write itself succeeded: an attribute a variant may not override is left alone rather\nthan making the whole call fail, so a client working from a slightly stale schema snapshot\nstill succeeds instead of failing on fields it could not have known to drop.\n\nOne entry per attribute, each with its own reason, so a client that only cares about typos\nfilters the entries by `reason` rather than branching on a second code.\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" } } } } } } ] }, "VersionMoved": { "type": "object", "additionalProperties": false, "description": "Which version a write moved, and which one was in effect while it did.\n", "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 — every version of it still scheduled.\n\nMay lag the variant's timeline by milliseconds, so a version written moments earlier may\nnot be named here. Advisory, like the warning carrying it: nothing branches on it except a\nhuman reading the message.\n", "example": "2026-01-01T00:00:00.000Z" } } }, "InertOverride": { "type": "object", "additionalProperties": false, "description": "One override that did not apply, and why.\n\nThe same entry on both sides of the feature: a write reports the attributes in its body it did\nnot store, and a resolved payload reports the stored overrides composition did not apply. Those\nare the same fact observed at two moments, so a client learns one shape and reads it in both\nplaces.\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 entity's schema declares the attribute but has not granted\n it `overridable_attribute`. Granting the flag is an ordinary schema edit, which makes this\n the reason most often worth acting on.\n- `ATTRIBUTE_READONLY`: the attribute is declared readonly, and a readonly attribute cannot\n be granted the flag.\n- `ATTRIBUTE_HIDDEN`: the attribute is declared hidden, and a hidden attribute cannot be\n granted the flag.\n- `ATTRIBUTE_COMPUTED`: the attribute's value is derived (`type: computed` or\n `computed: true`) rather than stored, so an override would be recomputed away.\n- `ATTRIBUTE_UNDECLARED`: the entity's schema declares no attribute of that name. On a write\n that is usually a typo; on a resolved payload it is a stored override whose attribute has\n since left the schema — a stored value outlives the flag being withdrawn, so it can outlive\n its own attribute too. This API keeps no record of what a schema once declared, so it states\n only the observable fact and does not distinguish the two.\n- `TYPE_NOT_OVERRIDABLE`: the attribute's type is not one a variant may override, whatever\n the schema says about that particular attribute.\n- `CAPABILITY_NOT_OVERRIDABLE`: the attribute is contributed by a capability rather than\n declared on the entity's schema. Published for completeness and not emitted in this version,\n in which no capability attribute can be overridden at all.\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 is the one that freed the variant's combination of condition values.\n`false` where an earlier, interrupted attempt had already freed it — the delete still\nsucceeded, and the combination was already reusable.\n" }, "versions_deleted": { "type": "number", "description": "Version rows this call removed." } } }, "VariantVersion": { "type": "object", "description": "One version of one variant: the attribute overrides it carries, the instant it takes effect,\nand the variant it belongs to.\n\nThese are the version's **own** overrides, not the base entity overlaid with them — this is\nwhat an editing screen loads and saves, and what it edits is the overrides. Composing them onto\nthe entity is what `:resolve` answers.\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 property\nof the variant rather than of this version: every version of a variant carries the same\none, and no version write can change it.\n" }, "valid_from": { "type": "string", "description": "When this version takes effect, canonicalized to millisecond-precision UTC. A version's\nidentity within its variant — it never moves.\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 to be accepted. Always current: every read\nthat returns one is strongly consistent, so it is never a marker a write would be refused\nfor having read too early.\n", "readOnly": true, "example": 3 } } }, "WrittenVariantVersion": { "description": "A version as a write left it, together with anything the write moved.\n", "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. Empty in the\nordinary case — a client reads its length rather than branching on its absence.\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, if anything. Empty when a scheduled version was withdrawn — a\nclient reads its length rather than branching on its absence.\n", "items": { "$ref": "#/components/schemas/WriteWarning" } } } }, "AppendVersionRequest": { "type": "object", "additionalProperties": false, "required": [ "values" ], "properties": { "valid_from": { "type": "string", "description": "When this version takes effect. Defaults to now.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision.\n\nA date in the past is accepted and answered with warnings, never refused. A date the\nvariant already has a version at is refused as `VERSION_CONFLICT`.\n\n**Omit this to mean \"now\"** — that is the only spelling of now that is reliably silent. A\ntimestamp taken from the caller's own clock is already some milliseconds old when the\nserver judges it, which makes it a backdate, however small, and it is answered with the\nwarnings a backdate earns.\n", "example": "2027-01-01T00:00:00Z" }, "values": { "allOf": [ { "$ref": "#/components/schemas/VariantValues" } ], "description": "The attribute overrides this version carries. An append seeds the attributes the variant\nmay not override from the version in effect at this version's own `valid_from` and then\napplies these values over them, so the stored values are not a pure function of this\nbody. An append dated before the variant's earliest version inherits nothing.\n" }, "conditions": { "allOf": [ { "$ref": "#/components/schemas/PinnedConditions" } ], "description": "Optional, and never applied: a variant's conditions are fixed when it is created. Accepted\nonly so that a client building its body from the version it loaded is not forced to strip\nthem out, and refused when they describe a different situation from the stored one.\n" } } }, "ReplaceVersionRequest": { "type": "object", "additionalProperties": false, "required": [ "values", "_revision" ], "properties": { "values": { "allOf": [ { "$ref": "#/components/schemas/VariantValues" } ], "description": "The complete set of attribute overrides this version carries. An overridable attribute\nabsent from here stops being overridden.\n\nAttributes the variant may not override are not applied where this carries them, and\ntheir **stored value is kept rather than dropped**.\n" }, "_revision": { "type": "integer", "minimum": 1, "description": "The revision marker read from the version being written. The write is refused with\n`WRITE_CONFLICT` if the version has been written since.\n", "example": 3 }, "valid_from": { "type": "string", "description": "Optional, and never applied. Accepted when it names the version being addressed — so a\nclient building its body from what it loaded need not strip it out — and refused when it\nnames another: a version's `valid_from` is its identity, and moving it is an append and a\ndelete rather than an edit.\n" }, "conditions": { "allOf": [ { "$ref": "#/components/schemas/PinnedConditions" } ], "description": "Optional, and never applied: a variant's conditions are fixed when it is created. Refused\nwhen they describe a different situation from the stored one.\n" } } }, "PatchVersionRequest": { "type": "object", "additionalProperties": false, "required": [ "values", "_revision" ], "properties": { "values": { "allOf": [ { "$ref": "#/components/schemas/VariantValues" } ], "description": "Only the attribute overrides to change. Everything not mentioned is left as stored.\n\n`null` is a value like any other here rather than a deletion; to stop overriding an\nattribute, send the complete snapshot without it through the replace operation.\n" }, "_revision": { "type": "integer", "minimum": 1, "description": "The revision marker read from the version being written. The write is refused with\n`WRITE_CONFLICT` if the version has been written since.\n", "example": 3 }, "valid_from": { "type": "string", "description": "Optional, never applied, and refused when it names a version other than the one addressed." }, "conditions": { "allOf": [ { "$ref": "#/components/schemas/PinnedConditions" } ], "description": "Optional, and never applied. A partial update that tries to change a pinned condition value\nis refused.\n" } } }, "ListVariantsRequest": { "type": "object", "additionalProperties": false, "description": "How to narrow and page a variant listing. Every property is optional, so `{}` is a valid body\nand asks for the first ten variants of the entity in `variant_id` order — the body itself is\nrequired, and an omitted one is a request-validation `400` rather than an unnarrowed page.\n\n`conditions` and `search` narrow independently and a variant has to satisfy both.\n", "properties": { "conditions": { "$ref": "#/components/schemas/VariantConditionFilter" }, "search": { "type": "string", "description": "Free text matched against the variant's pinned values — how someone finds one postal code\namong 800,000.\n\nMatches `string`, `select` and `number` pins only. A `location` pin is stored as an array\nof its format's parts and a `daterange` pin as an object carrying `from` and `until`, so\nneither is text a user could have typed.\n", "example": "460" }, "sort": { "type": "string", "description": "`conditions.:asc` or `conditions.:desc`, for a `string`, `select`, `number` or\n`date` pin. Anything else — another field, or a pin of another type — is a `400`.\n\n**`variant_id:asc` is appended by the server**, always, so the order is total: many\nvariants can pin one postal code, and without a tiebreaker a cursor would repeat or skip\nrows between pages. Asking for no sort is `variant_id:asc` alone.\n", "example": "conditions.postal_code:asc" }, "from": { "type": "integer", "minimum": 0, "default": 0, "description": "The offset to read from. Not read when a `cursor` is sent, which carries its own position.\n\nBounded by the search index's offset window, together with `size`: the window bounds the\nlast row a page may contain, so the final servable offset is the window minus the page\nsize. A page reaching past it is `OFFSET_WINDOW_EXCEEDED`, naming all three numbers,\nrather than a page clamped back inside it as entity listing does. The window is the\ndeploy's: read its size from the error, not from here.\n" }, "size": { "type": "integer", "minimum": 1, "default": 10, "description": "Rows per page. Clamped silently at 1000, as entity listing's is.\n" }, "cursor": { "type": "string", "description": "Continue from a previous response's `next`, which is where a caller goes when the offset\nwindow runs out. Opaque: it encodes the position and the listing it was issued for, and\nnothing a client should read or construct.\n\n`conditions`, `search` and `sort` must be the ones the cursor was issued with — a cursor\nresumes one listing, and cannot mean anything against a different one. A cursor that is\nmalformed, or does not match the listing it is sent with, is a `400`.\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 shared property means what it means on the list.\n", "properties": { "conditions": { "$ref": "#/components/schemas/VariantConditionFilter" }, "search": { "type": "string", "description": "Free text matched against the variant's pinned values — how someone finds one postal code\namong 800,000.\n\nMatches `string`, `select` and `number` pins only. A `location` pin is stored as an array\nof its format's parts and a `daterange` pin as an object carrying `from` and `until`, so\nneither is text a user could have typed.\n", "example": "460" }, "sort": { "type": "string", "description": "`conditions.:asc` or `conditions.:desc`, for a `string`, `select`, `number` or\n`date` pin. Anything else — another field, or a pin of another type — is a `400`.\n\n**`variant_id:asc` is appended by the server**, always, so the order is total: many\nvariants can pin one postal code, and without a tiebreaker a cursor would repeat or skip\nrows between pages. Asking for no sort is `variant_id:asc` alone.\n", "example": "conditions.postal_code:asc" }, "from": { "type": "integer", "minimum": 0, "default": 0, "description": "The offset to read from. Not read when a `cursor` is sent, which carries its own position.\n\nBounded by the search index's offset window, together with `size`: the window bounds the\nlast row a page may contain, so the final servable offset is the window minus the page\nsize. A page reaching past it is `OFFSET_WINDOW_EXCEEDED`, naming all three numbers,\nrather than a page clamped back inside it as entity listing does. The window is the\ndeploy's: read its size from the error, not from here.\n" }, "size": { "type": "integer", "minimum": 1, "default": 10, "description": "Rows per page. Clamped silently at 100, a tenth of the variants list's cap: every row here\ncosts its own version lookup.\n" }, "cursor": { "type": "string", "description": "Continue from a previous response's `next`, which is where a caller goes when the offset\nwindow runs out. Opaque: it encodes the position and the listing it was issued for, and\nnothing a client should read or construct.\n\n`conditions`, `search` and `sort` must be the ones the cursor was issued with — a cursor\nresumes one listing, and cannot mean anything against a different one. A cursor that is\nmalformed, or does not match the listing it is sent with, is a `400`.\n", "example": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0" }, "as_of": { "type": "string", "description": "The instant each row's version is selected at — the version with the latest `valid_from`\nat or before it. Defaults to now. The same selector, by the same rule, as `:resolve`'s.\n\nA variant whose first version is later than this is not dropped the way context matching\ndrops it: it is a row with `status: scheduled` carrying that upcoming first version, which\nis what makes a staged price visible on the editing screen.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision.\n", "example": "2027-03-15T00:00:00Z" } } }, "VariantConditionFilter": { "type": "object", "additionalProperties": true, "description": "Which pins a variant must carry to be listed: a flat map keyed by condition name, as the\nentity's schema declares them. A condition left out of the map is not filtered on at all.\n\nEach value is either an exact value, typed by its condition, or a single-operator predicate\nobject — the same seven a resolve context accepts, because in both cases a predicate is\napplied to the variant's *pinned* value, so nothing about matching moves:\n\n- `{ \"lt\": v }`, `{ \"lte\": v }`, `{ \"gt\": v }`, `{ \"gte\": v }` — order against a `number` or\n `date` condition.\n- `{ \"in\": [...] }` — membership, against a `string`, `select` or `number` condition.\n- `{ \"between\": \"2026-03-01\" }` — the explicit spelling of `daterange` containment; a plain\n date supplied for a `daterange` condition means the same thing.\n- `{ \"exists\": true }` — pinned to any value. `{ \"exists\": false }` — the condition left\n unpinned.\n\nAn `in` list carries at most 50,000 values; a longer one is `CONTEXT_FORMAT_INVALID`. To\nfilter on a condition whatever its pinned value, send `{ \"exists\": true }` rather than\nenumerating its vocabulary.\n\n**A variant matches only where it pins the condition** — the one place a filter and a resolve\ncontext differ. On `:resolve` a condition a variant does not pin matches any value; here,\nasking for postal code 46045 does not return the variants that pin no postal code at all.\n`{ \"exists\": false }` is how those are asked for.\n\nValues are typed and canonicalized exactly as a resolve context's are, by the same code, so\none instant written two ways filters the same way either way. A condition the schema does not\ndeclare is `CONDITION_UNDEFINED`, a predicate its type does not support is\n`OPERATOR_UNSUPPORTED`, and a value malformed for its type is `CONTEXT_FORMAT_INVALID`.\n\n**`default` is accepted here**, as the exact boolean every row reports it as: `true` selects\nthe entity's fallback variant, `false` every variant that is not it.\n\nIt takes no predicate. `default` is not a condition and has no type, so ordering and\nmembership have nothing to apply to. It is also the one key the pinned-only rule above does\nnot describe literally: a variant that is not the fallback does not pin the marker to `false`,\nit does not pin it at all, so `false` selects the variants that leave it unpinned.\n\nNames beginning with `_` stay reserved for the server and cannot be filtered on — `_default`,\nthe marker a fallback is actually stored under, included. `default` is the spelling every read\nreports and the only one this accepts.\n", "example": { "postal_code": "46045", "consumption": { "lt": 5000 } } }, "VariantList": { "type": "object", "required": [ "hits", "results" ], "properties": { "hits": { "type": "integer", "description": "How many variants match, exactly, at any depth — not how many this page carries. Exact,\nas entity listing's is.\n", "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 `cursor`,\nwith 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.\n\nNo `_revision` — a write re-reads its version through that version's own `GET` — and no\n`_inert_overrides`, since a listing reports what is stored and only `:resolve` honours the\nschema.\n", "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 — the same\nshape a variant write returns.\n\nMay lag: a variant just created can be missing from a page, and one just deleted can still\nbe on it. The pins shown for a variant are never stale, since a variant's conditions are\nimmutable after creation.\n" } } }, "VariantTree": { "type": "object", "required": [ "hits", "results" ], "properties": { "hits": { "type": "integer", "description": "How many variants match, exactly, at any depth — not how many this page carries. Exact,\nas entity listing's is.\n", "example": 8128 }, "results": { "type": "array", "description": "One row per matching variant, in the requested order.\n\nA variant the index still holds but whose versions are already gone — a variant\nmid-delete — is **omitted** rather than returned without a `version`. So `results` can be\nshorter than `hits` implies, for the width of that lag and no longer. Paging still ends\nwhere `next` does.\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 `cursor`,\nwith the same filter, search and sort.\n\n`as_of` is free to change between pages. It selects which version each row shows and has\nno bearing on which variants match or on the order they come back in, so a screen whose\ndate picker moves mid-listing keeps paging rather than starting over.\n", "example": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0" } } }, "VariantTreeRow": { "type": "object", "description": "A listing row plus the one version the tree view shows for it, and the status saying which\nversion that is.\n", "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 — the same\nshape a variant write returns.\n\nMay lag: a variant just created can be missing from a page, and one just deleted can still\nbe on it. The pins shown for a variant are never stale, since a variant's conditions are\nimmutable after creation.\n" }, "status": { "$ref": "#/components/schemas/VariantTreeRowStatus" }, "version": { "allOf": [ { "$ref": "#/components/schemas/VariantVersionSnapshot" } ], "description": "The version this row shows: the one in effect at `as_of`, or — where every version of the\nvariant is still ahead of it — that upcoming first one. `status` says which of the two it\nis.\n\nAlways present. A variant always has at least one version, and the one case where a row\ncould have none — a variant whose delete has removed its versions but not yet its index\ndocument — is omitted from `results` instead, so a consumer never reads this field\ndefensively.\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\nExactly two values, and every row has one: a variant always has at least one version, so\neither a version is in effect at `as_of` or every version of that variant is still to come.\n\n- `active`: `version` is the version with the latest `valid_from` at or before `as_of` —\n the same version `active_valid_from` and `NO_ACTIVE_VERSION` speak of.\n- `scheduled`: the variant's first version is later than `as_of`, and `version` is that\n upcoming first version.\n", "enum": [ "active", "scheduled" ] }, "VariantVersionSnapshot": { "type": "object", "description": "One version of one variant as a listing reports it: `VariantVersion` without `_revision`.\n\nThe revision is missing on purpose. An editing screen re-reads the one version it is about to\nwrite through that version's own `GET`, which is strongly consistent, and writes with the\nrevision it gets back.\n\nEverything else is `VariantVersion` field for field, including the variant's `conditions`,\nwhich every version of a variant repeats.\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 property\nof the variant rather than of this version: every version of a variant carries the same\none, and no version write can change it.\n" }, "valid_from": { "type": "string", "description": "When this version takes effect, canonicalized to millisecond-precision UTC. A version's\nidentity within its variant — it never moves.\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`.\n", "items": { "$ref": "#/components/schemas/VariantVersionSnapshot" } }, "next": { "type": "string", "description": "The cursor that continues this timeline, absent only on the last page.\n\nThe only end-of-data signal: a page shorter than `limit`, or an empty one, can still carry\na cursor, so a client pages until this field is absent rather than until a page looks\nshort. Send it back as `cursor`, against the same variant and the same `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.\n", "required": [ "items" ], "properties": { "correlation_id": { "type": "string", "description": "An opaque string the caller uses to tie this response to the file and cycle that produced\nit. Echoed back verbatim, only when it was sent, and never interpreted.\n", "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 — a limit on one request, distinct from the per-entity\nvariant cap, which limits stored state.\n", "items": { "$ref": "#/components/schemas/BatchUpsertItem" } } } }, "BatchUpsertItem": { "type": "object", "additionalProperties": false, "description": "One variant write: the entity it belongs to, the situation it applies to, and the values it\ncarries — the single-item create's body plus `entity_id`. The two differ on `conditions`: on\na create an existing tuple is `TUPLE_CONFLICT`, and here it is a version appended to the\nvariant already holding it.\n\nThere is no `variant_id`. An upsert creates variants that have no id yet.\n", "required": [ "entity_id", "values" ], "properties": { "entity_id": { "type": "string", "description": "The conditional entity this item writes to. On the item rather than in the path, so one\ncall can refresh a whole tariff hierarchy — a composite price and its components\ntogether.\n", "example": "price-sp26d1yo" }, "conditions": { "$ref": "#/components/schemas/PinnedConditions" }, "default": { "type": "boolean", "default": false, "description": "Mark this variant as the entity's fallback, exactly as a create does: a property of the\nvariant, never an entry in `conditions`. An item that pins nothing and is not the default\nis `VARIANT_UNPINNED` — the empty postal-code column in a source file.\n" }, "valid_from": { "type": "string", "description": "When the version this item writes takes effect. Omitted, it is a current-state,\nlast-write-wins write with no `skipped` detection.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision.\n\nA past instant is written like any other and answered with the timeline warnings on this\nitem, so an importer stamping one `valid_from` across a batch sees them on every item.\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\nremoves from.\n", "required": [ "items" ], "properties": { "correlation_id": { "type": "string", "description": "An opaque string the caller uses to tie this response to the file and cycle that produced\nit. Echoed back verbatim, only when it was sent, and never interpreted.\n", "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 — which is decided after every condition tuple has been resolved to a variant id,\nso the order holds across the two addressing forms. At most 100 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.\n\nExactly one of the two forms. An item carrying both a `variant_id` and `conditions` matches\nneither branch and is an envelope `400`, since the request validator rejects the body before\nany item runs.\n", "oneOf": [ { "$ref": "#/components/schemas/BatchDeleteByVariantId" }, { "$ref": "#/components/schemas/BatchDeleteByConditions" } ] }, "BatchDeleteByVariantId": { "type": "object", "additionalProperties": false, "description": "A delete addressing its variant by id — the form a cleanup pass uses after the schema has\ndrifted, since a tuple naming a condition the schema no longer declares addresses nothing.\n", "required": [ "entity_id", "variant_id" ], "properties": { "entity_id": { "type": "string", "description": "The conditional entity the variant belongs to. **Required beside `variant_id`, and not\nredundant**: a variant id alone addresses nothing in this API.\n", "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 — its tuple, its index registration and every version it accumulated.\n\nAn RFC 3339 date or date-time, to at most millisecond precision, canonicalized before it\nis 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 — the form an importer uses\nwhen it knows the source rows rather than the ids they produced.\n\n`conditions` is optional because the entity's fallback variant pins nothing: an item\naddressing it sends `default: true` and no `conditions`, exactly as a create marks one.\n\n**An item that addresses no variant is a per-item `VARIANT_UNPINNED`, not an envelope\n`400` and not a `skipped`.** Three shapes reach it: no `conditions` and no `default`,\n`conditions: {}`, and `default: false` alone — an empty postal-code column in a source row,\nserialized one way or another.\n\nTwo more shapes validate here and are refused per item rather than described by the schema:\nan item marking `default` while also pinning `conditions` — a fallback variant applies only\nwhen nothing else does, so it cannot also pin — and an item carrying `valid_from` with no\nvariant addressed at all. Both carry a message and no code, as the create path refuses the\nfirst today.\n", "required": [ "entity_id" ], "properties": { "entity_id": { "type": "string", "description": "The conditional entity the variant belongs to. Required, as it is beside a `variant_id`.\n", "example": "price-sp26d1yo" }, "conditions": { "$ref": "#/components/schemas/PinnedConditions" }, "default": { "type": "boolean", "default": false, "description": "Address the entity's fallback variant, the one it serves when nothing else applies. A\nproperty of the variant, as it is on a write, never an entry in `conditions`.\n" }, "valid_from": { "type": "string", "description": "The one version to remove, by the instant it takes effect. Omitted, the whole variant\ngoes.\n\nAn RFC 3339 date or date-time, to at most millisecond precision, canonicalized before it\nis 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.\n", "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** — position is what maps an outcome back to its\nsource row, and no entry carries an index of its own.\n", "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.\n", "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** — position is what maps an outcome back to its\nsource row.\n", "items": { "$ref": "#/components/schemas/BatchDeleteResultEntry" } } } }, "BatchUpsertOutcome": { "type": "string", "description": "What one upsert item did, derived from what was stored rather than from a mode the caller\ndeclared.\n\n- `variant_created`: the condition tuple was unknown, so a variant and its first version were\n created. The entry's `variant_id` is the id an order or contract pins.\n- `version_created`: the tuple was known and had no version at the item's `valid_from`, so\n one was appended. The ordinary monthly-refresh case, and a separate value from\n `variant_created` so an importer's counts can tell \"new postal codes appeared\" from\n \"existing variants got their scheduled adjustment\".\n- `updated`: a version existed at that exact instant and was written in place.\n- `skipped`: reserved for a write whose values are identical to what is stored, so re-running\n an unchanged import reads as a no-op. An item without `valid_from` has no `skipped`\n detection at all.\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 nothing — **the variant or the version**, never the entity. An\n entity that cannot answer the item is an `error` carrying `ENTITY_NOT_FOUND`,\n `ENTITY_TYPE_MISMATCH` or `ENTITY_NOT_CONDITIONAL`.\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`, all\nof them present, so a logger reads a count without `?? 0`.\n\n**They sum to the length of `results`.** There is no `total`.\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`, all\nof them present, and summing to the length of `results`. No `total`.\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, and anything worth knowing about it.\n\n**It carries nothing else.** Position in `results` is the contract, so no entry carries an\nindex; nothing the caller sent is echoed back beyond `entity_id`; and there is no `_revision`\n— an editing screen re-reads the version it is about to write through its own `GET`.\n", "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 — present whatever happened.", "example": "price-sp26d1yo" }, "variant_id": { "type": "string", "description": "The variant this item created or wrote to. Present on every outcome but `error`: for a\n`variant_created` item it is the id an importer needs to pin, and for the rest it is the\nvariant the item's condition tuple resolved to.\n", "example": "var-46045" }, "valid_from": { "type": "string", "description": "The version this item wrote, canonicalized to millisecond-precision UTC. Present on every\noutcome but `error`, including for an item that sent none — the server stamps the instant\na current-state write takes effect, and this is where the caller reads it back.\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 a `skipped` and an `error` entry too — so a client reads its length rather\nthan branching on its absence, as every other write in this document already asks.\n`skipped` describes what storage did; a warning describes what the request asked for, and\nthe two are not the same fact.\n\nEvery warning fires per item, with no batch-level suppression:\n`VARIANT_COUNT_APPROACHING_CAP` included, even where an entity past its threshold\nproduces it on all 100 entries. A logger dedupes by code.\n", "items": { "$ref": "#/components/schemas/WriteWarning" } }, "error": { "allOf": [ { "$ref": "#/components/schemas/ConditionalPricingError" } ], "description": "Why this item failed, present only with `outcome: error`. The same typed shape a\nsingle-item write is refused with, so a per-item failure and a single-item failure are\nread by one client type.\n\nAn item carries the codes variant create raises — `VARIANT_UNPINNED`,\n`CONDITION_UNDEFINED`, `CONDITION_VALUE_INVALID`, `PIN_FORMAT_INVALID`,\n`VARIANT_LIMIT_REACHED`, `WRITE_CONFLICT` for transient contention, and the three the\naddressed entity answers with: `ENTITY_NOT_FOUND`, `ENTITY_TYPE_MISMATCH` and\n`ENTITY_NOT_CONDITIONAL` — less two. Those three are per item because each item names its\nown entity, while `SCHEMA_NOT_FOUND` is the envelope's, since the slug is in the path. `TUPLE_CONFLICT` never appears on an item, and neither does `VERSION_CONFLICT`: a\nguard failure on a brand-new tuple is re-read and re-derived, and an existing\n`valid_from` is a replacement.\n" } } }, "BatchDeleteResultEntry": { "type": "object", "additionalProperties": false, "description": "What one delete item did, and anything worth knowing about it.\n\nThe same six properties as a batch upsert entry, and it carries nothing else.\n", "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 — present whatever happened.", "example": "price-sp26d1yo" }, "variant_id": { "type": "string", "description": "The variant this item removed, or whose version it removed. Present wherever it is known:\nalways for an item that named one, and for an item addressing a condition tuple only once\nthat tuple resolved. **A `skipped` entry for a tuple no variant pins therefore names no\nvariant.**\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, which is what distinguishes the two deletes this one\nendpoint performs.\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: `ACTIVE_VERSION_CHANGED` where what resolves now changed, and\n`SUPERSEDED_VERSION_WRITTEN` where a past-dated read did. Always present and possibly\nempty, on every outcome, as batch upsert's is.\n", "items": { "$ref": "#/components/schemas/WriteWarning" } }, "error": { "allOf": [ { "$ref": "#/components/schemas/ConditionalPricingError" } ], "description": "Why this item failed, present only with `outcome: error`. The same typed shape a\nsingle-item delete is refused with.\n\n`LAST_VERSION_UNDELETABLE` is the refusal specific to this endpoint's dated form;\n`VARIANT_UNPINNED` is an item that addresses no variant — no `variant_id`, no\n`default`, and no or empty `conditions`; `ENTITY_NOT_FOUND`, `ENTITY_TYPE_MISMATCH` and\n`ENTITY_NOT_CONDITIONAL` are per item, since each item names its own entity;\n`WRITE_CONFLICT` is transient contention.\nA missing variant or version is not here at all — that is `skipped`.\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)" } } }, "ReportedError": { "description": "The `error` field of an error response: the message, or — where the request itself failed\nvalidation before any handler ran — the validation errors themselves, which those 400s put\nhere in place of a string.\n\nA conditional-pricing operation answers a body its schema rejects with the list, and\neverything else it refuses with the message.\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 machine-readable `code` from the\nconditional-pricing vocabulary plus the structured data that code explains, so a client can\nbranch on the kind of failure rather than parse the message.\nReferenced only by the operations that emit these codes; every other operation\nkeeps the plain `Error` shape.\n\n`details` is typed per code. Narrow on `code` and the object under it declares exactly the\nfields that code sends — never a field it does not send, and nothing beyond the declaration —\nso the conflicting variant id, or the value and vocabulary behind a rejected pin, is read\ndirectly.\n\nNot every failure these operations raise is in the vocabulary. A request body that is simply\nmalformed earns a message and nothing to branch on, and is answered with neither `code` nor\n`details` — the last member of the union, so testing `code` for absence is how a client tells\none of those from the twenty-three coded failures.\n", "allOf": [ { "$ref": "#/components/schemas/Error" }, { "type": "object", "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/ReportedError" } ], "description": "What went wrong, in the field responses have always used and every caller to date\nreads. Carries the same string as `message` — which the shared `Error` schema\nrequires — except on a request-validation failure, which puts the list of validation\nerrors here instead.\n" } } }, { "oneOf": [ { "type": "object", "description": "No conditional entity type by that slug — the organization has no schema under it, or\nthe schema it has is not a conditional-pricing one.\n\nAddressed to the caller's own path parameter, and the same answer for every operation:\nnothing below a schema can be looked up until the schema itself is known.\n", "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 exists and holds no entity with that id.\n\nA wrong entity id is answered here, never as a variant that was never there. An id\nthat *does* exist, under another type, is not this code — the entity was found, and\n`ENTITY_TYPE_MISMATCH` is what says so.\n", "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.\n\nA `400`, not a `404`: the entity **was** found. The fix is to correct the slug and\nsend the request again; the entity id and the variant id were right. `actual_schema`\nnames the type the id belongs to, and where that is a conditional entity type it is\nthe slug to send.\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, it\nis the slug to send instead.\n", "example": "product" } } } } }, { "type": "object", "description": "The entity is of the type the slug named, and is not a conditional one.\n\nA Product, Price or Coupon carries variants only if it was created with\n`is_conditional` set, and that flag is fixed at creation. So this is not a refusal\nanother request can get past: the entity has no conditional capability to address,\nand one that needs it has to be created as such.\n\nA `400`, as `ENTITY_TYPE_MISMATCH` is: the entity was found. Reading and writing the\nentity itself are unaffected; it is these endpoints that do not apply to it.\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 — nothing to read, write or delete, and nothing that\nwas ever there to have deleted.\n\nRaised only once the entity itself has been established, so it never stands in for a\nwrong entity id or a wrong slug.\n", "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.\n\nA version is addressed by the exact instant it takes effect from, not by the instant\na read happens to fall in, so this is not \"no version applies then\"; that case is\n`NO_ACTIVE_VERSION`.\n\nResolving a dated address tells an absent version from an absent variant, so a\nvariant that does not exist at all answers `VARIANT_NOT_FOUND` — the same answer the\npaths that name no date give.\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 to fall\nback to.\n\nEverything the request addressed exists: this is an answer about the organization's\nown data, not a defect to fix — \"we do not serve this situation\".\n\nOnly reachable with `resolve_one`. Without it the same situation is a `200` carrying\nan empty `results`, since a set of applicable variants can legitimately be empty; it\nis asking for exactly one answer that turns having none into a failure.\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 — raised by the\nshorthand reads and writes that address \"the version in effect\" without naming a\ndate, and by a pinned `:resolve` whose variant has no version in effect at `as_of`.\n\nRelative to `as_of`, and not a claim that every version is scheduled: a variant that\nis live today has none in effect at an instant before its first `valid_from` either.\nThe ordinary case is a variant staged ahead of its launch, which is a variant waiting\nrather than a variant broken — address one of its versions by `valid_from` to read or\nedit 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.\n\nThe candidates are named, and none of them is served over the others: which is right\nis a question about the organization's own data.\n", "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 — which is what\nmakes the overlap actionable: two variants both apply because their pins do\nnot distinguish the context they were both asked about.\n\nBounded by the same cap `TOO_MANY_MATCHES` reports, which is checked first,\nso this list is never longer than one response may carry.\n", "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.\n\nPersistent, unlike `WRITE_CONFLICT`: the same request fails the same way until the\nholder changes, so a bulk importer can tell \"send this again\" from \"this combination\nis taken and always will be\".\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.\n", "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": "A condition the entity's schema does not define, named by a resolve context, by a\nlisting's condition filter, or by a variant's pins.\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 named by the request and absent from the schema.", "example": "postal_code" } } } } }, { "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, which is what decides the\noperators it accepts.\n", "example": "location" }, "operator": { "type": "string", "description": "The operator the context or filter asked for.", "example": "between" } } } } }, { "type": "object", "description": "A resolve context or listing filter value that is malformed for its condition's type.\n\n`details` says what the type requires, never what arrived: a resolve context value is\nnot quoted back.\n", "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 the condition's `options` do not admit — either\na value a declared vocabulary does not contain, or any value at all where the\ncondition declares no vocabulary for it to be in.\n\nOne of the two codes that report the submitted value back — `PIN_FORMAT_INVALID` is\nthe other. A resolve context value is never quoted back.\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. Declared without a type: the\nvocabulary holds strings, so anything else is out of it by definition and is\nreported as sent.\n", "example": "industrial" }, "options": { "type": "array", "description": "The vocabulary *as enforced* — after the entries this deploy cannot read have\nbeen dropped, so a tenant whose `options` holds a title-only entry is told\nwhat the API actually checked against rather than what they believe they\nwrote. Empty when the condition declares no vocabulary at all, which is\nitself the reason the pin was refused; the message says which of the two\n(unconfigured, or unreadable) applies.\n", "items": { "type": "string" }, "example": [ "private", "commercial" ] } } } } }, { "type": "object", "description": "A multi-match resolve found more variants than one response may carry. Narrowing the\ncontext is the only fix; 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 — concurrent writers, or throughput pressure on the\nentity's own rows. Retryable, unlike `TUPLE_CONFLICT`.\n\nThe revisions are present where the contention was detected on a specific version: a\nwrite carrying `_revision` lost to another that landed first, and a client that read\nthe version again would see `current_revision`. A variant-level refusal carries the\nvariant alone.\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.\nAbsent when it could not be.\n", "example": 4 } } } } }, { "type": "object", "description": "A listing asked for a page reaching past the window the search index allows.\n\n**`from` plus `size`**, not `from` alone: the window bounds the last row a page may\ncontain, so the final servable offset is `window` minus the page size. All three\nnumbers are in `details`, because a refusal quoting only an offset below the window\nreads like a mistake.\n\nNot a page clamped back inside the window, as entity listing does. The fix is a\ndifferent request: page on with the last response's `next`.\n\nThe window belongs to the deploy's search index, so it is reported and never\npublished.\n\nRaised by the paginated variant reads, which answer `501` until their behaviour\nlands.\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. Present because the two\ntogether are what exceeded the window — an offset inside it can still be\nrefused for the page it would have to read.\n", "example": 25 }, "window": { "type": "integer", "description": "The last row this deploy's index will serve from an offset. Read it to size a\npage control, never to decide when to switch to the cursor — a caller can page\non with `next` from any page.\n", "example": 25000 } } } } }, { "type": "object", "description": "A paging cursor could not be used for the read it arrived on.\n\nOne code for every way that happens, because the caller's fix is the same for all of\nthem: start the read again without a cursor. `details.reason` says which check failed,\nfor a human reading a log rather than for a client to branch on — a cursor this API\nminted and a caller stored can go stale, be truncated in transit, be replayed against\na different filter or sort, or be replayed against another variant or the opposite\norder on a versions read.\n\nRaised by the paginated variant and version reads, which answer `501` until their\nbehaviour lands.\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.\n\nA hard refusal, unlike the `VARIANT_COUNT_APPROACHING_CAP` warning that precedes it,\ncarrying the warning's two keys. In a batch it means stop the import rather than fix\na row: every remaining item for that entity will be refused the same way.\n\nEmitted by `$createConditionalVariant`. The batch writes that will also raise it\nanswer `501` until their handlers land.\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, the same value for\nevery organization on it.\n", "example": 5000 } } } } }, { "type": "object", "description": "A variant pins a value that is malformed for its condition's type.\n\nThe write-side mirror of `CONTEXT_FORMAT_INVALID`: a context value is *matched*, a\nvariant's value is *pinned*. Unlike that one it reports the value back, as\n`CONDITION_VALUE_INVALID` does.\n\nDistinct from a condition whose *declared type* this deploy cannot read at all: that\nis a schema problem rather than a bad row, every item naming the condition fails\nidentically, and it stays uncoded.\n\nIt carries `expected` as well as `condition_type`, and the two are not the same fact:\na `location` condition is `condition_type: location` whichever format it declares,\nand the two formats want different values — a postal code, or an object carrying a\npostal code and a town. The type is what a client branches on; `expected` is what\nsays what the value had to be.\n\nEmitted by `$createConditionalVariant`. The batch writes that will also raise it\nanswer `501` until their handlers land.\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, which is what decides the\nvalues it accepts.\n", "example": "daterange" }, "expected": { "type": "string", "description": "What a pin for that condition has to be, in prose — the same field\n`CONTEXT_FORMAT_INVALID` carries, worded for the write side. It says what\n`condition_type` cannot: a `location` of format `zipcode` wants a postal code\nand one of format `zipcode_town` wants an object carrying both, and the type\nis `location` either way.\n", "example": "an object carrying a from and an until date, either may be open" }, "value": { "description": "The value the write pinned, as it arrived. Declared without a type, since\nwhat makes it invalid is that it is not of the condition's type.\n", "example": "2027-01-01/2027-12-31" } } } } }, { "type": "object", "description": "The write pins no condition and is not marked `default`.\n\nSuch a variant would be a universal wildcard matching every resolve, which is a far\nmore dangerous thing than a fallback and far easier to create by accident — an empty\npostal-code column in a source file produces exactly this.\n\nRaised on a delete too, where an item addresses no variant at all — no `variant_id`,\nno `default`, and either no `conditions` or an empty one: the item names no target.\nIt is an `error`, not a `skipped`.\n\nEmitted by `$createConditionalVariant`. Batch upsert and batch delete, which raise\nit too, answer `501` until their handlers land.\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.\n\nSuch a variant would still hold its condition tuple and still be selectable, and\nwould then resolve to nothing — a variant delete wearing a version delete's clothes.\nDelete the variant instead; that frees the tuple too.\n\nEmitted by `$deleteConditionalVariantVersion`. Batch delete, which raises it too,\nanswers `501` until its handler lands.\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 failure the vocabulary has no entry for: a malformed request body, a value that is\nnot readable as its condition's type, a rule refusing a write for a reason a client\ncannot branch on. The message says what to fix, and no code is sent.\n\nCarries what every response carries and nothing else — reading `code` on this member\nis how a client tells it from the coded members above.\n", "additionalProperties": false, "required": [ "message" ], "properties": { "message": { "type": "string" }, "status": { "type": "number" }, "cause": { "type": "string" }, "error": { "$ref": "#/components/schemas/ReportedError" } } } ] } ] }, "Product": { "type": "object", "description": "The product entity", "readOnly": true, "additionalProperties": true, "example": { "type": "product", "_schema": "product", "_title": "Solar Panel with Battery Storage", "name": "Solar Panel with Battery Storage", "code": "SOLAR-BATT", "active": true, "description": "Solar Panel with battery solution, optimized for max efficiency. ", "feature": [ { "_tags": [], "feature": "Eco-Panels" }, { "_tags": [], "feature": "Remote Management Platform" }, { "_tags": [], "feature": "Battery Remote Control" }, { "_tags": [], "feature": "Mobile App" } ], "cross_sellable_products": { "$relation": [ { "entity_id": "068d0713-a650-4668-9ed2-eca7be31e337", "_schema": "product", "_tags": [] }, { "entity_id": "c8402ee7-fba9-4f3d-bffd-6803ca655782", "_tags": [] } ] }, "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": [] } ] } }, "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" } } } }, "cross_sellable_products": { "type": "object", "description": "Stores references to products that can be cross sold with the current product.", "properties": { "$relation": { "type": "array", "items": { "$ref": "#/components/schemas/EntityRelation" } } } }, "product_images": { "description": "Stores references to a set of file images of the product", "oneOf": [ { "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" } } ] }, "price_options": { "type": "object", "description": "A set of [prices](/api/pricing#tag/simple_price_schema) or [composite prices](/api/pricing#tag/dynamic_price_schema) for the current product.", "properties": { "$relation": { "type": "array", "items": { "$ref": "#/components/schemas/EntityRelation" } } } }, "is_conditional": { "description": "The flag for entities whose values vary by context. Resolve the values that apply with\n`POST /v1/conditional-pricing:resolve`.\n", "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 } } }, "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`.\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`.\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" } ] } }, "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" } }, "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" }, "_meta": { "$ref": "#/components/schemas/SignatureMeta" } }, "required": [ "amount_total", "amount_total_decimal", "currency", "billing_period", "breakdown" ] }, "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" } ] } } }, "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", "readOnly": true, "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", "readOnly": true, "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`.\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" } } }, "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" } } } } } }