Fee Configuration
Each brand can define additional fees that are applied on top of the base duties and taxes calculated by Duty Pro. Fees are configured in the dashboard under the brand’s detail page.
Fee types
Section titled “Fee types”Constant amount
Section titled “Constant amount”A fixed monetary value added to the shipment total. Example: a flat $5 “Card Processing Fee.”
| Setting | Description |
|---|---|
| Display name | Name shown to the consignee (e.g., “Processing Fee”) |
| Amount | Fixed fee value |
| Currency | ISO 4217 currency code for the fee amount |
Percentage of value
Section titled “Percentage of value”A fee calculated as a percentage of a configurable base. Example: 4% of value with a $10 minimum.
| Setting | Description |
|---|---|
| Display name | Name shown to the consignee |
| Percentage | Percentage rate (e.g., 2.5 for 2.5%) |
| Percentage base | What the percentage is applied to. See Percentage base below. |
| Minimum amount | Optional floor; if the calculated fee is below this, the minimum is used instead |
| Maximum amount | Optional cap; if the calculated fee exceeds this, the maximum is used instead |
| Currency | ISO 4217 currency code. Caps are defined in this currency and converted to the shipment currency at calculation time. |
Percentage base
Section titled “Percentage base”The percentage can be applied to one of three bases:
| Value | Base | When to use |
|---|---|---|
| Declared Value | Sum of declared_value × quantity across all items | General-purpose value-based fees (e.g., service fees, handling). |
| Duties + Taxes | total_duties + total_taxes + total_additional_country_charges in shipment currency, i.e., the full customs side of the bill (excluding additional fees themselves) | Fees that only relate to the customs amount Duty Pro processes (e.g., a card processing fee, since the merchant collects the merchandise value separately). |
| Duties + Taxes + Other Fees | Customs charges (as above) plus the sum of visible fees applied before this one (per the brand’s apply order) | A fee that should run on top of everything else, e.g., a card processing fee that should also process the customs clearance fee. Place this fee last in the apply order. |
If the base resolves to zero (e.g., a “Duties + Taxes” base on a duty- and tax-free shipment), the calculated fee is zero before any min/max caps are applied, meaning the minimum cap can still force a non-zero fee. If you want such fees skipped entirely when there are no customs charges, enable duty-conditional on the fee.
Pre-customs calculation fee
Section titled “Pre-customs calculation fee”A fee that is distributed across item values before duty and tax calculation. This means the fee amount affects the cost basis on which duties and taxes are computed.
Pre-customs fees are not displayed as separate line items to the consignee and are not re-counted in the consignee’s total; their only effect on the consignee is the increase in customs duties and taxes from the inflated base. The fee amount itself is assumed to be already collected by the merchant (e.g., as shipping).
| Setting | Description |
|---|---|
| Display name | Internal name (not shown to consignee) |
| Amount | Fee value to distribute across items |
| Currency | ISO 4217 currency code |
Distribution method
Section titled “Distribution method”The pre-customs amount is distributed across items pro-rata by each item’s share of the shipment’s total declared value. Each item’s declared value is increased by its share of the adjustment, divided by its quantity to give a per-unit increment.
Example: A $20 pre-customs fee on a shipment with two items:
- Item A: 1 unit at $1,000 → share = $20 × ($1,000 / $1,010) ≈ $19.80 → adjusted to $1,019.80
- Item B: 1 unit at $10 → share = $20 × ($10 / $1,010) ≈ $0.20 → adjusted to $10.20
Pro-rata distribution keeps each item’s proportional weight in the duty base constant, which prevents low-value items from being disproportionately loaded when mixed with high-value items.
Fee conditions
Section titled “Fee conditions”Each fee supports two conditions that control when it is applied:
Duty-conditional
Section titled “Duty-conditional”When enabled, the fee is only applied when the shipment incurs any customs charges: duties, taxes, or destination-country charges (i.e., total_duties + total_taxes + total_additional_country_charges > 0). If all three are zero, the fee is skipped entirely. A shipment with only taxes, or only destination charges, still triggers the fee.
This is useful for fees that should only apply when customs processing actually occurs. For example, a “Customs Brokerage Fee” that doesn’t make sense on a shipment with no customs charges at all.
Country scope
Section titled “Country scope”By default, a fee applies to all destination countries. You can restrict it to a specific set of countries by providing a list of ISO 3166-1 alpha-2 country codes.
Example: A card processing fee that only applies to US-bound shipments would have a country scope of ["US"].
Apply order
Section titled “Apply order”The brand’s fees are calculated and displayed in a configurable apply order. This matters because:
- Receipt line items appear in apply order on the payment page.
- A “Duties + Taxes + Other Fees” percentage fee only sees the fees that come before it in this order. If you put it first, its base is just the customs charges; if you put it last, every other visible fee contributes to its base.
Reorder fees from Brands > [Your Brand] > Additional Fees using the up / down arrows on each fee card. New fees are appended to the end of the order.
Fee calculation order
Section titled “Fee calculation order”Fees are calculated in the following order during shipment creation:
- Filter applicable fees: exclude fees whose country scope doesn’t include the destination country.
- Convert fee amounts: for each applicable fee, convert
amount,min_amount, andmax_amountfrom the fee’s configured currency into the shipment’s currency using the most recent Exelot-managed FX rate. - Calculate pre-customs total: sum all pre-customs fee amounts (in shipment currency).
- Distribute pre-customs adjustment: distribute the total pro-rata across items by each item’s share of the shipment’s total declared value, then divide each share by the item’s quantity to add a per-unit increment.
- Query tariff: calculate duties and taxes using the adjusted item values.
- Apply post-tariff fees: for each constant and percentage fee:
- Iterate fees in apply order.
- Check the duty-conditional flag; skip if duties, taxes, and destination charges are all zero and the fee requires customs charges.
- Calculate the fee amount: fixed amount, or percentage of the selected base (declared value, duties + taxes + destination charges, or duties + taxes + other fees applied so far), with min/max bounds.
- Sum totals:
total_amount = total_duties + total_taxes + total_additional_country_charges + total_additional_fees, wheretotal_additional_country_chargesis any destination-country surcharge returned by the tariff provider (e.g., fixed processing or environmental charges imposed by the destination).total_additional_feesexcludes pre-customs fees (their effect is already captured intotal_dutiesvia the inflated base).
Per-item shipping cost
Section titled “Per-item shipping cost”In addition to brand-level pre-customs fees, each shipment item can carry an optional shipping_cost field. This is the shipping charge for that line item, regardless of quantity (it is not multiplied by quantity).
When set, shipping_cost is passed through to the tariff engine and added to that item’s customs base. It behaves like a per-item, per-shipment version of the pre-customs fee:
shipping_costis dynamic per shipment: submitted with each item on the API call.- Brand-level pre-customs fees are static per brand: configured once in the dashboard.
- The two are additive: an item’s customs base equals its declared value, plus its share of brand-level pre-customs fees, plus its
shipping_cost.
shipping_cost is in the shipment currency and is internal to the customs calculation. It is not displayed as a separate line item to the consignee.
Currency handling
Section titled “Currency handling”Fees can be defined in any currency. At calculation time, fee amounts are converted to the shipment’s currency using Exelot-managed exchange rates. The response includes both the converted amount (amount) and the original amount before conversion (original_amount, original_currency).
Visibility
Section titled “Visibility”By default, all fees appear on the consignee-facing payment page. The only exception is pre-customs fees, which are never visible (they are embedded in item costs).
Managing fees in the dashboard
Section titled “Managing fees in the dashboard”Fees are managed under Brands > [Your Brand] > Additional Fees. Adding, editing, or deleting a fee does not retroactively affect existing shipments.