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",
    "shipping_option": {
        "slug": "shipping_option_slug",
        "name": "Shipping Option Name",
        "page": "ShippingOptionSelectionPage"
    },
    "conf": {
        "items": [
            {
                "product": "product_sku",
                "quantity": 1,
                "product_attributes": {
                      "Age": "10-50",
                      "renk": "BLACK",
                      "beden": "S",
                      "Gender": "female",
                      "description": "test",
                      "integration_size": "S",
                      "integration_color": "WHITE",
                      "integration_arm_length": "long"
              }
            }
        ],
        "shipping_address": {
            "district": "district_name",
            "township": "township_name",
            "city": "city_name",
            "country": "country_name",
            "country_code": "TR"
        },
        "currency": "try",
        "segment_slug": "segment-example"
    },
    "user": {
        "attributes": {
            "city": "Istanbul",
            "slot": "morning"
        }
    },
    "extra_field": {
        "order_type": "pre_order",
        "slot": "evening"
    },
    "client_type": "instore"
}'

Request Parameters

Field	Type	Description
shipping_company	string	Slug identifier of the shipping company.
shipping_option.slug	string	Slug of the selected shipping option.
shipping_option.name	string	Display name of the shipping option.
shipping_option.page	string	Page where the shipping option is selected.
conf.items	array	Product list to be shipped.
conf.items[].product	string	SKU of the product.
conf.items[].quantity	integer	Quantity of each product.
conf.items[].product_attributes	object	Key-value product attribute pairs (e.g., color, material, size).
conf.shipping_address.district	string	Name of the district.
conf.shipping_address.township	string	Name of the township.
conf.shipping_address.city	string	Name of the city.
conf.shipping_address.country	string	Country name.
conf.shipping_address.country_code	string	The code of the country.
conf.currency	string	Currency for shipping cost (e.g., try, usd, etc.).
conf.segment_slug	string	Optional segment identifier used for segment-based shipping cost calculations.
user	object | null	Authenticated user information. Present when the request is made by a logged-in user; null for anonymous users.
user.attributes	object	Key-value attribute pairs of the authenticated user (e.g., city, slot preferences). Can be used for user-based cost customisation on the extension side.
extra_field	object | null	Custom order-level data collected at the OrderSelectionPage step and stored on the pre-order. Can be used to pass slot, city, or other domain-specific fields to the external calculator.
client_type	string | null	Indicates how the order was placed. Possible values: default, android, ios, instore, b2b. Null when not determined.

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).