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

#### <mark style="color:red;">**Example Configuration**</mark>

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](https://docs.akinon.com/tutorials/omnitron/sales-channels/sales-channel-settings/how-to-manage-shipping-options-in-omnitron) tutorial.

```json
{
  "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" }
  }
}
```

## <mark style="color:red;">Configuration</mark>

### <mark style="color:red;">1. Define Fallback Costs</mark>

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.

#### <mark style="color:red;">**Fallback Resolution Logic**</mark>

| 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`    |

### <mark style="color:red;">2. Client Modes</mark>

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.

<table><thead><tr><th width="120.84375">Client Type</th><th width="192.453125">Activation</th><th width="169.65234375">Required Settings</th><th>Description</th></tr></thead><tbody><tr><td><strong>Omnitron</strong> (default)</td><td><code>USE_EXTERNAL_COST_CALCULATOR = false</code></td><td>None</td><td>Relies on internal services for shipping cost logic.</td></tr><tr><td><strong>External</strong></td><td><code>USE_EXTERNAL_COST_CALCULATOR = true</code></td><td><code>EXTERNAL_COST_CALCULATOR</code> with <code>host</code> and <code>token</code></td><td>Calls external 3rd-party service using secure token-authenticated requests.</td></tr></tbody></table>

{% hint style="warning" %}
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.
{% endhint %}

### <mark style="color:red;">3. External Client Setup</mark>

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

#### <mark style="color:red;">**i. Enable External Mode**</mark>

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

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

#### <mark style="color:red;">**ii. Define External Endpoint**</mark>

```json
{
  "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.

### <mark style="color:red;">**API Method**</mark>

#### Example Request

```bash
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"
        },
        "currency": "try"
        "segment_slug": "segment-example"
    }
}'
```

#### Request Parameters

<table><thead><tr><th width="295.8203125">Field</th><th width="85.640625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>shipping_company</code></td><td>string</td><td>Slug identifier of the shipping company.</td></tr><tr><td><code>shipping_option.slug</code></td><td>string</td><td>Slug of the selected shipping option.</td></tr><tr><td><code>shipping_option.name</code></td><td>string</td><td>Display name of the shipping option.</td></tr><tr><td><code>shipping_option.page</code></td><td>string</td><td>Page where the shipping option is selected.</td></tr><tr><td><code>conf.items</code></td><td>array</td><td>Product list to be shipped.</td></tr><tr><td><code>conf.items[].product</code></td><td>string</td><td>SKU of the product.</td></tr><tr><td><code>conf.items[].quantity</code></td><td>integer</td><td>Quantity of each product.</td></tr><tr><td><code>conf.items[].product_attributes</code></td><td>object</td><td>Key-value product attribute pairs (e.g., color, material, size).</td></tr><tr><td><code>conf.shipping_address.district</code></td><td>string</td><td>Name of the district.</td></tr><tr><td><code>conf.shipping_address.township</code></td><td>string</td><td>Name of the township.</td></tr><tr><td><code>conf.shipping_address.city</code></td><td>string</td><td>Name of the city.</td></tr><tr><td><code>conf.shipping_address.country</code></td><td>string</td><td>Country name.</td></tr><tr><td><code>conf.currency</code></td><td>string</td><td>Currency for shipping cost (e.g., try, usd, etc.).</td></tr><tr><td><code>conf.segment_slug</code></td><td>string</td><td>Optional segment identifier used for segment-based shipping cost calculations.</td></tr></tbody></table>

#### Example Response (200 OK)

```json
{
  "shipping_price": "409.00"
}
```

<table><thead><tr><th width="176.63671875">Field</th><th width="178.484375">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>shipping_price</code></td><td>string</td><td>Final calculated cost as a string.</td></tr></tbody></table>

#### Error Scenarios & Handling

<table><thead><tr><th width="120.359375">HTTP Code</th><th width="254.65234375">Scenario</th><th>Handling</th></tr></thead><tbody><tr><td><code>4xx</code></td><td>Authentication/authorization error</td><td>Validate the <code>token</code>, <code>host</code>, and external client configuration.</td></tr><tr><td><code>5xx</code></td><td>External service is down or returns error</td><td>Automatically falls back to static cost (<code>fallback_cost</code>).</td></tr></tbody></table>