Label Compliance Integration

Overview

The Label Compliance API enables clients to continue using their existing label generation workflows while leveraging OpenBorder to ensure international shipping compliance. Designed for carriers, label providers, and other fulfillment partners, the API validates commercial invoice values, preserves HS codes from checkout through billing, and ensures shipments meet destination-country tax requirements using OpenBorder’s Tax ID. This allows merchants to maintain a Delivered Duty Paid (DDP) experience while continuing to use their preferred shipping infrastructure. Built to integrate seamlessly into existing label generation workflows, the API returns compliance results almost instantly, helping ensure duties and taxes are calculated correctly while reducing the risk of customs delays, billing discrepancies, and other cross-border compliance issues.

This integration is best suited for organizations that already generate shipping labels and require OpenBorder to provide the compliance information needed for international shipments.

Workflow Example

The Label Compliance API is designed to integrate directly into a client’s existing label generation workflow. A typical implementation follows the steps below.

Prerequisite

The merchant must have the OpenBorder Checkout Block installed on their e-commerce platform (e.g.,, Shopify, BigCommerce, etc.). This enables OpenBorder to calculate and display the correct duties and taxes during checkout.

Customer Checkout

When the customer proceeds to checkout, OpenBorder’s Tax Engine calculates the applicable shipping costs, duties, and taxes for the order in real time.

Order Placement

After the customer places their order, the order is automatically ingested into the OpenBorder Order Management System (OMS), where all required compliance data is stored. This includes the commercial invoice value, product HS codes, duties, and taxes.

Preparing for Label Generation

Before generating the shipping label, the client makes a single call to the Label Compliance API using the order ID. OpenBorder retrieves the corresponding order and returns the compliance data required for label generation, ensuring the shipment remains consistent with the duties and taxes calculated during checkout.

Label Generation

After receiving the compliance data, the client continues with its existing label generation workflow, using the values returned by OpenBorder to generate the final shipping label.

Authentication

The Label Compliance API uses an API Key for authentication. A valid API key must be included in the x-openborder-api-key header of every request. Production API credentials are provided by OpenBorder. To obtain a production API key, contact your OpenBorder representative. For testing purposes, you may use the following sandbox API key:

x-openborder-api-key: sk_896954b521a845c8-abd53ccb3d20d81c

In addition to the API key, each integration is assigned a unique Partner ID. This value must be included as the partnerId path parameter in every request so OpenBorder can identify your integration. For testing purposes, use the following Partner ID:

partnerId: obpartner

Request

Method	Endpoint
`POST`	`https://api.openborder.com/api/v1/{partnerId}/label-compliance`

Replace {partnerId} with the Partner ID issued to you by OpenBorder.

Merchant ID

Many OpenBorder clients manage multiple merchants or brands. Therefore, every request must include a unique merchant code in the merchant_id field. Each merchant is assigned a unique Merchant ID by OpenBorder during onboarding. When a new merchant is onboarded, OpenBorder will provide the corresponding Merchant ID for use in API requests.

Order References

When a request is made, OpenBorder must be able to match the order to the corresponding order in our system. The API supports several order reference types. The two most commonly used identifiers are:

