Developer notes

Technical reference for developers who customize Cross-border Duties & Customs Data.

Add-on identity

Item	Value
Add-on id	kv_crossborder_duties
Function prefix	fn_kv_crossborder_duties_
Language variables	kv_crossborder_duties.*
CSS scope	.kv-cbd-*
PHP namespace	Tygh\Addons\KvCrossborderDuties

Hooks used

PHP: calculate_cart_post (adds the lines to $cart['kv_cbd_lines'], the sums to $cart['kv_cbd_sum'] and the DDP amount to $cart['total']), place_order (stores the lines and the customs item snapshot), get_order_info (loads kv_cbd_lines, kv_cbd_sum, kv_cbd_customs), delete_order, update_product_post (saves product_data[kv_cbd]), delete_product_post, clone_product.

Templates: storefront checkout:checkout_totals (post), checkout:summary (post), orders:order_total (pre); backend products:update_product_code (post), orders:totals_content (pre), orders:detailed_after_content (pre) and the mail hook orders:invoice_shipping (pre). Document variable kvc for the order documents (invoice, summary, packing slip).

Order customs block (for carrier and label add-ons)

$order = fn_get_order_info($order_id);
$customs = $order['kv_cbd_customs'];          // or fn_kv_crossborder_duties_get_order_customs($order_id)
// null when the order has no cross-border data, else:
// [
//   'order_id' => 12, 'incoterm' => 'DDP'|'DAP'|'', 'ship_from' => 'CN', 'dest_country' => 'DE',
//   'currency' => 'USD', 'content_type' => 'merchandise', 'form' => 'CN22'|'CN23',
//   'ids' => ['ioss' => 'IM...', 'uk_vat' => '...', 'eori' => '...'],
//   'goods_total' => 80.0, 'duty_total' => 3.5, 'fee_total' => 2.3, 'vat_total' => 0.0, 'prepaid_total' => 5.8,
//   'items' => [['product_id' => 1, 'description' => '...', 'hs_code' => '6109.10.00', 'origin' => 'CN', 'ship_from' => 'CN',
//                'qty' => 1, 'unit_value' => 40.0, 'line_value' => 40.0, 'weight_kg' => 0.2], ...],
// ]

Values are in the store’s primary currency. The data is a snapshot taken when the order was placed.

Hooks provided

fn_set_hook('kv_cbd_order_customs', $data, $order_id): runs after the customs block is built; change $data by reference (for example to add a carrier-specific field). Register it with fn_register_hooks('kv_cbd_order_customs') and write fn_<your_addon>_kv_cbd_order_customs(&$data, &$order_id).

Estimate endpoint

GET index.php?dispatch=kv_crossborder_duties.estimate&product_id=ID&dest=DE[&from=CN][&qty=1] returns JSON (lines, ddp, dap, note) for one product, never cached (Cache-Control: no-store). It reads no session data except the cart address when dest is omitted.

Database tables

Table	Content
?:kv_cbd_products	HS code, origin, customs description and ship-from override per product.
?:kv_cbd_rules	Duty and fee rules (countries, value limits, amounts, mode, dates).
?:kv_cbd_hs_rates	Duty % by HS prefix and destination.
?:kv_cbd_order_lines	Duty lines of placed orders (per parcel and rule).
?:kv_cbd_order_items	Customs item snapshot of placed orders.

All tables are dropped on uninstall.

Full page cache

Nothing is printed on product, category or home pages. The estimate shows on the cart, checkout and order pages, which are never cached, so no per-visitor data reaches a cached page.

Template overrides

Storefront templates live in design/themes/<theme>/templates/addons/kv_crossborder_duties/. To customize one, copy it to your own theme’s folder; do not edit the add-on’s files, they are replaced on update.