Skip to main content
Skip table of contents

Order Item Shipments API

KornitX now provides 3 endpoints that allow shipments to be created against one or more items within an order. The endpoints allow you to update by the sales channels own order and item references (Order External Ref/Item External Ref), by the KornitX order and item IDs (sequential numbers attributed to all orders and items created in the KornitX platform) or by a combination of the 2.

Multiple shipments can be created against a single order. Let’s say that you have an order that contains 4 items. 3 items are shipped in one package and 1 item is shipped in another package. In this instance, you should create 2 separate shipments against the order, one for each package.

Authentication

The shipments API uses OAuth 2.0 authentication.  A request for an OAuth token is made to the OAuth endpoint, which returns an access token.  This token can then be used in requests made to the Shipments endpoint.

To make a request for a token, you will require an OAuth user to be set up in the KornitX platform. The user will require specific access and permissions depending on the API request. The permissions required for this request can be found in the “OAuth User Requirements” section below.

If you don’t have an OAuth user set up, please contact the support team, who will be happy to help. The support team will set up the OAuth user in the KornitX platform for you and supply you with the OAuth user client ID and client secret.  These credentials can then be used to obtain a token from the OAuth token endpoint. 

OAuth Token Endpoint - https://oauth.kornitx.net/token

The OAuth token can be obtained by making a POST to the above endpoint.  The request type for the OAuth token is x-www-form-urlencoded and must include the following form keys and values.

Key

Value

client_id

The client ID of the OAuth user provided by the support team.

client_secret

The client secret of the OAuth user provided by the support team.

grant_type

client_credentials

scope

api-sl-2-3.order-shipment.create

Example Response

JSON
{"token_type":"Bearer","expires_in":3600,"access_token":"..."}

OAuth User Requirements

To make a request to the Shipments API, the OAuth user must have:

  • Access to the companies relating to the order items that you wish to create shipments for.

  • The api-sl-2-3.order-shipment.create user permission enabled.

Request Headers

There are 3 endpoints to choose from when creating a shipment against order items.

Each of them require the same 2 headers which are listed below.

Content-Type: “application/json” 

Authorization: “Bearer [OAUTH_ACCESS_TOKEN]“

[OAUTH_ACCESS_TOKEN] should be replaced by the access token that was returned when we made the token request to the https://oauth.kornitx.net/token endpoint.

Shipment Status IDs

The shipment request body contains a status field to indicate the status of the shipment. The field accepts an ID of a predefined list of statuses. These statuses and their associated IDs are provided in the table below.

The most commonly used status ID would be 200 (DISPATCHED).

Shipment Status Name

Shipment Status ID

STATUS_UNKNOWN

0

STATUS_PENDING_LABEL

100

STATUS_HAS_LABEL

110

STATUS_DISPATCHED

200

STATUS_COLLECTED

300

STATUS_DELIVERED

500

STATUS_CANCELLED

9000

Shipment by KornitX ID

To create a shipment using the KornitX order and item IDs, make a HTTP POST request to the endpoint below.

https://api-sl-2-3.kornitx.net/order/[KORNITX_ORDER_ID]/shipment

[KORNITX_ORDER_ID] should be replaced by the ID of the order that you wish to create a shipment against.

Example - https://api-sl-2-3.kornitx.net/order/45453571/shipment

Request Body The request body should be in JSON format and contain the following fields.

Shipment JSON

Name

Type

Field Usage

Example Value/s

status

Int

Shipment Status ID (See Shipment Status ID table above).

200

carrier

String

The name of the carrier.

"DHL"

tracking

String

The tracking number of the shipment.

"JD12345876A"

tracking_url

String

The tracking URL of the shipment.

“https://dhl.com/track/JD12345876A"

items

Array

An array of one or more item objects.

The Item Object within the items Array

Name

Type

Field Usage

Example Value/s

id

Int

The KornitX item ID.

12345678

quantity

Int

The quantity of items to be shipped.

5

Example Request Body

JSON
{
	"status": 200,
	"carrier": "dhl",
	"tracking": "JD12345876A",
	"tracking_url": "https://dhl.com/track/JD12345876A",
	"items": [
		{
			"id": 12345678,
			"quantity": 1
		}
	]
}

Shipment by External Ref

To create a shipment using the KornitX order and item IDs, make a HTTP POST request to the endpoint below.

https://api-sl-2-3.kornitx.net/order/by-external-ref/[ORDER_EXTERNAL_REF]/shipment

[ORDER_EXTERNAL_REF] should be replaced by the external reference of the order that you wish to create a shipment against.

