> ## Documentation Index > Fetch the complete documentation index at: https://developers.openborder.com/llms.txt > Use this file to discover all available pages before exploring further. # Calculate Landed Cost > ## What this endpoint does This REST API calculates the **total landed cost** for shipping a cart of products internationally. It determines **all costs your customer will pay**, including: - Duties - Import taxes - Other customs-related charges Showing a **fully landed cost upfront** gives your international customers transparency at checkout, reduces delivery surprises, and helps you offer **Delivered Duty Paid (DDP)** shipping. ## When to Use This API - **During checkout**: Calculate the total landed cost in real-time when the user enters a shipping address. - **In the shopping cart**: Let shoppers see estimated import charges before they even reach checkout. - **Before creating a draft order**: Validate total shipping costs so your system can show an accurate final price, including duties and taxes. ## Key business benefits - Eliminate unexpected customs charges that cause cart abandonment. - Enable a DDP (Delivered Duty Paid) experience: you collect duties and taxes at checkout. - Improve international conversion rates by being upfront about total cost. - Optionally guarantee the estimate: if all required fields are provided, your business can absorb the final bill. ## What this gives your merchants - One shipment → One or more ship-from → One or more shipping rates → Multiple items - The system returns *duties, taxes, and fees** for each shipment and rate, so merchants can present accurate options at checkout. ## How to ensure a guaranteed calculation - All required fields must be accurate. - Certain destination countries require **Province/State** and **zip code** to guarantee compliance. - If fields are missing, your calculation may be **non-guaranteed** and final charges could differ. ## OpenAPI ````yaml /api-reference/landed-cost.json post /v1/landed-cost openapi: 3.0.0 info: title: OpenBorder Direct API Service description: Direct API Service description for OPEN API documentation version: '0.1' contact: {} servers: - url: https://api.openborder.com/api/direct/ description: Production - url: https://api.staging.openborder.com/api/direct/ description: Sandbox security: [] tags: [] paths: /v1/landed-cost: post: tags: - Landed Cost summary: | Calculate Landed Cost description: > ## What this endpoint does This REST API calculates the **total landed cost** for shipping a cart of products internationally. It determines **all costs your customer will pay**, including: - Duties - Import taxes - Other customs-related charges Showing a **fully landed cost upfront** gives your international customers transparency at checkout, reduces delivery surprises, and helps you offer **Delivered Duty Paid (DDP)** shipping. ## When to Use This API - **During checkout**: Calculate the total landed cost in real-time when the user enters a shipping address. - **In the shopping cart**: Let shoppers see estimated import charges before they even reach checkout. - **Before creating a draft order**: Validate total shipping costs so your system can show an accurate final price, including duties and taxes. ## Key business benefits - Eliminate unexpected customs charges that cause cart abandonment. - Enable a DDP (Delivered Duty Paid) experience: you collect duties and taxes at checkout. - Improve international conversion rates by being upfront about total cost. - Optionally guarantee the estimate: if all required fields are provided, your business can absorb the final bill. ## What this gives your merchants - One shipment → One or more ship-from → One or more shipping rates → Multiple items - The system returns *duties, taxes, and fees** for each shipment and rate, so merchants can present accurate options at checkout. ## How to ensure a guaranteed calculation - All required fields must be accurate. - Certain destination countries require **Province/State** and **zip code** to guarantee compliance. - If fields are missing, your calculation may be **non-guaranteed** and final charges could differ. operationId: CartController_calculateLandedCost parameters: - name: x-openborder-direct-api-key in: header description: OpenBorder merchant API token required: true schema: type: string requestBody: required: true description: >- This API uses JSON. The **required fields** ensure accurate and guaranteed landed cost calculations. All keys below **must** be included for a guaranteed calculation. content: application/json: schema: $ref: '#/components/schemas/TaxCalculationRequest' responses: '200': description: Landed cost successfully calculated content: application/json: schema: $ref: '#/components/schemas/TaxCalculationResponse' '400': description: Invalid request payload received. '401': description: Invalid authorization token received. '422': description: Unprocessable payload received. content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityException' components: schemas: TaxCalculationRequest: type: object properties: ship_to: description: Destination address. allOf: - $ref: '#/components/schemas/ShipToAddress' caller_app: type: string description: Identifier for your app/service (e.g., "checkout-service"). external_reference_id: type: string description: External ID for traceability, like a cart ID or checkout session ID. nullable: true currency_code: type: string description: ISO 4217 currency code (e.g., USD, EUR). order_discount: type: number description: >- Total order-level discount in major currency units (e.g., 10.00 means $10 off). Discount is split proportionally across products for duties/taxes. shipments: description: >- One or more shipments to calculate landed costs for. A shipment groups the items sent from a specific origin warehouse to the order's destination address. type: array items: $ref: '#/components/schemas/CartShipmentRequest' custom_properties: type: object description: Any custom metadata your system wants to store (max 4 KB). nullable: true required: - ship_to - caller_app - currency_code - order_discount - shipments TaxCalculationResponse: type: object properties: landedcost_request_id: type: string description: >- Unique ID for this tax calculation request, must be submitted with the final order — store this for auditing or support. currency_code: type: string description: ISO 4217 currency code used for all amounts (e.g., "CAD"). external_reference_id: type: string description: >- Your original reference ID (e.g., cart or session ID) — helps link this calculation back to your system. nullable: true created_at: type: string description: ISO timestamp showing when the calculation was processed. usd_conversion_rate: type: number description: >- Conversion rate from the returned currency to USD at the time of calculation — useful for reporting. shipments: description: List of results for each shipment you submitted. type: array items: $ref: '#/components/schemas/CartShipmentResponse' hs_codes: description: >- The HS Code each product has been classified to. Availability Note: This field is conditionally populated in the response body. It will only be included if your merchant configuration requires the HS Code for proper processing (ex. international shipping or customs declaration). If the field is not required for your integration, a null value will be returned. type: array items: $ref: '#/components/schemas/SkuHsCodeEntry' required: - landedcost_request_id - currency_code - external_reference_id - created_at - usd_conversion_rate - shipments - hs_codes UnprocessableEntityException: type: object properties: error: description: Validation errors type: array items: $ref: '#/components/schemas/ErrorDetails' ShipToAddress: type: object properties: country_code: type: string description: >- The two-letter country code (ISO 3166-1 alpha-2) for the destination country (e.g. "CA" for Canada). Important: For United States of America (US) and Canada (CA) the `province` and `postal_code` fields are required. province: type: string description: >- The state, province, or region within the destination country. Include this if your destination country has one (e.g."ON" for Ontario). Important: Required for United States of America (US) and Canada (CA). nullable: true postal_code: type: string description: >- The ZIP code or postal code for the shipping address. Important: Required for United States of America (US) and Canada (CA). nullable: true address1: type: string description: >- The primary street address line, such as the house number and street name. Example: "123 Main Street". nullable: true address2: type: string description: >- A secondary address line, such as an apartment, suite, or unit number. Example: "Apt 4B". nullable: true city: type: string description: The city or locality for the delivery address. nullable: true name: type: string description: The full name of the recipient at the destination address. nullable: true required: - country_code CartShipmentRequest: type: object properties: ship_from: description: >- The origin address for this shipment — where it will be shipped from. allOf: - $ref: '#/components/schemas/ShipFromAddress' shipment_id: type: string description: >- A unique ID for the shipment. This ID will be returned in the response to match duties and taxes back to your shipment. shipping_rates: description: A list of available shipping rate options for this shipment. type: array items: $ref: '#/components/schemas/ShippingRate' items: description: All the products included in this shipment. type: array items: $ref: '#/components/schemas/CartItem' required: - ship_from - shipment_id - shipping_rates - items CartShipmentResponse: type: object properties: shipment_id: type: string description: >- The ID you provided for this shipment — use it to map results back to your original request. shipment_type: type: string description: 'Type of shipment: "cross_border" or "local".' enum: - cross_border - local shipping_rate_taxes: description: >- Tax and landed cost results for each shipping rate option you submitted. type: array items: $ref: '#/components/schemas/ShippingRateTaxesResponse' required: - shipment_id - shipment_type - shipping_rate_taxes SkuHsCodeEntry: type: object properties: sku: type: string description: SKU of the product hs_code: type: string description: >- HS code assigned to the product when calculating duties/taxes. **HS code is determined based on the product and ship to country**. required: - sku - hs_code ErrorDetails: type: object properties: field: type: string description: Field name example: ship_from error: type: string description: Error message example: Name is required required: - field - error ShipFromAddress: type: object properties: country_code: type: string description: >- The two-letter country code (ISO 3166-1 alpha-2) for the shipping origin (e.g., "US"). province: type: string description: The state, province, or region within the country. nullable: true postal_code: type: string description: The postal or ZIP code for the origin address. nullable: true address1: type: string description: TThe primary street address line (e.g., "123 Warehouse Ave"). nullable: true address2: type: string description: A secondary address line (e.g., unit or suite number). nullable: true city: type: string description: The city or locality for the delivery address. nullable: true name: type: string description: The full name for the shipping origin, if needed for labeling. nullable: true required: - country_code ShippingRate: type: object properties: shipping_rate_id: type: string description: A unique ID for the shipping rate option (e.g., "EXPRESS_UPS"). shipping_rate: type: number description: >- The cost of the shipping rate in major currency units (e.g., dollars). Up to two decimal places. required: - shipping_rate_id - shipping_rate CartItem: type: object properties: source_line_id: type: string description: > Your internal unique ID for this specific line item within the order. source_product_id: type: number description: Your internal unique ID for the product. source_variant_id: type: number description: Your internal unique ID for the variant of the product. hs_code: type: string description: >- Optional merchant-provided HS6 code. When provided, used as the basis for landed cost and classification. nullable: true quantity: type: number description: The number of units of this product in the shipment. unit_price: type: number description: The per-unit price in major currency units (e.g., dollars). unit_discount: type: number description: >- The total discount applied per unit in major currency units. This amount will be deducted from the unit price when calculating duties/taxes. sku: type: string description: The SKU code for the variant. product_name: type: string description: The name of the product (e.g., "Cotton T-Shirt"). variant_name: type: string description: >- A descriptive variant name, such as "Medium / Blue" — identifies the unique combination of attributes. description: type: string description: A clear description of the product. origin_country_code: type: string description: >- ISO 3166-1 alpha-2 country code for where the product was manufactured. category: type: string description: >- The product category or taxonomy for classification (e.g., "Apparel"). requires_shipping: type: boolean description: >- true if the product physically ships; false for digital/non-physical items. weight: description: Weight information for the item. allOf: - $ref: '#/components/schemas/Weight' required: - source_line_id - source_product_id - source_variant_id - quantity - unit_price - unit_discount - sku - product_name - variant_name - description - origin_country_code - category - requires_shipping - weight ShippingRateTaxesResponse: type: object properties: shipping_rate_id: type: string description: ID of the shipping rate you submitted (e.g., "STANDARD_UPS"). shipping_rate: type: number description: >- The cost of the shipping rate in major currency units (e.g., dollars). Up to two decimal places. tax_transaction_id: type: string description: >- Unique tax transaction ID for the selected shipping option. You must save this and send it when you commit the final order to show which rate was chosen. landed_cost: description: >- Duties, taxes, fees, and a detailed breakdown for this shipping rate. allOf: - $ref: '#/components/schemas/LandedCost' required: - shipping_rate_id - shipping_rate - tax_transaction_id - landed_cost Weight: type: object properties: per_unit: type: number description: Weight per individual item unit. unit: type: string description: Measurement unit for weight (g = grams, lb = pounds). enum: - g - lb required: - per_unit - unit LandedCost: type: object properties: duties: type: number description: Total import duties in major currency units. total_taxes: type: number description: Total taxes for the shipment — sum of shipment and product taxes. shipment_taxes: type: number description: Portion of taxes that apply to shipping fees. product_taxes: type: number description: Portion of taxes that apply to the products. breakdown: description: >- Itemized details of each tax or duty, by type, jurisdiction, and amount. type: array items: $ref: '#/components/schemas/TaxBreakdown' required: - duties - total_taxes - shipment_taxes - product_taxes - breakdown TaxBreakdown: type: object properties: type: type: string description: 'Type of charge: "shipment_tax", "product_tax", or "duty".' enum: - shipment_tax - product_tax - duty tax_name: type: string description: Descriptive name of the tax or duty (e.g., "GST", "Import Duty"). rate: type: number description: Percentage rate applied to the taxable amount. amount: type: number description: >- Final amount for this tax or duty in major currency units (e.g., dollars). taxable_amount: type: number description: The base amount that the rate was applied to. jurisdiction: description: The jurisdiction or region that this tax or duty applies to. allOf: - $ref: '#/components/schemas/Jurisdiction' sku: type: string description: >- The SKU of the product the tax or duty applies to, if relevant. If the cost is shipment-level (not product-specific), this will be null. nullable: true required: - type - tax_name - rate - amount - taxable_amount - jurisdiction - sku Jurisdiction: type: object properties: name: type: string description: >- The name of the jurisdiction or region where the tax/duty applies (e.g., "Ontario" or "Federal"). type: type: string description: >- The type of jurisdiction — for example, "state", "country", or "federal". required: - name - type ````