When a buyer reaches the payment screen and sees a price that does not reflect the real cost of importing the product, they leave. According to the Baymard Institute, 48% of international checkout abandonments are caused by unexpected costs at the payment step. The technical solution to that problem has a name: landed cost API integration.
This guide is for e-commerce leaders and engineering teams building international checkout experiences. It covers the data requirements, integration architecture, performance considerations, and compliance checkpoints that determine whether your real-time duty and tax calculation will be accurate or create downstream operational problems.
What a landed cost API calculates
A landed cost API receives order data and returns the total delivered cost to the buyer. That includes international shipping, import duties, local taxes, and relevant customs fees for that specific destination.
The accuracy of the output depends entirely on the quality of the input. A missing or incorrect HS code produces a wrong calculation. A mismatched declared value creates a customs discrepancy. That is why integration starts before checkout. It starts at product catalog setup.
For brands exporting from the Americas to the US, EU, and UK, the calculation components include tariff rates based on HS code and declared origin, US Sales Tax by destination state, EU VAT by member country, UK VAT, and shipping cost calculated by corridor, dimensional weight, and selected service level.
Required data for real-time calculation
The minimum payload the API needs per line item is the HS code of the product, item value in base currency, weight and dimensions, country of origin, and full destination address including postal code.
Additional data that improves accuracy: product category for correct rate application, material composition when relevant for classification, whether the item contains a battery or falls under a regulated category, and the import model being used, DDP or DAP.
Any missing required field should trigger an explicit fallback in the frontend. Showing an estimated shipping cost with a visible disclaimer is better than showing an incorrect value that will cause a customs hold downstream.
US Sales Tax is calculated at the state level and in some jurisdictions at the county or city level. The API needs the full destination postal code to return a precise rate. Generic state-level lookups are not accurate enough for compliance purposes in states with destination-based sourcing rules.
Checkout integration architecture
There are three standard patterns for integrating a landed cost API into checkout: synchronous call on cart load, synchronous call on address change event, or asynchronous pre-calculation with cache by destination and SKU.
The synchronous call on cart load is the simplest to implement but creates the highest latency impact. If the landed cost API response time exceeds 400ms, users notice the delay before seeing the total.
The synchronous call on address change is the most common pattern in D2C checkout. The calculation fires when the buyer confirms the destination postal code or country, and the result is displayed as a separate line item in the order summary before payment confirmation. This approach balances accuracy and performance.
Asynchronous pre-calculation with cache is recommended for high-volume operations with recurring destinations. You calculate landed cost by SKU and destination country combination in batch, store in cache with a 24 to 48 hour TTL, and serve the cached result in checkout without a real-time API call. The tradeoff is that the cache must be invalidated when tariff rates or contracted freight rates change.
For Shopify integrations, the landed cost API connects via Shopify Functions or Checkout UI Extensions. For headless platforms, the integration point is the orchestration layer that composes the payload before checkout rendering. For BigCommerce, the integration connects via the Storefront API at the cart level.
Performance requirements and API SLA
The acceptable maximum latency for an API call in the checkout flow is 500ms at the 95th percentile. Above that threshold, abandonment impact becomes measurable. Google research on mobile page speed indicates that a one-second delay in response reduces conversion by up to 20%.
Set a timeout on the landed cost API call. If the response does not arrive within the defined timeout, the correct behavior is to display an estimate with a visible disclaimer or block order completion with an explanatory message. Silencing the error and displaying zero tax is not acceptable behavior in a compliant checkout.
Monitor the API error rate and the fallback call rate separately. An increase in fallback rate may indicate that product catalog data is incomplete or that the API is experiencing performance degradation.
For operations with simultaneous multi-destination traffic, consider prefetching calculations for the most frequent destination corridors during the user onboarding flow, before they reach checkout, so the result is available in browser-side cache when needed.
Fiscal compliance and customs documentation
The landed cost calculation at checkout is not only a user experience feature. It is the data that will feed customs documentation when the order ships.
The value calculated by the API must match the value declared on the commercial invoice. If there is a discrepancy between what the customer paid at checkout and what was declared to customs, the shipment may be held for value inconsistency.
For DDP operations, you are collecting the tax from the buyer and taking responsibility for remitting that amount to the fiscal authority in the destination country. That requires the calculation to be precise and the tax reconciliation workflow to be structured in your finance systems.
In the EU, this means VAT registration in the destination market or enrollment in the OSS (One Stop Shop) program. In the US, it means Sales Tax nexus management by state. In the UK, it means VAT registration under the rules applicable to non-UK sellers.
The API must be able to feed the customs declaration payload automatically from the order data. If your order management system and your customs documentation system are disconnected, the landed cost calculation creates a correct checkout experience and an incorrect shipment record.
Common integration mistakes and how to avoid them
The first common mistake is using the generic category HS code instead of the product-specific code. A cotton sweater and a wool sweater have different HS codes and different duty rates. Using the wrong code produces an inaccurate calculation and creates a customs declaration discrepancy.
The second mistake is not invalidating the tariff cache after regulatory changes. Tariff rates change, trade agreements take effect, and de minimis thresholds are adjusted. A static cache with a long TTL can serve outdated data for weeks without the team noticing.
The third mistake is treating the API result as informational data rather than operational data. If your order management system does not consume the landed cost API result to feed customs documentation, you have built a correct checkout experience and an incorrect dispatch operation.
The fourth mistake is not testing checkout behavior when the API is unavailable. Define the fallback behavior in staging and validate it works as expected before going to production.
How to evaluate and select a landed cost API
Evaluate available APIs across five dimensions: coverage of the corridors and markets relevant to your operation, calculation accuracy tested with your actual SKU data, documented latency and SLA, DDP support with data passthrough to customs documentation, and integration compatibility with your e-commerce stack.
Request a sandbox environment with real data before signing any contract. Test with the SKUs you actually sell, for the corridors you actually serve, and compare the result against the official tariff schedules published by each destination country’s customs authority.
For brands shipping from Latin America to the US and Europe, the API must cover US Sales Tax by state, EU VAT by member country, UK VAT under applicable non-established seller rules, and any market-specific compliance requirements for the origin country.
ShipSmart provides a landed cost API with coverage for the major cross-border corridors from Latin America, native integration with VTEX and Shopify, and real-time calculation that automatically feeds the customs documentation for each order.
Talk to a ShipSmart specialist and see the API in action with your SKUs