Example - https://api-sl-2-3.kornitx.net/order/by-external-ref/POS-584551/shipment

Request Body The request body should be in JSON format and contain the following fields.

Shipment JSON

Name

Type

Field Usage

Example Value/s

status

Int

Shipment Status ID (See Shipment Status ID table above).

200

carrier

String

The name of the carrier.

"DHL"

tracking

String

The tracking number of the shipment.

"JD12345876A"

tracking_url

String

The tracking URL of the shipment.

https://dhl.com/track/JD12345876A"

items

Array

An array of one or more item objects.

The Item Object within the items Array

Name

Type

Field Usage

Example Value/s

external_ref

String

The sales channels item ref for the order-item to be shipped.

"ABCD"

quantity

Int

The quantity of items to be shipped.

5

Example Request Body

JSON
{
	"status": 200,
	"carrier": "dhl",
	"tracking": "JD12345876A",
	"tracking_url": "https://dhl.com/track/JD12345876A",
	"items": [
		{
			"external_ref": "ABCD",
			"quantity": 1
		}
	]
}

Because an order external ref may not be unique this method also has an optional URL parameter to allow disambiguate orders using ItemExternalRef. If this is enabled and more than one order is matched for the sumitted external_ref the KornitX platform will try to narrow down the a unique order using the item level external_ref provided in the request body.

Example: https://api-sl-2-3.kornitx.net/order/by-external-ref/[ORDER_EXTERNAL_REF]/shipment?disambiguateOrdersUsingItemExternalRef=1

Shipment by a Combination of External Ref and KornitX ID

To create a shipment using the external ref and the KornitX ID combined, make a HTTP POST request to the endpoint below.

https://api-sl-2-3.kornitx.net/order/by-combined/[ORDER_EXTERNAL_REF]-[KORNITX_ORDER_ID]/shipment

[ORDER_EXTERNAL_REF] should be replaced by the sales channels order reference for the order that you wish to create a shipment against and [KORNITX_ORDER_ID] should be replaced by the KornitX order ID of the same order.

Example - https://api-sl-2-3.kornitx.net/order/by-combined/POS-584551-45453571/shipment

Request Body The request body should be in JSON format and contain the following fields.

Shipment JSON

Name

Type

Field Usage

Example Value/s

status

Int

Shipment Status ID (See Shipment Status ID table above).

200

carrier

String

The name of the carrier.

"dhl"

tracking

String

The tracking number of the shipment.

"JD12345876A"

tracking_url

String

The tracking URL of the shipment.

https://dhl.com/track/JD12345876A"

items

Array

An array of one or more item objects.

The Item Object within the items Array

Name

Type

Field Usage

Example Value/s

combined

String

The sales channels item ref for the order-item to be shipped followed by the KornitX item ID, separated by a hyphen.

"ABCD-12345678"

quantity

Int

The quantity of items to be shipped.

5

Example Request Body

JSON
{
	"status": 200,
	"carrier": "dhl",
	"tracking": "JD12345876A",
	"tracking_url": "https://dhl.com/track/JD12345876A",
	"items": [
		{
			"combined": "ABCD-12345678",
			"quantity": 1
		}
	]
}

Response

A successful request will return an HTTP 200 response. The response body will be in JSON format and contain the following fields.

Name

Type

Field Usage

Example Value/s

id

Int

The ID of the shipment.

14457497

tracking

String

The tracking number of the shipment.

"JD12345876A"

carrier

String

The name of the carrier on the shipment.

"dhl"

label_url

String

The label URL for the shipment.

"https://s3-eu-west1.amazonaws.com/generatedassets-gateway3dcom/misc/html2pdf/...............pdf "

document_url

String

The document URL for the shipment.

"https://s3-eu-west1.amazonaws.com/generatedassets-gateway3dcom/misc/html2pdf/...............pdf"

items

Array

An array of one or more item objects.

The Item Object within the items Array

Name

Type

Field Usage

Example Value/s

id

Int

The KornitX item ID.

75174654

order_id

Int

The KornitX order ID.

42042615

quantity

Int

The total quantity of the line item.

5

quantity_shipped

Int

The quantity of the line item that has been shipped.

5

Example Response Body

JSON
[
   {
      "id":14457497,
      "tracking":"JD12345876A",
      "carrier":"dhl",
      "label_url":"",
      "document_url":"",
      "items":[
         {
            "id":75174654,
            "order_id":42042615,
            "quantity":5,
            "quantity_shipped":5
         }
      ]
   }
]

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.