> ## 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.

# Introduction

The Landed Cost integration empowers merchants and developers to connect directly the OpenBorder platform to deliver seamless cross-border shopping experiences. With just a few API calls, you can calculate accurate landed costs - including duties & taxes - and submit finalized orders for processing through the OpenBorder Order Management System (OMS).

By integrating with OpenBorder, you enable real-time landed cost estimates at checkout, streamlined order submission, and end-to-end visibility from purchase to delivery.

This integration method offers a headless approach for providing guaranteed landed cost at checkout. It is designed for merchants building and hosting their own e-commerce storefronts. If you are using an e-commerce platform such as Shopify or BigCommerce, we recommend integrating with our dedicated OpenBorder app.

## Authentication

To ensure every transaction on the OpenBorder platform remains safe and secure, all API requests must be authenticated. OpenBorder uses API keys to verify and authorize requests. Your unique API key will be provided by our Implementation team during onboarding and must be included in the header of each request you send to the OpenBorder API.

| Header                        | Example                                         |
| :---------------------------- | :---------------------------------------------- |
| `x-openborder-direct-api-key` | `x-openborder-direct-api-key: {{your_api_key}}` |

If you need help managing your API key, please contact our Implementation team for assistance.

## Environments

The Landed Cost API is available in two environments: **Staging** and **Production**.

* Staging is designed for testing, integration development, and validating your workflows before going live.
* Production is the live environment used to process real landed cost calculations and orders for merchants operating on the OpenBorder platform.

**Use the Staging environment to safely test and refine your integration before moving to Production.**

| Environment | Base URL                                            |
| :---------- | :-------------------------------------------------- |
| Staging     | `https://api.staging.openborder.com/api/direct/v1/` |
| Production  | `https://api.openborder.com/api/direct/v1/`         |

## Status and Error Codes

When you send a request to the Landed Cost API, the response will include an HTTP status code that indicates the outcome of the request.

* `2xx` codes signify a successful request.
* `4xx`and `5xx` codes indicate an issue with the request - such as a missing required field, an invalid API key, or improperly formatted data.

For any response returning a `4xx` status code, the API will include an error message detailing the specific cause and how to resolve it. The following is a list of status codes that can be returned by the Landed Cost API.

### Common Status Codes

| HTTP Status Code              | Description                                                              | What to do                                                                                                                                     |
| :---------------------------- | :----------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `200 - OK`                    | The request was successful, and the response contains the requested data | No action required.                                                                                                                            |
| `204 - No Content`            | The request was successful.                                              | No action required.                                                                                                                            |
| `400 - Bad Request`           | Invalid request payload received.                                        | Review your request body and ensure all required fields and formats are correct. Review API response for validation errors (ex. invalid JSON). |
| `401 - Unauthorized`          | Invalid or missing authorization token.                                  | Verify that your `x-openborder-direct-api-key` header is included and valid for the environment you are making requests against.               |
| `422 - Unprocessable Entity`  | Unprocessable payload request received.                                  | Review API response for validation errors (ex., invalid data types, values, or dependencies).                                                  |
| `500 - Internal Server Error` | OpenBorder error                                                         | Contact OpenBorder support with request details.                                                                                               |

### Example Error Responses

<Tabs>
  <Tab title="400 - Bad Request">
    ```json theme={null} theme={null}
    {
      "message": "Unexpected token 'c', ...\"ence_id\": cart_12345\"... is not valid JSON",
      "error": "Bad Request",
      "statusCode": 400
    }
    ```
  </Tab>

  <Tab title="401 - Unauthorized">
    ```json theme={null} theme={null}
    {
      "message": "Unauthorized",
      "statusCode": 401
    }
    ```
  </Tab>

  <Tab title="422 - Unprocessable Entity">
    ```json theme={null} theme={null}
    {
      "message": "Request payload validation error",
      "error": [
        {
          "field": "caller_app",
          "error": "caller_app should not be empty, caller_app must be shorter than or equal to 255 characters, caller_app must be a string"
        },
        {
          "field": "order_discount",
          "error": "order_discount must not be less than 0, order_discount must be a number conforming to the specified constraints"
        }
      ],
      "statusCode": 422
    }
    ```
  </Tab>
</Tabs>