Skip to main content
Skip table of contents

Order Status API

As a Managed Network Fulfiller, you may prefer to pull the order or job information into your own production system, using one of our supplier or production integrations, rather than using one of the workflows offered in the KornitX platform. If this is the case, it is recommended that you send order status updates back to the platform, for the orders that you fulfil.

KornitX now provides 3 endpoints that allow order status updates, using the OAuth authentication method. The endpoints allow you to update by the sales channels own order reference (Order External Ref), by the KornitX order ID (a sequential number attributed to all orders created in the KornitX platform) or by a combination of the 2.

Authentication

This version of the Order Status 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 Order Status 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-status.update

Example Response

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

OAuth User Requirements

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

  • Access to the companies relating to the orders that you wish to update the status of.

  • The api-sl-2-3.order-status.update user permission enabled.

Request Headers

There are 3 endpoints to choose from when updating the status of an order.

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.

Endpoints

Order Status Update by ID

To update the order status using the KornitX order ID, make a HTTP PUT request to the endpoint below.

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

[KORNITX_ORDER_ID] should be replaced by the ID of the order that you wish to update the status of.

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

Order Status Update by Order External Ref

To update the order status using the orders external ref, make a HTTP PUT request to the endpoint below.

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

[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/status

Order Status Update by a Combination of the Order External Ref and the KornitX Order ID

To update the order status using the external ref and the KornitX order ID combined, make a HTTP PUT request to the endpoint below.

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

[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 KornitX order ID of the same order.

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

Request Body

The request body should be in JSON format and contains a single field.

Name

Type

Field Usage

Example Value/s

status

Int

The status code applicable for the status update (see status code table below).

4

Example Request Body

JSON
{
	"status": 4
}

Status Codes

A table listing each status code and their associated status name is provided in the table below. The table also lists the valid statuses that an order can move to.

For example, an order in the Received status can only transition to the Cancelled status via an API request. An attempt to move an order that’s in the Received status, directly to the Dispatched status, will result in the error response below.

JSON
{
    "error": {
        "message": "Invalid status transition",
        "code": 0
    }
}

Status Name

Status Code

Valid Statuses to Transition To

Received

1

Cancelled (128)

In Production

4

Dispatched (8), Cancelled (128)

Dispatched

8

QC Query

32

Cancelled

128

On Hold

256

Received (1), Cancelled (128)

Sent to Supplier

512

QC Query (32), Cancelled (128), Received by Supplier (513)

Received by Supplier

513

In Production (4), Pending Dispatch (517), Dispatched (8), QC Query (32), Cancelled (128)

Pending Dispatch

517

Dispatched (8)

Success Response

A successful request will return a HTTP 200 response.

JavaScript errors detected

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

If this problem persists, please contact our support.