📘
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": "3757 Anchor Way RR2",
        "address2": "Suite 200",
        "city": "Pender Island",
        "province": "BC",
        "postal_code": "V6B 1A1",
        "country_code": "CA"
    },
    "external_reference_id": "cart_12345",
    "caller_app": "ecommerce-storefront",
    "currency_code": "CAD",
    "order_discount": 0,
    "shipments": [
        {
            "ship_from": {
                "address1": "3606 South Street",
                "address2": "Suite 200",
                "city": "Durham",
                "province": "NC",
                "postal_code": "27707",
                "country_code": "US"
            },
            "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_line_id": "1",
                    "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": "CN",
                    "category": "Apparel",
                    "requires_shipping": true,
                    "weight": {
                        "per_unit": 150,
                        "unit": "g"
                    }
                },
                {
                    "source_line_id": "2",
                    "source_product_id": 1001,
                    "source_variant_id": 3001,
                    "quantity": 1,
                    "unit_price": 35.0,
                    "unit_discount": 0.0,
                    "sku": "TSHIRT-GREEN-M",
                    "product_name": "Crewneck T-Shirt",
                    "variant_name": "Medium / Green",
                    "description": "100% cotton crewneck tee",
                    "origin_country_code": "CN",
                    "category": "Apparel",
                    "requires_shipping": true,
                    "weight": {
                        "per_unit": 150,
                        "unit": "g"
                    }
                }
            ]
        }
    ],
    "custom_properties": {}
}

{
    "landedcost_request_id": "5398e165-5c34-4d80-8930-c16472d601b0",
    "currency_code": "CAD",
    "external_reference_id": "cart_12345",
    "created_at": "2026-01-07T14:28:06.192Z",
    "usd_conversion_rate": 1.37642,
    "shipments": [
        {
            "shipment_id": "ship_1",
            "shipment_type": "cross_border",
            "shipping_rate_taxes": [
                {
                    "shipping_rate_id": "rate_ups_priority",
                    "shipping_rate": 25,
                    "tax_transaction_id": "91d57b2f-57f6-4aeb-8ae8-c7284f3da828",
                    "landed_cost": {
                        "duties": 0,
                        "total_taxes": 8.4,
                        "shipment_taxes": 0,
                        "product_taxes": 8.4,
                        "breakdown": [
                            {
                                "type": "shipment_tax",
                                "tax_name": "CANADA GST/TPS",
                                "amount": 0,
                                "taxable_amount": 25,
                                "rate": 0,
                                "jurisdiction": {
                                    "name": "CANADA",
                                    "type": "country"
                                },
                                "sku": null
                            },
                            {
                                "type": "shipment_tax",
                                "tax_name": "BRITISH COLUMBIA PST",
                                "amount": 0,
                                "taxable_amount": 25,
                                "rate": 0,
                                "jurisdiction": {
                                    "name": "BRITISH COLUMBIA",
                                    "type": "state"
                                },
                                "sku": null
                            },
                            {
                                "type": "product_tax",
                                "tax_name": "CANADA GST/TPS",
                                "amount": 1.75,
                                "taxable_amount": 35,
                                "rate": 0.05,
                                "jurisdiction": {
                                    "name": "CANADA",
                                    "type": "country"
                                },
                                "sku": "TSHIRT-RED-M"
                            },
                            {
                                "type": "product_tax",
                                "tax_name": "BRITISH COLUMBIA PST",
                                "amount": 2.45,
                                "taxable_amount": 35,
                                "rate": 0.07,
                                "jurisdiction": {
                                    "name": "BRITISH COLUMBIA",
                                    "type": "state"
                                },
                                "sku": "TSHIRT-RED-M"
                            },
                            {
                                "type": "product_tax",
                                "tax_name": "CANADA GST/TPS",
                                "amount": 1.75,
                                "taxable_amount": 35,
                                "rate": 0.05,
                                "jurisdiction": {
                                    "name": "CANADA",
                                    "type": "country"
                                },
                                "sku": "TSHIRT-GREEN-M"
                            },
                            {
                                "type": "product_tax",
                                "tax_name": "BRITISH COLUMBIA PST",
                                "amount": 2.45,
                                "taxable_amount": 35,
                                "rate": 0.07,
                                "jurisdiction": {
                                    "name": "BRITISH COLUMBIA",
                                    "type": "state"
                                },
                                "sku": "TSHIRT-GREEN-M"
                            }
                        ]
                    }
                },
                {
                    "shipping_rate_id": "rate_fedex_express",
                    "shipping_rate": 40,
                    "tax_transaction_id": "589486c9-712e-4fa4-8db1-652c27126e50",
                    "landed_cost": {
                        "duties": 0,
                        "total_taxes": 8.4,
                        "shipment_taxes": 0,
                        "product_taxes": 8.4,
                        "breakdown": [
                            {
                                "type": "shipment_tax",
                                "tax_name": "CANADA GST/TPS",
                                "amount": 0,
                                "taxable_amount": 40,
                                "rate": 0,
                                "jurisdiction": {
                                    "name": "CANADA",
                                    "type": "country"
                                },
                                "sku": null
                            },
                            {
                                "type": "shipment_tax",
                                "tax_name": "BRITISH COLUMBIA PST",
                                "amount": 0,
                                "taxable_amount": 40,
                                "rate": 0,
                                "jurisdiction": {
                                    "name": "BRITISH COLUMBIA",
                                    "type": "state"
                                },
                                "sku": null
                            },
                            {
                                "type": "product_tax",
                                "tax_name": "CANADA GST/TPS",
                                "amount": 1.75,
                                "taxable_amount": 35,
                                "rate": 0.05,
                                "jurisdiction": {
                                    "name": "CANADA",
                                    "type": "country"
                                },
                                "sku": "TSHIRT-RED-M"
                            },
                            {
                                "type": "product_tax",
                                "tax_name": "BRITISH COLUMBIA PST",
                                "amount": 2.45,
                                "taxable_amount": 35,
                                "rate": 0.07,
                                "jurisdiction": {
                                    "name": "BRITISH COLUMBIA",
                                    "type": "state"
                                },
                                "sku": "TSHIRT-RED-M"
                            },
                            {
                                "type": "product_tax",
                                "tax_name": "CANADA GST/TPS",
                                "amount": 1.75,
                                "taxable_amount": 35,
                                "rate": 0.05,
                                "jurisdiction": {
                                    "name": "CANADA",
                                    "type": "country"
                                },
                                "sku": "TSHIRT-GREEN-M"
                            },
                            {
                                "type": "product_tax",
                                "tax_name": "BRITISH COLUMBIA PST",
                                "amount": 2.45,
                                "taxable_amount": 35,
                                "rate": 0.07,
                                "jurisdiction": {
                                    "name": "BRITISH COLUMBIA",
                                    "type": "state"
                                },
                                "sku": "TSHIRT-GREEN-M"
                            }
                        ]
                    }
                }
            ]
        }
    ],
    "hs_codes": null
}

📘
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_id for the shipment returned by OpenBorder during the landed cost calculation.
The landedcost_request_id returned 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_id and tax_transaction_id for all shipments in the order.

Use the most recent landedcost_request_id for the cart.

Ensure the total value 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