Order Item Cancellations API v2.3
KornitX now provides 3 endpoints that allow cancellations 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.
Authentication
The Cancellations 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 Cancellations 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 |
---|---|
| The client ID of the OAuth user provided by the support team. |
| The client secret of the OAuth user provided by the support team. |
|
|
|
|
Example Response
{"token_type":"Bearer","expires_in":3600,"access_token":"..."}
OAuth User Requirements
To make a request to the Cancellations API, the OAuth user must have:
Access to the companies relating to the order items that you wish to create cancellations for.
The
api-sl-2-3.order-cancellation.create
user permission enabled.
Request Headers
There are 3 endpoints to choose from when creating a cancellation 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.
Cancellation by KornitX ID
To create a cancellation 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]/cancellation
[KORNITX_ORDER_ID] should be replaced by the ID of the order that you wish to create a cancellation against.
Example - https://api-sl-2-3.kornitx.net/order/45453571/cancellation
Request Body The request body should be in JSON format and contain the following fields.
Cancellation JSON
Name | Type | Field Usage | Example Value/s |
---|---|---|---|
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 cancelled. | 5 |
Example Request Body
{
"items": [
{
"id": 12345678,
"quantity": 1
}
]
}
Cancellation by External Ref
To create a cancellation 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]/cancellation
[ORDER_EXTERNAL_REF] should be replaced by the external reference of the order that you wish to create a cancellation against.
Example - https://api-sl-2-3.kornitx.net/order/by-external-ref/POS-584551/cancellation
Request Body The request body should be in JSON format and contain the following fields.
Cancellation JSON
Name | Type | Field Usage | Example Value/s |
---|---|---|---|
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 cancelled. | "ABCD" |
quantity | Int | The quantity of items to be shipped. | 5 |
Example Request Body
{
"items": [
{
"external_ref": "ABCD",
"quantity": 1
}
]
}
Cancellation by a Combination of External Ref and KornitX ID
To create a cancellation 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]/cancellation
[ORDER_EXTERNAL_REF] should be replaced by the sales channels order reference for the order that you wish to create a cancellation 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/cancellation
Request Body The request body should be in JSON format and contain the following fields.
Cancellation JSON
Name | Type | Field Usage | Example Value/s |
---|---|---|---|
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 cancelled, followed by the KornitX item ID, separated by a hyphen. | "ABCD-12345678" |
quantity | Int | The quantity of items to be cancelled. | 5 |
Example Request Body
{
"reference": "ABC1234",
"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 cancellation. | 254001 |
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. | 89483772 |
order_id | Int | The KornitX order ID. | 50713062 |
quantity | Int | The total quantity of the line item. | 5 |
Example Response Body
[
{
"id": 254001,
"items": [
{
"id": 89483772,
"order_id": 50713062,
"quantity": 5
}
]
}
]