Order Item Shipments API

It is now possible for Managed Network Fulfillers to create shipments against an order. One advantage of this, is that it offers item level shipments, allowing you to partially ship an order that you may wish to dispatch over several shipments. Another advantage, is that you can provide tracking URLs, which are in turn, fed back to the retailer or brand via order status notifications.

Kornit^X 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 Kornit^X order and item IDs (sequential numbers attributed to all orders and items created in the Kornit^X platform) or by a combination of the 2.

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 Kornit^X 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 Kornit^X 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.

Example Response

{"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 dropship 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 by KornitX ID

To create a shipment using the Kornit^X 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

The Item Object within the items Array

Example Request Body

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

Shipment by External Ref

To create a shipment using the Kornit^X 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 update the status of.

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

The Item Object within the items Array

Example Request Body

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

Shipment by a Combination of External Ref and KornitX ID

To create a shipment using the external ref and the Kornit^X 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 update the status of and [KORNITX_ORDER_ID] should be replaced by the Kornit^X 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

The Item Object within the items Array

Example Request Body

{
	"status": 200,
	"carrier": "dhl",
	"tracking": "JD12345876A",
	"tracking_url": "https://dhl.com/track/JD12345876A",
	"items": [
		{
			"combined": "ABCD-12345678",
			"quantity": 1
		},
		{
			"combined": "EFGH-87654321",
			"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.

The Item Object within the items Array

Example Response Body

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