Shopify Order ID (SHOPIFY_ORDER_ID) – The 13-digit numerical ID at the end of the Shopify order URL. For example, for the order:
https://admin.shopify.com/store/samplemerchant/orders/7392874987713
the Shopify Order ID is:
7392874987713
Shopify Order Number (SHOPIFY_ORDER_NUMBER) – The customer-facing order number displayed at the top of the Shopify order page (for example, #340056).

Example Request

{
  "merchant_id": "merchant_abc",
  "order_references": [
    {
      "id": "4369721569321",
      "type": "SHOPIFY_ORDER_ID"
    }
  ],
  "package": {
    "parcel_items": [
      {
        "sku": "XYZ222",
        "quantity": 1,
        "unit_price": {
          "amount": 50,
          "currency": "USD"
        },
        "weight": {
          "weight": 200,
          "unit": "g"
        },
        "hs_code": 700239,
        "country_of_origin": "CN",
        "description": "A daily supplement",
        "category": "Health & Supplements",
        "url": "https://www.google.com"
      }
    ],
    "package_value": {
      "amount": 50.0,
      "currency": "USD"
    },
    "incoterm": "DDP",
    "shipper_address": {
      "vat": "",
      "country_code": "US",
      "city": "Los Angeles",
      "province": "CA",
      "postal_code": "90002",
      "address1": "3245 Sunnyside Drive"
    },
    "destination_address": {
      "vat": "",
      "country_code": "GB",
      "city": "London",
      "province": "",
      "postal_code": "W114UL"
    }
  }
}

Response

Upon a successful request, the API returns the order’s Commercial Invoice (CI) value, the HS codes for each SKU, the unit price for each SKU, and a Tax ID (when applicable).

{
  "label_compliance_request_id": "a98db93c-d90f-40f1-84e3-f2950485633a",
  "ci_value": {
    "amount": 100,
    "currency": "USD"
  },
  "ci_value_price_set": {
    "shop_money": {
      "amount": 100,
      "currency": "USD"
    },
    "presentment_money": {
      "amount": 100,
      "currency": "USD"
    }
  },
  "order_total": {
    "amount": 100,
    "currency": "USD"
  },
  "tax_id": "GM123456789",
  "parcel_items": [
    {
      "sku": "SKU-123",
      "hs_code": "23456789",
      "unit_price": {
        "amount": 100,
        "currency": "USD"
      },
      "unit_price_price_set": {
        "shop_money": {
          "amount": 100,
          "currency": "USD"
        },
        "presentment_money": {
          "amount": 100,
          "currency": "USD"
        }
      }
    }
  ]
}

In the event of an error, the API may return one of the following responses.

400 Bad Request
401 Unauthorized
422 Unprocessable Entity

{
  "error": "An error describing why the request could not be validated or parsed.",
  "label_compliance_request_id": "a98db93c-d90f-40f1-84e3-f2950485633a"
}

{
  "error": "Please verify that the API key matches the key provided for this environment.",
  "label_compliance_request_id": "a98db93c-d90f-40f1-84e3-f2950485633a"
}

{
  "error": "The order could not be found. Please check the requested merchant_id or order_reference and try again.",
  "label_compliance_request_id": "a98db93c-d90f-40f1-84e3-f2950485633a"
}

Split Shipments

The Label Compliance API supports split shipments natively. This allows clients to request compliance data for partial fulfillments, where a single order is shipped across multiple packages and each package requires its own shipping label. To create a split shipment, include only the SKUs and quantities that will be fulfilled in the current shipment. OpenBorder will automatically detect that the request represents a partial fulfillment and return:

A prorated Commercial Invoice (CI) value for the shipment.
A parcel_items array containing only the SKUs included in the request.

When implementing split shipments, keep the following in mind:

OpenBorder does not track the fulfillment status of an order or which SKUs have already been processed. It is the client’s responsibility to track which items and quantities have been submitted for each shipment.The Label Compliance API is idempotent, so repeated requests with the same payload will always return the same compliance values.

The order_total field returned in the response always represents the full order value (subtotal + shipping + duties + taxes).This value is not prorated for split shipments and remains the same regardless of how many shipments are created.

Testing

The following sandbox credentials can be used to test the Label Compliance API.

Value	Test Credential
Partner ID	`obpartner`
Merchant ID	`obdemo`
Shopify Order ID	`6721184661784`

Sample Request

{
  "merchant_id": "obdemo",
  "order_references": [
    {
      "id": "6721184661784",
      "type": "SHOPIFY_ORDER_ID"
    }
  ],
  "package": {
    "parcel_items": [
      {
        "sku": "M18A",
        "quantity": 1,
        "unit_price": {
          "amount": 76.24,
          "currency": "CAD"
        },
        "weight": {
          "weight": 1.09,
          "unit": "g"
        },
        "hs_code": "23456789",
        "country_of_origin": "US",
        "description": "Leveled-up features include a sleek charging dock, a single attachable\ntrimming guard that allows you to explore 5 different hair lengths\nusing one tool, and an LED spotlight to easily groom to your",
        "category": "Health & Beauty > Personal Care > Shaving & Grooming",
        "url": "https://www.google.com"
      }
    ],
    "package_value": {
      "amount": 76.24,
      "currency": "CAD"
    },
    "incoterm": "DDP",
    "shipper_address": {
      "vat": "1234567890",
      "country_code": "US",
      "city": "New York",
      "province": "NY",
      "postal_code": "10001",
      "address1": "123 Main St"
    },
    "destination_address": {
      "vat": "9876543210",
      "country_code": "CA",
      "city": "Mississauga",
      "province": "ON",
      "postal_code": "L4V 1E6"
    }
  }
}

Sample cURL

curl --location 'https://api.openborder.com/api/v1/obpartner/label-compliance' \
--header 'Content-Type: application/json' \
--header 'x-openborder-api-key: sk_896954b521a845c8-abd53ccb3d20d81c' \
--data @request.json

Replace the sample values with your production Partner ID, Merchant ID, and API key when moving to production.

Get Started

Integration Guides

Overview

Workflow Example

Authentication

Request

Merchant ID

Order References

Example Request

Response

Split Shipments

Testing

Sample Request

Sample cURL

​Overview

​Workflow Example

​Authentication

​Request

​Merchant ID

​Order References

​Example Request

​Response

​Split Shipments

​Testing

​Sample Request

​Sample cURL

Overview

Workflow Example

Authentication

Request

Merchant ID

Order References

Example Request

Response

Split Shipments

Testing

Sample Request

Sample cURL