{ "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", "version": "1.1.0", "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": "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" ] }, { "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": { "type": "string" }, "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" }, { "name": "Provider 2", "code": "code#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}/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": "calculatePricingDetails", "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" } } } } } } } }, "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" ] }, "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)" } } }, "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" } } } }, "_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 ] }, "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 ] }, "_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 } } }, "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 }, "availability": { "$ref": "#/components/schemas/AvailabilityFilters" } }, "example": { "q": "_id:1233432 OR _id:123432454 OR _id:23445433", "sort": "description ASC", "from": 0, "size": 200 }, "required": [ "q" ] }, "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" } }, "required": [ "name", "code" ] }, "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_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": { "$ref": "#/components/schemas/Tax" } } }, "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" } ] } } }, "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 cashback sums for each cashback period.", "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" } }, "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" }, "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": false, "properties": { "contract": { "type": "object", "description": "The contract information.", "properties": { "_id": { "type": "string", "description": "The unique identifier of the contract." }, "contract_name": { "type": "string", "description": "Contract Name" }, "contract_number": { "type": "string", "description": "Contract Number" }, "assignee": { "type": "string", "description": "Assignee user ID" }, "status": { "type": "string", "description": "Contract status", "enum": [ "draft", "in_approval_process", "approved", "active", "deactivated", "revoked", "terminated", "expired" ] }, "description": { "type": "string", "description": "Description of the contract" }, "billing_account": { "type": "object", "description": "Billing Account relation" }, "account_number": { "type": "string", "description": "Account Number" }, "branch": { "type": "string", "description": "Branch/commodity type (e.g. power, gas, water, waste_water, district_heating, or any custom value)" }, "move_in_date": { "type": "string", "format": "date", "description": "Move In Date" }, "move_out_date": { "type": "string", "format": "date", "description": "Move Out Date" }, "billing_address": { "description": "Billing Address", "type": "object" }, "delivery_address": { "description": "Delivery Address", "type": "array", "items": { "type": "object" } }, "additional_addresses": { "type": "array", "description": "Additional Addresses", "items": { "type": "object" } }, "termination_date": { "type": "string", "format": "date", "description": "Date of Termination" }, "termination_reason": { "type": "string", "description": "Reason For Termination" }, "start_date": { "type": "string", "format": "date", "description": "Start Date" }, "end_date": { "type": "string", "format": "date", "description": "End Date" }, "customer": { "type": "object", "description": "Customer relation (contact or account)" }, "order": { "type": "string", "description": "Order relation ID" }, "type": { "type": "string", "description": "Contract type", "enum": [ "one_time", "recurring" ] }, "billing_period": { "type": "string", "description": "Billing Period", "enum": [ "weekly", "monthly", "every_quarter", "every_6_months", "yearly" ] }, "billing_duration_amount": { "type": "number", "description": "Billing Duration amount", "minimum": 0 }, "billing_duration_unit": { "type": "string", "description": "Billing Duration Unit", "enum": [ "weeks", "months", "years" ] }, "notice_time_amount": { "type": "number", "description": "Notice Time amount", "minimum": 0 }, "notice_time_unit": { "type": "string", "description": "Notice Time Unit", "enum": [ "weeks", "months", "years" ] }, "termination_time_amount": { "type": "number", "description": "Termination Time amount", "minimum": 0 }, "termination_time_unit": { "type": "string", "description": "Termination Time Unit", "enum": [ "weeks", "months", "years" ] }, "renewal_duration_amount": { "type": "number", "description": "Renewal Duration amount", "minimum": 0 }, "renewal_duration_unit": { "type": "string", "description": "Renewal Duration Unit", "enum": [ "weeks", "months", "years" ] }, "billing_due_day": { "type": "number", "description": "Billing Due Day" }, "installment_amount": { "type": "number" }, "balance": { "type": "number", "description": "Balance" }, "meters": { "type": "array", "description": "Meters relation", "items": { "type": "string" } }, "payment": { "type": "object", "description": "Payment Details relation" }, "last_sync_at": { "type": "string", "format": "date", "description": "Last Sync At" }, "external_id": { "type": "string", "description": "External ID", "readOnly": true } } }, "contact": { "type": "object", "description": "The contact information.", "properties": { "_id": { "type": "string", "description": "The unique identifier of the contact." }, "salutation": { "type": "string", "description": "Salutation", "enum": [ "Mr.", "Ms. / Mrs.", "Company", "Contact Person", "Company/Contact Person", "Spouse", "Family", "Ownership", "Assembly", "Other" ] }, "title": { "type": "string", "description": "Title", "enum": [ "Dr.", "Prof.", "Prof. Dr." ] }, "first_name": { "type": "string", "description": "First Name" }, "last_name": { "type": "string", "description": "Last Name" }, "customer_number": { "type": "string", "description": "Customer Number" }, "birthdate": { "type": "string", "format": "date", "description": "Date of Birth" }, "email": { "type": "array", "description": "Email addresses", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "_primary": { "type": "boolean" } } } }, "phone": { "type": "array", "description": "Phone numbers", "items": { "type": "object", "properties": { "phone": { "type": "string" }, "_primary": { "type": "boolean" } } } }, "communication_preference": { "type": "string", "description": "Standard communication method", "enum": [ "postal", "portal" ] }, "address": { "type": "array", "description": "Addresses", "items": { "type": "object", "properties": { "_primary": { "type": "boolean" }, "postal_code": { "type": "string" }, "city": { "type": "string" }, "street": { "type": "string" }, "street_number": { "type": "string" }, "country": { "type": "string" } } } }, "payment": { "type": "array", "description": "Payment methods", "items": { "type": "object", "properties": { "_primary": { "type": "boolean" } } } }, "account": { "type": "array", "description": "Account relations", "items": { "type": "string" } }, "marketing_permission": { "type": "boolean", "description": "Marketing Permission (deprecated)", "deprecated": true }, "contact_owner": { "type": "string", "description": "Contact Owner user ID" }, "consent_email_marketing": { "type": "object", "description": "Email Marketing consent" }, "consent_sms_marketing": { "type": "object", "description": "SMS Marketing consent" }, "consent_phone_call": { "type": "object", "description": "Direct Phone Marketing consent" }, "consent_print_marketing": { "type": "object", "description": "Print Marketing consent" }, "portal_users": { "type": "array", "description": "Portal Users relation", "items": { "type": "string" } }, "opportunities": { "type": "array", "description": "Opportunities relation", "items": { "type": "string" } }, "orders": { "type": "array", "description": "Orders relation", "items": { "type": "string" } }, "contracts": { "type": "array", "description": "Contracts relation", "items": { "type": "string" } }, "external_id": { "type": "string", "description": "External ID", "readOnly": 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" ] }, "Offer": { "type": "object", "properties": { "target_id": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "price_id": { "type": "string" }, "product_id": { "type": "string" } }, "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" } } } } } }