Remote Cost Calculator

The Remote Cost Calculator is a flexible and fail-safe module designed to dynamically determine shipping costs by interfacing with external shipping company APIs. It serves as a bridge between the e-commerce platform and third-party logistics providers, ensuring accurate, real-time shipping cost estimations during checkout. In cases where the external service is unreachable or returns an error, the system gracefully degrades to use predefined fallback costs, optionally per currency.

This module supports:

• Real-time shipping cost retrieval via external API

• Static fallback pricing on failure

• Multi-currency fallback pricing

• Client configuration (Omnitron-internal or external)

Example Configuration

This configuration is defined by entering "Remote Cost Calculator" in the calculator field when creating a Shipping Option in Omnitron. For more details, please refer to the Shipping Options tutorial.

{
  "name": "Remote Cost Calculator",
  "slug": "remote-cost-calculator",
  "shipping_company": "test",
  "fallback_cost": "300.00",
  "prices_per_currency": {
    "try": { "fallback_cost": "90.00" },
    "usd": { "fallback_cost": "10.00" }
  }
}

Configuration

1. Define Fallback Costs

Fallback values are essential for ensuring continuity in cost calculation when the external service fails. These values prevent cart or order errors by guaranteeing that a shipping price is always available.

• fallback_cost (string): Default shipping cost in the base currency, used when the remote service cannot be reached and no currency-specific fallback is defined.

• prices_per_currency (object): A mapping of currency codes to their corresponding fallback shipping costs.

Fallback Resolution Logic

Condition	Behavior
prices_per_currency has value for currency	Use that value
No value for currency but fallback_cost exists	Use fallback_cost
Both are missing	Default to 0.0

2. Client Modes

The shipping cost can be fetched using either Omnitron’s internal services or a configured External API. This is controlled by environment-based or dynamic settings.

Client Type	Activation	Required Settings	Description
Omnitron (default)	USE_EXTERNAL_COST_CALCULATOR = false	None	Relies on internal services for shipping cost logic.
External	USE_EXTERNAL_COST_CALCULATOR = true	EXTERNAL_COST_CALCULATOR with host and token	Calls external 3rd-party service using secure token-authenticated requests.

When using the Omnitron client, ensure the shipping company is properly configured and linked with a Shipping Cost service in Omnitron; otherwise, no cost will be returned.

3. External Client Setup

To enable external communication with a shipping service provider, the following dynamic settings must be configured in Omnitron:

i. Enable External Mode

{
  "key": "USE_EXTERNAL_COST_CALCULATOR",
  "value": true
}

This activates external request mode. It must be complemented with the API endpoint configuration.

ii. Define External Endpoint

{
  "key": "EXTERNAL_COST_CALCULATOR",
  "value": {
    "host": "https://{{domain}}/calc/",
    "token": "{{your_api_token_here}}"
  }
}

• host: Full URL of the external shipping cost calculator endpoint.

• token: API token to be used in the Authorization header as a bearer token.

API Method

Example Request

curl --location 'https://{{domain}}/calc/' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token {{your_api_token_here}} \
--data '{
    "shipping_company": "shipping_company_slug",
    "conf": {
        "items": [
            {
                "product": "product_sku",
                "quantity": 1
            }
        ],
        "shipping_address": {
            "district": "district_name",
            "township": "township_name",
            "city": "city_name",
            "country": "country_name"
        },
        "currency": "try"
    }
}'

Request Parameters

Field	Type	Required	Description
shipping_company	string	true	Slug identifier of the shipping company.
conf.items	array	true	Product list to be shipped.
conf.items[].product	string	true	SKU of the product.
conf.items[].quantity	integer	true	Quantity of each product.
conf.shipping_address.district	string	true	Name of the district.
conf.shipping_address.township	string	true	Name of the township.
conf.shipping_address.city	string	true	Name of the city.
conf.shipping_address.country	string	true	Country name.
conf.currency	string	true	Currency for shipping cost (e.g., try, usd, etc.).

Example Response (200 OK)

{
  "shipping_price": "409.00"
}

Field	Type	Description
shipping_price	string	Final calculated cost as a string.

Error Scenarios & Handling

HTTP Code	Scenario	Handling
4xx	Authentication/authorization error	Validate the token, host, and external client configuration.
5xx	External service is down or returns error	Automatically falls back to static cost (fallback_cost).