Direct Label Integration

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

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:

Authorization: Bearer 28c859a0-bc6d-11ee-9e9e-2ff0c2fe8758

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

Request

Method	Endpoint
POST	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

{
	"orderNumber": "#12345",
	"zpl": true
}

{
  "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"
}

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.

{
  "isError": false,
  "result": {
    "orderNumber": "#12345",
    "labelUrls": ["https://labelurl.com", "https://labelurl2.com"],
    "status": "success",
    "trackingCode": "123456789",
    "trackingUrl": "https://trackingurl.com"
  }
}

{
    "isError": true,
    "status": 404,
    "name": "NotFoundError",
    "message": "Unable to retrieve label",
    "data": null
}

Possible Error States

Invalid Order Number

HTTP Status: 200 Response:

{
  "isError": false,
  "result": "Unable to generate label"
}

Cause:
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:
Verify that:

The orderNumber matches a valid order number in Shopify.
The merchant associated with the order is linked to the API key being used.
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:

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

Cause:
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:
Verify that:

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:

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"
}'

Get Started

Integration Guides

Overview

Workflow Example

Authentication

Request

Request Examples

Response Examples

Possible Error States

Invalid Order Number

Invalid Request Payload

Testing

​Overview

​Workflow Example

​Authentication

​Request

​Request Examples

​Response Examples

​Possible Error States

​Invalid Order Number

​Invalid Request Payload

​Testing

Overview

Workflow Example

Authentication

Request

Request Examples

Response Examples

Possible Error States

Invalid Order Number

Invalid Request Payload

Testing