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

# Direct Label Integration

> The Direct Label Integration enables fulfillment partners, such as 3PLs, Warehouse Management Systems (WMS), and label providers, to retrieve shipping labels directly from OpenBorder using the Get Label API.

## Overview

When a customer places an order through a merchant that uses OpenBorder for international shipping, the order is automatically processed by the OpenBorder platform. OpenBorder generates and stores the shipping label associated with the order, making it available for retrieval through the Get Label API.

When the order is ready for fulfillment, the fulfillment partner can request the label from OpenBorder and use it to complete the shipping workflow. This integration method allows partners to incorporate OpenBorder labels into their existing fulfillment processes with minimal changes to their infrastructure.

## Workflow Example

```mermaid placement="top-left" actions={true} theme={null} theme={null}
sequenceDiagram
    participant Customer
    participant Merchant
    participant OpenBorder
    participant Fulfillment Partner

    Customer->>Merchant: Places Order
    Merchant->>OpenBorder: Submit Order
    OpenBorder->>OpenBorder: Generate Label
    Fulfillment Partner->>OpenBorder: Get Label API
    OpenBorder-->>Fulfillment Partner: Return Label
    Fulfillment Partner->>Customer: Ship Order
```

## Authentication

The Get Label API uses Bearer token authentication. A valid Bearer token must be included in the `Authorization` header of every API request.

Production API credentials are provided by OpenBorder. To obtain a production Bearer token, contact your OpenBorder representative.

For testing purposes, you may use the following sandbox token:

```text theme={null} theme={null}
Authorization: Bearer 28c859a0-bc6d-11ee-9e9e-2ff0c2fe8758
```

<Note>
  The sandbox token can only be used against the test merchant and does not provide access to production data.
</Note>

## Request

| Method | Endpoint                                                                                       |
| ------ | ---------------------------------------------------------------------------------------------- |
| POST   | [https://api.openborder.com/api/post/fc/labels](https://api.openborder.com/api/post/fc/labels) |

The Get Label API supports two request types, depending on how the order is being fulfilled:

* If the fulfillment partner is fulfilling the entire order in a single shipment, only the `orderNumber` field is required in the request.
* If the fulfillment partner is fulfilling only a subset of the items in an order, the request must include the `skus` field and the additional conditionally required fields. OpenBorder will generate a label for the specified items only. This is referred to as a **split shipment**. Because the order is fulfilled across multiple shipments, a separate label is generated for each shipment.

## Request Examples

<CodeGroup>
  ```json Full Order Fulfillment theme={null} theme={null}
  {
  	"orderNumber": "#12345",
  	"zpl": true
  }
  ```

  ```json Split Shipment Fulfillment theme={null} theme={null}
  {
    "orderNumber": "#12345",
    "skus": [
      { "skuName": "TSHIRT-L-BLK", "asn": "ASN001", "quantity": 2 }
    ],
    "fromAddress": {
      "firstName": "Warehouse",
      "lastName": "Team",
      "phoneNumber": "+12125551234",
      "line1": "123 Warehouse St",
      "city": "New York",
      "province": "NY",
      "country": "US",
      "zipcode": "10001"
    },
    "toAddress": {
      "firstName": "Jane",
      "lastName": "Doe",
      "phoneNumber": "+493012345678",
      "line1": "Unter den Linden 1",
      "city": "Berlin",
      "province": "Berlin",
      "country": "DE",
      "zipcode": "10115"
    },
    "trackReference": "REF-12345",
    "parcelWeight": "500",
    "brandCode": "MYBRAND"
  }
  ```
</CodeGroup>

Both request types support an optional `zpl` field. When `zpl` is set, the label is returned in ZPL (Zebra Programming Language) format. If the `zpl` field is omitted, OpenBorder returns the label in the carrier's default format, which may be either PDF or PNG depending on the carrier.

## Response Examples

Upon a successful request, the API returns one or more label URLs, along with the shipment's tracking code and tracking URL. In case of error, an error status will be returned with a brief description of the error.

<CodeGroup>
  ```json Success Response theme={null} theme={null}
  {
    "isError": false,
    "result": {
      "orderNumber": "#12345",
      "labelUrls": ["https://labelurl.com", "https://labelurl2.com"],
      "status": "success",
      "trackingCode": "123456789",
      "trackingUrl": "https://trackingurl.com"
    }
  }
  ```

  ```json Error Response theme={null} theme={null}
  {
      "isError": true,
      "status": 404,
      "name": "NotFoundError",
      "message": "Unable to retrieve label",
      "data": null
  }
  ```
</CodeGroup>

## Possible Error States

### Invalid Order Number

**HTTP Status:** `200`

**Response:**

```text theme={null} theme={null}
{
  "isError": false,
  "result": "Unable to generate label"
}
```

**Cause:**<br />This error occurs when the `orderNumber` in the request payload is incorrect or does not belong to the merchant associated with the API key. OpenBorder tries to match the order in our system, but cannot resolve it, thus triggering an error.

**Solution:**<br />Verify that:

1. The `orderNumber` matches a valid order number in Shopify.
2. The merchant associated with the order is linked to the API key being used.
3. The request is using the correct API key.

If you are unsure whether the correct API key is being used, contact your OpenBorder representative.

### Invalid Request Payload

**HTTP Status:** `400`

**Response:**

```text theme={null} theme={null}
{
    "isError": true,
    "status": 400,
    "name": "InvalidRequestError",
    "message": "Invalid request",
    "data": {
        "errors": [
            {
                "property": "orderNumber",
                "errors": [
                    "orderNumber must be a string"
                ]
            }
        ]
    }
}
```

**Cause:**<br />This error occurs when an `orderNumber` is not included in the request payload. This is the main field OpenBorder uses to match the applicable Shopify order, so it must be included in every request.

**Solution:**<br />Verify that:

1. The `orderNumber` field is included in the request payload, and is populated with a correct order number.

## Testing

You can use the following sample orders to test the Get Label API in the sandbox environment:

* `#OBTEST1094`
* `#OBTEST1111`
* `#OBTEST1115`
* `#OBTEST1159`

The following cURL example retrieves a label for the sample order `#OBTEST1159`:

```bash theme={null} theme={null}
curl --location 'https://api.openborder.com/api/post/fc/labels' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer 28c859a0-bc6d-11ee-9e9e-2ff0c2fe8758' \
--data '{
  "orderNumber": "#OBTEST1159"
}'
```