This guide is applicable for a Delivered Duty Paid (DDP) experience where duties and taxes will be collected at checkout.
Overview
The OpenBorder API enables merchants to calculate the total landed cost for a shopper’s cart - including duties, import taxes, and other customs-related fees - and to submit finalized orders to the OpenBorder Order Management System (OMS) once checkout is complete.
This guide outlines the standard flow of a typical e-commerce transaction and shows where OpenBorder fits into that process.
Standard Order Flow
1. Customer shops and builds their cart
A shopper visits your storefront, browses products, and begins adding items to their cart. As the shopper builds their cart, your system tracks product details such as SKU, quantity, and price. At this stage, no API calls to OpenBorder are required.
2. Customer begins checkout and shipping rates are retrieved
When the shopper proceeds to checkout, they enter or confirm their shipping address. These details are later used to calculate the order’s total landed cost.
Your system then retrieves shipping rates from your preferred carrier or shipping platform (ex., ShipEngine, EasyPost, Shippo). These rates reflect transportation costs only - they do not include duties, import taxes, or customs fees.
Once you have these rates, you’re ready to calculate the total landed cost.
3. Calculate landed cost with OpenBorder
After shipping rates are available, call OpenBorder to calculate the total landed cost of cross-border delivery.
In the example below, a landed cost request is sent for an order shipping from the United Kingdom (GB) to the United States (US). The request includes a single item, an article of clothing, and two possible shipping options (UPS Priority and FedEx Express). The response includes detailed duties and taxes for each shipping option.
Combine these values with the product price and shipping rate to present shoppers with a single, transparent all-in price at checkout.
| Product Price | Shipping Cost | Duties | Taxes | Total Landed Cost |
|---|---|---|---|---|
| 35.00 | 25.00 | 9.28 | 4.95 | 74.23 |
| 35.00 | 40.00 | 9.28 | 6.18 | 75.46 |
Be sure to store the landedcost_request_id and tax_transaction_id values returned in the response - they’ll be required when the order is finalized.
Endpoint: POST https://api.openborder.com/api/direct/v1/landed-cost
{
"ship_to": {
"name": "John Doe",
"address1": "400 Commerce St",
"address2": "Suite 200",
"city": "Austin",
"province": "TX",
"postal_code": "78701",
"country_code": "US"
},
"external_reference_id": "cart_12345",
"caller_app": "big-commerce-storefront",
"currency_code": "USD",
"order_discount": 0,
"shipments": [
{
"ship_from": {
"address1": "12 High St",
"address2": "Flat 3",
"city": "London",
"province": "",
"postal_code": "SW1A 1AA",
"country_code": "GB"
},
"shipment_id": "ship_1",
"shipping_rates": [
{
"shipping_rate_id": "rate_ups_priority",
"shipping_rate": 25.0
},
{
"shipping_rate_id": "rate_fedex_express",
"shipping_rate": 40.0
}
],
"items": [
{
"source_product_id": 1001,
"source_variant_id": 2001,
"quantity": 1,
"unit_price": 35.0,
"unit_discount": 0.0,
"sku": "TSHIRT-RED-M",
"product_name": "Crewneck T-Shirt",
"variant_name": "Medium / Red",
"description": "100% cotton crewneck tee",
"origin_country_code": "GB",
"category": "Apparel",
"requires_shipping": true,
"weight": {
"per_unit": 0.2,
"unit": "g"
}
}
]
}
],
"custom_properties": {}
}{
"landedcost_request_id": "592a0706-e959-437e-af3f-a55fa023f402",
"currency_code": "USD",
"external_reference_id": "cart_12345",
"created_at": "2025-10-22T13:43:29.106Z",
"usd_conversion_rate": 1,
"shipments": [
{
"shipment_id": "ship_1",
"shipment_type": "cross_border",
"shipping_rate_taxes": [
{
"shipping_rate_id": "rate_ups_priority",
"shipping_rate": 25,
"tax_transaction_id": "92f1b9d3-2fd6-476d-8a27-a4894cc1fe0c",
"landed_cost": {
"duties": 9.28,
"total_taxes": 4.95,
"shipment_taxes": 2.06,
"product_taxes": 2.89,
"breakdown": [
{
"type": "shipment_tax",
"tax_name": "TX STATE TAX",
"amount": 1.56,
"taxable_amount": 25,
"rate": 0.0625,
"jurisdiction": {
"name": "TEXAS",
"type": "state"
},
"sku": null
},
{
"type": "shipment_tax",
"tax_name": "TX CITY TAX",
"amount": 0.25,
"taxable_amount": 25,
"rate": 0.01,
"jurisdiction": {
"name": "AUSTIN",
"type": "city"
},
"sku": null
},
{
"type": "shipment_tax",
"tax_name": "TX SPECIAL TAX",
"amount": 0.25,
"taxable_amount": 25,
"rate": 0.01,
"jurisdiction": {
"name": "AUSTIN MTA TRANSIT",
"type": "special"
},
"sku": null
},
{
"type": "duty",
"tax_name": "US LandedCost",
"amount": 9.28,
"taxable_amount": 35,
"rate": 0.265,
"jurisdiction": {
"name": "UNITED STATES",
"type": "country"
},
"sku": "TSHIRT-RED-M"
},
{
"type": "product_tax",
"tax_name": "TX STATE TAX",
"amount": 2.19,
"taxable_amount": 35,
"rate": 0.0625,
"jurisdiction": {
"name": "TEXAS",
"type": "state"
},
"sku": "TSHIRT-RED-M"
},
{
"type": "product_tax",
"tax_name": "TX CITY TAX",
"amount": 0.35,
"taxable_amount": 35,
"rate": 0.01,
"jurisdiction": {
"name": "AUSTIN",
"type": "city"
},
"sku": "TSHIRT-RED-M"
},
{
"type": "product_tax",
"tax_name": "TX SPECIAL TAX",
"amount": 0.35,
"taxable_amount": 35,
"rate": 0.01,
"jurisdiction": {
"name": "AUSTIN MTA TRANSIT",
"type": "special"
},
"sku": "TSHIRT-RED-M"
}
]
}
},
{
"shipping_rate_id": "rate_fedex_express",
"shipping_rate": 40,
"tax_transaction_id": "f722699a-3b34-4054-a4e6-966b0a265838",
"landed_cost": {
"duties": 9.28,
"total_taxes": 6.1899999999999995,
"shipment_taxes": 3.3,
"product_taxes": 2.89,
"breakdown": [
{
"type": "shipment_tax",
"tax_name": "TX STATE TAX",
"amount": 2.5,
"taxable_amount": 40,
"rate": 0.0625,
"jurisdiction": {
"name": "TEXAS",
"type": "state"
},
"sku": null
},
{
"type": "shipment_tax",
"tax_name": "TX CITY TAX",
"amount": 0.4,
"taxable_amount": 40,
"rate": 0.01,
"jurisdiction": {
"name": "AUSTIN",
"type": "city"
},
"sku": null
},
{
"type": "shipment_tax",
"tax_name": "TX SPECIAL TAX",
"amount": 0.4,
"taxable_amount": 40,
"rate": 0.01,
"jurisdiction": {
"name": "AUSTIN MTA TRANSIT",
"type": "special"
},
"sku": null
},
{
"type": "duty",
"tax_name": "US LandedCost",
"amount": 9.28,
"taxable_amount": 35,
"rate": 0.265,
"jurisdiction": {
"name": "UNITED STATES",
"type": "country"
},
"sku": "TSHIRT-RED-M"
},
{
"type": "product_tax",
"tax_name": "TX STATE TAX",
"amount": 2.19,
"taxable_amount": 35,
"rate": 0.0625,
"jurisdiction": {
"name": "TEXAS",
"type": "state"
},
"sku": "TSHIRT-RED-M"
},
{
"type": "product_tax",
"tax_name": "TX CITY TAX",
"amount": 0.35,
"taxable_amount": 35,
"rate": 0.01,
"jurisdiction": {
"name": "AUSTIN",
"type": "city"
},
"sku": "TSHIRT-RED-M"
},
{
"type": "product_tax",
"tax_name": "TX SPECIAL TAX",
"amount": 0.35,
"taxable_amount": 35,
"rate": 0.01,
"jurisdiction": {
"name": "AUSTIN MTA TRANSIT",
"type": "special"
},
"sku": "TSHIRT-RED-M"
}
]
}
}
]
}
]
}Key Landed Cost Calculation Implementation Notes
- Call this endpoint after shipping rates are known.
- Provide full destination details (country, province/state, postal code) for accurate results.
- Use the response to show shoppers an all-in total (items + shipping + duties/taxes).
- If the shopper changes their cart or address, recalculate using this same endpoint.
4. Customer completes checkout
Once the shopper completes checkout, submit the order to OpenBorder for processing. This creates the finalized order in OpenBorder’s Order Management System (OMS), locking in the tax and duty amounts and triggering OpenBorder’s downstream processing workflows.
The example below shows a finalized order submitted to OpenBorder. The request includes:
- A reference id for the order that is unique to your system, identified by
source_reference. - The selected shipment option, identified by
shipment_id. - The
tax_transaction_idfor the shipment returned by OpenBorder during the landed cost calculation. - The
landedcost_request_idreturned by OpenBorder used to link the order to its original landed cost response.
Endpoint: POST https://api.openborder.com/api/direct/v1/orders
{
"source": "merchant-store",
"source_reference": 98765,
"landedcost_request_id": "90f2ee35-0210-4153-83c8-9e62307768ad", // Reference a landed-cost response
"source_created_at": "2025-10-20T10:15:00Z",
"source_updated_at": "2025-10-20T10:15:00Z",
"total": 2427.3251203535406,
"shipments": [
{
"shipment_id": "ship_1",
"tax_transaction_id": "82b80ea0-7c60-4304-95fd-c92d60016208" // Reference response from /landed-cost
}
],
"custom_properties": {
"promocode": "EXAMPLE-WELCOME10"
}
}A successful response with a 204 - No Content status will indicate that the order was accepted and successfully created in the OpenBorder system. No response body is returned.
Key Order Submission Implementation Notes
- Include the
shipment_idandtax_transaction_idfor all shipments in the order.- Use the most recent
landedcost_request_idfor the cart.- Ensure the
totalvalue matches the total shown to the shopper at checkout.- Submit this request after the shopper has successfully completed payment.
Summary of API Touchpoints
| Stage | OpenBorder API Involved | Description |
|---|---|---|
| Cart building | - | No API calls |
| Checkout initiated | - | Collecting info |
| After shipping rates retrieved | POST /api/direct/v1/landed-cost | Calculate duties/taxes |
| Cart revised | POST /api/direct/v1/landed-cost | Recalculate landed cost |
| Order finalized | POST /api/direct/v1/orders | Submit final order |
| Cart abandoned | - | No order submitted |