Skip to content

Feat/update pricing docs #114

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
paulofph wants to merge 4 commits into
base: main
Choose a base branch
from
+302 −2
Open

Feat/update pricing docs #114

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2ca0d20
Add link to swagger
paulofph Apr 3, 2026
8c9630e
adjust existing example
paulofph Apr 3, 2026
a86553a
Add Example
paulofph Apr 3, 2026
a834dd3
Add journey example
paulofph Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
304 changes: 302 additions & 2 deletions docs/apps/components/external-product-catalog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ You can use template variables throughout your configuration to dynamically inje

### Example

Below is an example of a configuration for the `products` hook, assuming a typical OAuth2 authentication flow, where the client credentials are stored in the app options.
Below is an example of a configuration for the `products` and `product-recommendations` hooks, assuming a typical OAuth2 authentication flow, where the client credentials are stored in the app options.

```json title="Products hook with OAuth2 authentication"
{
Expand Down Expand Up @@ -80,6 +80,33 @@ Below is an example of a configuration for the `products` hook, assuming a typic
"Authorization": "Bearer {{AuthResponse.access_token}}"
}
}
},
{
"id": "prod-recommendations-catalog",
"type": "product-recommendations",
"name": {
"en": "Prod Product Recommendations",
"de": "Prod Produktempfehlungen"
},
"auth": {
"url": "{{Options.oauth_api_url}}/auth/token",
"method": "POST",
"headers": {
"Authorization": "Basic {{Options.oauth_client_id | append: \":\" | append: Options.oauth_client_secret | base64_encode}}",
"Content-Type": "application/x-www-form-urlencoded"
},
"body": {
"grant_type": "client_credentials",
"scope": "{{Options.oauth_scope}}"
}
},
"call": {
"url": "{{Options.base_api_url}}/product-recommendations",
"method": "POST",
"headers": {
"Authorization": "Bearer {{AuthResponse.access_token}}"
}
}
}
]
}
Expand Down Expand Up @@ -122,7 +149,7 @@ This allows the portal to dynamically fetch products and pricing from your exter

## Integration Interface

To ensure seamless communication between epilot and your external catalog, your integration must respect the **External Catalog Integration Interface**.
To ensure seamless communication between epilot and your external catalog, your integration must respect the [External Catalog Integration Interface documentation](https://docs.api.epilot.io/pricing-api-external-catalog).

### Specification

Expand All @@ -134,3 +161,276 @@ The integration works as a request to your service endpoint with the following r
For detailed information on the request and response schemas, please refer to the [External Catalog Integration Interface documentation](https://docs.api.epilot.io/pricing-api-external-catalog).


### Response Examples

Below is an example of a response for the `product-recommendations` hook.

```json title="Product Recommendations Response Example"
{
"source": {
"id": "product-1",
"name": "Power Tariff",
"description": "Flexible electricity tariff with competitive prices for residential customers.",
"features": [
"Flexible",
"No hidden fees",
"Free customer support"
],
"product_image_urls": [
"https://epilot-dev-user-content.s3.eu-central-1.amazonaws.com/739224/13e79129-6087-4e6a-b801-3752e8e9490c/solar_panel_ph.jpeg"
],
"product_downloads_urls": [
{
"url": "https://epilot-dev-user-content.s3.eu-central-1.amazonaws.com/739224/b1289717-9266-4940-8f02-b665b98c34fd/september-order.pdf",
"filename": "Example product details file"
}
],
"legal_footnotes": "Price valid for new customers. Prices may vary depending on consumption and region.",
"price": {
"is_composite_price": true,
"id": "composite-price-1",
"name": "Standard tariff",
"metadata": {},
"price_components": [
{
"metadata": {},
"name": "Working price",
"id": "price-component-1",
"is_composite_price": false,
"type": "recurring",
"billing_period": "monthly",
"tax": {
"type": "VAT",
"rate": 19
},
"unit_amount_net_decimal": "0.35",
"unit_amount_gross_decimal": "0.4165",
"amount_subtotal_decimal": "35",
"amount_total_decimal": "41.65",
"currency": "EUR"
},
{
"name": "Base price",
"id": "price-component-2",
"is_composite_price": false,
"type": "recurring",
"billing_period": "monthly",
"tax": {
"type": "VAT",
"rate": 19
},
"unit_amount_net_decimal": "10",
"unit_amount_gross_decimal": "11.90",
"amount_subtotal_decimal": "10",
"amount_total_decimal": "11.90",
"currency": "EUR"
}
],
"total_details": {
"breakdown": {
"recurrences": [
{
"type": "recurring",
"billing_period": "monthly",
"amount_subtotal_decimal": "45",
"amount_total_decimal": "53.55"
}
]
}
},
"billing_duration_amount": 24,
"billing_duration_unit": "months",
"notice_time_amount": 6,
"notice_time_unit": "weeks",
"termination_time_amount": 6,
"termination_time_unit": "weeks",
"renewal_duration_amount": 12,
"renewal_duration_unit": "months"
},
"metadata": {}
},
"offers": [
{
"id": "product-2",
"name": "Power Tariff - Special",
"description": "Special flexible electricity tariff with competitive prices for residential customers.",
"features": [
"Flexible",
"No hidden fees",
"Free customer support"
],
"product_image_urls": [
"https://epilot-dev-user-content.s3.eu-central-1.amazonaws.com/739224/13e79129-6087-4e6a-b801-3752e8e9490c/solar_panel_ph.jpeg"
],
"product_downloads_urls": [
{
"url": "https://epilot-dev-user-content.s3.eu-central-1.amazonaws.com/739224/b1289717-9266-4940-8f02-b665b98c34fd/september-order.pdf",
"filename": "Example product details file"
}
],
"legal_footnotes": "Price valid for new customers. Prices may vary depending on consumption and region.",
"price": {
"is_composite_price": true,
"id": "composite-price-2",
"name": "Standard tariff",
"metadata": {},
"price_components": [
{
"metadata": {},
"name": "Working price",
"id": "price-component-3",
"is_composite_price": false,
"type": "recurring",
"billing_period": "monthly",
"tax": {
"type": "VAT",
"rate": 19
},
"unit_amount_net_decimal": "0.3697",
"unit_amount_gross_decimal": "0.44",
"amount_subtotal_decimal": "36.97",
"amount_total_decimal": "44.00",
"currency": "EUR"
},
{
"name": "Base price",
"id": "price-component-2",
"is_composite_price": false,
"type": "recurring",
"billing_period": "monthly",
"tax": {
"type": "VAT",
"rate": 19
},
"unit_amount_net_decimal": "10",
"unit_amount_gross_decimal": "11.90",
"amount_subtotal_decimal": "10",
"amount_total_decimal": "11.90",
"currency": "EUR"
}
],
"total_details": {
"breakdown": {
"recurrences": [
{
"type": "recurring",
"billing_period": "monthly",
"amount_subtotal_decimal": "45",
"amount_total_decimal": "53.55"
}
]
}
},
"billing_duration_amount": 12,
"billing_duration_unit": "months",
"coupons": [
{
"name": "Special Bonus",
"type": "fixed",
"description": "Flat €10 cashback for loyal customers.",
"category": "cashback",
"cashback_period": "12",
"cashback_amount_decimal": "10",
"fixed_value_decimal": "10",
"fixed_value_currency": "EUR"
}
]
}
},
{
"id": "product-3",
"name": "Power Tariff - Special",
"description": "Special flexible electricity tariff with competitive prices for residential customers.",
"features": [
"Flexible",
"No hidden fees",
"Free customer support"
],
"product_image_urls": [
"https://epilot-dev-user-content.s3.eu-central-1.amazonaws.com/739224/13e79129-6087-4e6a-b801-3752e8e9490c/solar_panel_ph.jpeg"
],
"product_downloads_urls": [
{
"url": "https://epilot-dev-user-content.s3.eu-central-1.amazonaws.com/739224/b1289717-9266-4940-8f02-b665b98c34fd/september-order.pdf",
"filename": "Example product details file"
}
],
"legal_footnotes": "Price valid for new customers. Prices may vary depending on consumption and region.",
"price": {
"is_composite_price": true,
"id": "composite-price-3",
"name": "Standard tariff",
"metadata": {},
"price_components": [
{
"metadata": {},
"name": "Working price",
"id": "price-component-1",
"is_composite_price": false,
"type": "recurring",
"billing_period": "monthly",
"tax": {
"type": "VAT",
"rate": 19
},
"unit_amount_net_decimal": "0.35",
"unit_amount_gross_decimal": "0.4165",
"amount_subtotal_decimal": "35",
"amount_total_decimal": "41.65",
"currency": "EUR"
},
{
"name": "Base price",
"id": "price-component-2",
"is_composite_price": false,
"type": "recurring",
"billing_period": "monthly",
"tax": {
"type": "VAT",
"rate": 19
},
"unit_amount_net_decimal": "10",
"unit_amount_gross_decimal": "11.90",
"amount_subtotal_decimal": "10",
"amount_total_decimal": "11.90",
"currency": "EUR"
}
],
"total_details": {
"breakdown": {
"recurrences": [
{
"type": "recurring",
"billing_period": "monthly",
"amount_subtotal_decimal": "45",
"amount_total_decimal": "53.55"
}
]
}
},
"billing_duration_amount": 24,
"billing_duration_unit": "months",
"coupons": [
{
"name": "Special Bonus",
"type": "fixed",
"description": "Flat €10 cashback for loyal customers.",
"category": "cashback",
"cashback_period": "12",
"cashback_amount_decimal": "10",
"fixed_value_decimal": "10",
"fixed_value_currency": "EUR"
}
]
}
}
]
}
```

This allows portals and journeys to display dynamic product recommendations based on your external catalog, as shown below:

<div style={{display: 'flex', gap: '1rem'}}>
<img src="/img/apps/external-product-catalog/portal-product-recommendations.gif" width="500" />
<img src="/img/apps/external-product-catalog/journey-product-recommendations.png" width="500" />
</div>
Binary file added static/img/apps/external-product-catalog/journey-product-recommendations.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added static/img/apps/external-product-catalog/portal-product-recommendations.gif
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading