Next | Order & Stock Management | Integration Guide - API

Next Integration Guide

Data Exchange Over REST API

Welcome to the Platform

KornitX is happy to welcome you to the platform. We work closely with Next to enable integrations for the passing and end to end management of orders for fulfillment by third party suppliers. This document describes the integration specification for a supplier to integrate to the KornitX Platform for the Direct Dispatch or Personalised Model.

KornitX is able to integrate with suppliers using a variety of API options.

For order management, KornitX can integrate with supplier systems in order to send Direct Dispatch and Personalised orders. The following order API requirements sections describe the core requirements for order management from a Supplier API.

KornitX also has a REST API available for stock management and order status updates. Details of these are also included in the sections below.

Managing Orders via API

The Order Push API allows a supplier to configure a per dropship URL that will receive order details for any new orders created by Next. Order details are sent to the endpoint URL via a simple JSON POST request.

Additionally, a X-CustomGateway-Hmac header is also sent as part of the request. This header can be used to verify that the request has originated from KornitX.

Order Push API Setup

To receive order pushes, the "Generic API" Supplier Integration must be enabled against the relevant Dropship Company account in the KornitX Platform. This will be done by your KornitX contact.

In order to configure the integration, KornitX require the Supplier to provide:

- API Sandbox Endpoint (push URL) - Note, this is optional.

- API Production Endpoint (push URL)

KornitX will provide the Supplier with:

- Access to KornitX Platform (for testing)

- REFID

- API Key

Once the integration has been enabled, a push URL defined and changes saved, a HMAC key will be automatically generated and provided to the supplier.

- HMAC Key

Authentication

HMAC Authentication will be enabled as standard. Each request that is made to the callback URL will always include a "X-CustomGateway-Hmac" header.

We can also enable Basic Authentication if requested.

HMAC Authentication

HMAC Authentication will be enabled as standard. Each request that is made to the callback URL will include a "X-CustomGateway-Hmac" header. The value of this header can be used to verify the authenticity of the request.

Verifying the HMAC Header

Whilst optional, this step is highly recommended for security. If you choose not to verify, or to use Basic Auth, the "X-CustomGateway-Hmac" header will still always be included.

You can verify the integrity of the callback data being sent using HMAC - we will send you a header with the request named "X-CustomGateway-Hmac".

The value of this is calculated using the following:

Hash: sha256

Message: Request body (on a single line with no spaces)

Secret: HMAC Key

If the HMAC you calculate matches the value of the "X-CustomGateway-Hmac" header, you can verify that the request is coming from KornitX and that the data hasn't been tampered with during transit (i.e. due to a man in the middle attack).

Basic Authentication

Basic authentication can be used by populating the Auth Strategy field of the integration settings, with the following URI:

SL\Proxy2\Supplier\GenericApi\GenericApiHttpBasicAuthStrategy

This will be configured by your KornitX contact.

This auth strategy uses the values entered into the Auth Username and Auth Password fields of the integration settings.

When this is set up, requests will include an authorization header. The value of the authorization header will be the Auth Username and Auth Password, separated by a colon, base 64 encoded and prefixed with “Basic “.

For example, if the Auth Username is “test” and the Auth Password is “test”, the authorization header will be sent as shown below.

Authorization: Basic dGVzdDp0ZXN0

The supplier will provide KornitX with basic auth credentials:

- Username

- Password

The supplier is responsible for authorizing the incoming server calls.

Receiving Orders via API

Example File Format

Below is an example of the JSON structure you can expect to receive.

{

"id": 55765718,

"company_ref_id": 18698,

"secondary_company_ref_id": "662144",

"ref": "ADD1F0CC6564B4FE",

"status": 1,

"shipping_company": "",

"shipping_address_1": "43 TEST STREET",

"shipping_address_2": "",

"shipping_address_3": "",

"shipping_address_4": "TEST",

"shipping_address_5": "TEST",

"shipping_postcode": "J34 2JF",

"shipping_country": "United Kingdom",

"shipping_country_code": "GB",

"billing_company": "",

"billing_address_1": "",

"billing_address_2": "",

"billing_address_3": "",

"billing_address_4": "",

"billing_address_5": "",

"billing_postcode": "",

"billing_country": "United Kingdom",

"customer_name": "MISS A TESTER",

"customer_telephone": "",

"customer_telephone_mobile": "",

"sale_datetime": "2023-11-27 00:00:00",

"external_ref": "3572795400",

"has_been_completed": false,

"completion_datetime": "0000-00-00 00:00:00",

"has_pdf_been_queued": false,

"has_pdf_been_completed": false,

"shipping_method": "48 Days",

"customer_email": "ATESTER@YAHOO.CO.UK",

"shipping_carrier": "OwnCarrier",

"shipping_tracking": "",

"shipping_note_url": "",

"payment_trans_id": "14067",

"payment_type": "",

"has_initial_confirmation_email_been_sent": false,

"has_shipping_confirmation_email_been_sent": false,

"creation_datetime": "2023-11-27 15:25:50",

"additional_info": "DQ695212",

"has_error": false,

"error_message": "",

"required_dispatch_date": "2024-01-15",

"is_status_callback_pending": false,

"stock_request_id": 0,

"status_callback_attempts": 0,

"status_callback_next_retry": "0000-00-00 00:00:00",

"consolidate": false,

"has_been_invoiced": false,

"billing_customer_name": "",

"billing_customer_email": "",

"billing_customer_telephone": "",

"shipping_price": 0,

"shipping_price_inc_tax": 0,

"shipping_tax_rate": 0,

"is_urgent": false,

"tag": "",

"pos_user_id": null,

"coupon_code": "",

"currency_code": "GBP",

"is_free_of_charge": false,

"status_name": "Received",

"company_external_ref": "",

"items": [

{

"id": 34328128,

"sale_vat_rate": 0,

"external_ref": "2799366",

"ref": "n6xrl213tp",

"order_id": 55765718,

"sku": "N04050",

"mapped_sku": "NXTSSS-DBL",

"description": "P Snta Stop Strt Sgn",

"colour": "",

"size": "DOUBLE",

"quantity": 1,

"type": 5,

"print_job_id": 0,

"print_job_promise_ref": "",

"external_url": "",

"external_thumbnail_url": "",

"status": 1,

"print_on_demand_ref": "",

"plain_stock_item_ref": "",

"license": "",

"license_percentage": "",

"unit_sale_price": 100,

"unit_sale_price_inc_tax": 100,

"unit_cost_price": 0,

"shipping_price": 0,

"shipping_price_inc_tax": 0,

"bundle_ref": "",

"textual_product_id": "12468190",

"product_variant_id": "3654526",

"quantity_batched": 0,

"quantity_dispatched": 0,

"stock_request_id": null,

"artwork_barcode": "",

"quantity_consolidated": 0,

"product_state_id": null,

"status_name": "Received",

"ecommerce": {

"barcode": "5060441641250"

"attributes": [],

"assets": []

}

"pdfs": [

{

"id": 36623754,

"order_id": 55765718,

"type": 1,

"url": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/misc/html2pdf/4fa7d4defb6a9b242f9b83da1f7c8c85.pdf",

"ref": "vh2h7w83kz15slg1k5b1",

"is_outdated": false

}

"shipments": []

}

Example File Format - Annotated

Below is an example of an annotated JSON structure with additional clarity.

{
"id":65928635, *required	KornitX order reference. This should be stored in your systems and used as the order identifier for status updates for all integrations
"company_ref_id":18698,	KornitX ID reference for Next. Not required if you get orders only from Next via KornitX
"secondary_company_ref_id":"589705", *required	KornitX supplier ID
"ref":"955C0070672AA0E3",	Internal KornitX order ref. Not required
"status":1,
"shipping_company":"",
"shipping_address_1":"FLAT 22 XYZ COURT", *required	Address line
"shipping_address_2":"",	Address line – usually empty
"shipping_address_3":"",	Address line – usually empty
"shipping_address_4":"ABC SQUARE", *required	Address line
"shipping_address_5":"MACCLESFIELD", *required	Address line (town / city)
"shipping_postcode":"SK10 2XR", *required
"shipping_country":"United Kingdom", *required
"shipping_country_code":"GB", *required
"billing_company":"",
"billing_address_1":"",
"billing_address_2":"",
"billing_address_3":"",
"billing_address_4":"",
"billing_address_5":"",
"billing_postcode":"",
"billing_country":"United Kingdom",
"customer_name":"MRS B SURNAME", *required
"customer_telephone":"",	This field is by default not mandatory. If you need it on each order, please ask Next to make it mandatory for your Brand
"customer_telephone_mobile":"",
"sale_datetime":"2024-11-05 00:00:00",	Order timestamp from Next
"external_ref":"3745681400", *required	Order reference from Next and with the customer. Not required for the integration, we recommend storing it for the invoicing from Next
"has_been_completed":false,
"completion_datetime":"0000-00-00 00:00:00",
"has_pdf_been_queued":false,
"has_pdf_been_completed":false,
"shipping_method":"8 Days",	Next expected leadtime
"customer_email":"NAME.SURNAME@GMAIL.COM", *required	Customer email address is always provided
"shipping_carrier":"OwnCarrier",
"shipping_tracking":"",
"shipping_note_url":"",
"payment_trans_id":"10041",	Next invoice number
"payment_type":"",
"has_initial_confirmation_email_been_sent":false,
"has_shipping_confirmation_email_been_sent":false,
"creation_datetime":"2024-11-05 22:49:07", *required	Order receiving timestamp (KornitX)
"additional_info":"S78P6335",
"has_error":false,
"error_message":"",
"required_dispatch_date":"2024-11-14", *required	Date Next communicated to the customer as expected delivery
"is_status_callback_pending":false,
"stock_request_id":0,
"status_callback_attempts":0,
"status_callback_next_retry":"0000-00-00 00:00:00",
"consolidate":false,
"has_been_invoiced":false,
"billing_customer_name":"",
"billing_customer_email":"",
"billing_customer_telephone":"",
"shipping_price":0,
"shipping_price_inc_tax":0,
"shipping_tax_rate":0,
"is_urgent":false,
"tag":"",
"pos_user_id":null,
"coupon_code":"",
"currency_code":"GBP",
"is_free_of_charge":false,
"status_name":"Received",
"company_external_ref":"",
"items":[
{
"id":121130789,
"sale_vat_rate":0,
"external_ref":"26305659",
"ref":"B44BAAA9857",
"order_id":65928635,	KorrnitX order reference
"sku":"AC6152", *required	Next item number
"mapped_sku":"HRNSBLW-L", *required	Manufacturer SKU. This is the item SKU you provided to Next in the PIF sheet. We recommend mapping this for the integration
"description":"BRAND T-Shirt",	Short item description
"colour":"Blue",
"size":"LARGE",
"quantity":1, *required
"type":2,	Internal KornitX item type
"print_job_id":112777254,	Internal KornitX ref for the personalised artwork
"print_job_promise_ref":"",
"external_url":"",
"external_thumbnail_url":"https://s3-eu-west-1.amazonaws.com/assets.easypromo3d.com/output/thumbnails/print-jobs/17798_112777254.png",
"status":1,
"print_on_demand_ref":"",
"plain_stock_item_ref":"",
"license":"",
"license_percentage":"",
"unit_sale_price":35,
"unit_sale_price_inc_tax":35,
"unit_cost_price":0,
"shipping_price":0,
"shipping_price_inc_tax":0,
"bundle_ref":"A92BF34BA5672A8AE7",
"textual_product_id":"15341393",
"product_variant_id":"4782092",
"quantity_batched":0,
"quantity_dispatched":0,
"stock_request_id":null,
"artwork_barcode":"112777254",
"quantity_consolidated":0,	Next orders are usually not consolidated
"product_state_id":null,
"status_name":"Received",
"ecommerce":{
"barcode":"5060441641250"
},
"attributes":[
],
"assets":[	--- Start of personalisation details –-- following lines won't be included in the JSON if your products are stock products
{
"name":"output-1.png",
"description":"T-Shirt",
"url":"https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/print-job/A92BF34BA5672ACDE7/print-artwork/single-1.png"	Link to the printable artwork.
},
{
"name":"thumbnail.png",
"description":"Default Thumbnail",
"url":"https://s3-eu-west-1.amazonaws.com/assets.easypromo3d.com/output/thumbnails/print-jobs/18778_111377254.png"	Thumbnail of default the preview of the personalised product
},
{
"name":"thumbnail-2513439.png",
"description":"Thumbnail T-Shirt",
"url":"https://s3-eu-west-1.amazonaws.com/assets.easypromo3d.com/output/thumbnails/print-jobs/18778_111377254_2513439.png"	Thumbnail of the preview of the personalised product for the specific aspect. If your product has more aspects (e.g. front / back / side) you have a thumbnail URL for each
}
],
"personalisation_text_elements":[	Personalisation details and text – if you wish to receive these in addition to the artwork, please ask us to activate this option
{
"area_name":"T-Shirt Front",
"area_position_x":384,
"area_position_y":198,
"final_text":"Ben",
"size":126
}
]
}
],	--- End of personalisation details ----
"pdfs":[
{
"id":43191519,
"order_id":65928635,	KornitX order reference
"type":1,
"url":"https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/misc/html2pdf/af3c4435e9f3cf22e13bc1a2a7688171.pdf", *required	URL to the Next branded dispatch note pdf to download, print and include with the order
"ref":"cqvymr5thppls0d5klsb",
"is_outdated":false
}
],
"shipments":[
]
}

Responses – HTTP Status Codes

Possible responses are listed below.

200	Order was created successfully.
403	Invalid data provided. For example, unrecognized Item SKU.
400	If there is a syntax issue with the data sent, respond with a 400 HTTP status code and a helpful error message in the response body.
401	If there is an authentication issue with the request, respond with a 401 HTTP status code.
500	If the server is unable to handle the request, respond with a 500 HTTP status code.

Order Consolidation

As standard, orders will be passed as individual order lines and the supplier can consolidate at the packing stage if desired.

For example, if a customer orders 2 products from Next in 1 transaction, two individual orders with unique order references will be passed to the supplier.

If you wish to discuss order consolidation (multi-line orders), please raise this with the Next Team directly as this is not controlled by KornitX.

Branded Dispatch Notes

A branded A4 Dispatch Note must be included within each order. It contains information which is vital for the Customer Returns process and is essential that it is included with each order.

The Dispatch Note "url" can be found within the "pdfs" array, example below:

"pdfs": [

{

"url": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/misc/html2pdf/02ed35b8f21b26b137c5dd3b0c224d0d.pdf ",

}

An example Dispatch Note can be viewed here.

If you are integrating directly with the platform, a URL will be included with the data where you will be able to access and print the Dispatch Note.

If needed, the Dispatch Note is also available to download and print from the KornitX Platform directly. Step by step instructions for this can be found in the Using the KornitX Platform Documentation under the 'Download your Orders' header.

Dispatch / Delivery Date

Please note that the "required_dispatch_date" is the date that the customer is expecting the product to be delivered to them, therefore you should be dispatching before this date with enough time to include your delivery.

Acknowledging Orders via API

When an order is successfully received by the endpoint, a 200 OK response will be returned to KornitX - this serves as the order acknowledgement.

KornitX offers

Status Updates via API

KornitX offers an order status API to allow the order status of each order to be updated via a HTTP PUT request.

The following are examples of the API calls required to set the status of the orders received from our platform via API.

There are two standard status options supported; Dispatch and Cancel, depending on whether an order can be fulfilled or not.

Status Update API Endpoint

https://api-sl-2-2.custom-gateway.net/order/:id/status

Where:

:id = Internal Order ID (this will be passed with the order data)

Request Headers

The request requires the Content-Type and Basic Authorization headers.

Content-Type: application/json

Authorization: Basic COMPANYREFID:APIKEY

Where:

COMPANYREFID = Fulfiller Company Code (this will be provided by KornitX)

APIKEY = API Key associated to the Fulfiller Company (this will be provided by KornitX)

Dispatching Your Order

Once the order has been completed and dispatched to the customer, the brand should update the status of the order to 'Dispatched'. Where possible, tracking information should be included as part of the status update. The below body and status code should be executed, alongside the above API Enpoint and Headers.

Request Body (with tracking)

{
    "status": 8,
    "shipping_tracking": "123Test"
}

Request Body (without tracking)

{
    "status": 8

}

Success Response

A successful request will return an HTTP 200 response. The response body will be in JSON format.

Cancelling Your Order

If a supplier is unable to fulfill an order, the order can be cancelled via the API. The below body and status code should be executed, alongside the above API Endpoint and Headers.

Request Body

{

    "status": 128
}

Success Response

A successful request will return an HTTP 200 response. The response body will be in JSON format.

Managing Inventory via Stock API

KornitX Stock API

The Stock Availability endpoint allows fulfillers to update the stock values of the products that they supply, via a HTTP PUT request when stock positions change. Stock values are updated via a KornitX API end-point which uses basic authentication via a company ref ID and API key which your KornitX representative will provide.

Stock Availability Endpoint

https://api-sl-2-2.kornitx.net/stock/availability

Request Headers

The request requires the Content-Type and Basic Authorization headers.

Content-Type: application/json

Authorization: Basic COMPANYREFID:APIKEY

Where:

COMPANYREFID = Fulfiller Company Code (this will be provided by KornitX)

APIKEY = API Key associated to the Fulfiller Company (this will be provided by KornitX)

Request Body

Stock can be updated in 2 ways. By fulfiller SKU or by barcode (ean).

The fulfiller SKU is stored in the Fulfiller SKU field, which is in the General tab of the stock product in the catalog module.

Barcode is found in the Barcode field, which is in the eCommerce tab of the stock product in the catalog module.

An example request body showing each method is provided below.

[

{

"barcode": "1234567891011",

"data": {

"quantity_available": 200

}

{

"sku": "SGS7E-CS-G-TEST",

"data": {

"quantity_available": 101

}

{

"sku": "R86409-LXL-PSTEST",

"data": {

"quantity_available": 50

}

]

Successful Response Body

An example response body can be seen below.

{

"successful": [

{

"id": 8965296,

"quantity_available": 200,

"last_modified": "2023-02-07 15:18:08"

{

"id": 8965089,

"quantity_available": 101,

"last_modified": "2023-02-07 15:18:08"

{

"id": 8274177,

"quantity_available": 50,

"last_modified": "2023-02-07 15:18:08"

}

]

}

Stock Pools

Stock values can be provided based on either a ring-fenced or shared stock pool. Where the stock is ring-fenced, the frequency with which the data is provided is less critical. However, if stock is part of a shared stock pool, stock updates are required frequently, based on stock position changes, in order to mitigate issues with fulfillment.

Frequency of Updates

The main stock file (full feed) is to be received by KornitX daily, at a designated time. There is an option to submit further delta files containing absolute values received at designated intervals, following the processing of the Next order files. The time and frequency of the feeds should be agreed directly with Next.

Removing Items from Sale

A stock quantity of 0 should be sent if the Brand would like to remove an item from the Next website. A stock update of zero will update the item to show “Currently unavailable” on the Next website, then after 20 minutes the item will be automatically removed from the search feed, unavailable for customers to purchase.

Invoicing & Reports

Invoicing is not handled via the KornitX Platform - Next will provide access to their own invoicing portal.

Suppliers who are integrated to the KornitX Platform will usually extract and store all relevant information needed for order reporting / reconciliation for Next Invoicing in their own systems.

For order reconciliation purposes, as well as the standard order information we recommend that you always store the following data fields:

"sku": "NEXT RETAIL SKU",

"mapped_sku": "MANUFACTURER SKU",

"external_ref": "NEXT ORDER REFERENCE",

If required, you can however extract Order Detail Reports from the KornitX Platform.

Step by Step instructions for this can be found in the Using the KornitX Platform Documentation under the 'Reports' header.

FAQ's

Can't find what you're looking for? Click here where more information can be found on our FAQ page.

Related Articles
Next | Order & Stock Management | Integration Guide - CSV
Next Integration Guide CSV File Data Exchange Over SFTP Welcome to the Kornit X Platform Kornit X is happy to welcome you to the platform. We work closely with Next to enable integrations for the passing and end to end management of orders for ...
Next | Order & Stock Management | Integration Guide - XML
Next Integration Guide XML File Data Exchange Over SFTP Welcome to the Kornit X Platform Kornit X is happy to welcome you to the platform. We work closely with Next to enable integrations for the passing and end to end management of orders for ...
Next | Order & Stock Management | FAQs
Next Supplier Onboarding FAQs Direct Dispatch & Personalised Suppliers Welcome to the KornitX Platform The following document has been written to supplement to information provided in the Technical Documentation. This document covers the most common ...
Next | Integration Test Plan - API
Next Supplier Onboarding Integration Test Plan - API When completing the integration, please follow the below test plan and confirm when all of the steps have been successfully completed. Dispatch Order (with tracking) 1a. Acknowledge Order When an ...
Next | Order & Stock Management | KornitX Platform For Label Plus
Label Plus+ Suppliers Using the KornitX Platform Please note we are now known exclusively as KornitX, a division of Kornit Digital – Custom Gateway was our name before our takeover. To access the platform please refer to the following link – CLICK ...

Next | Order & Stock Management | Integration Guide - API

Next | Order & Stock Management | Integration Guide - API

Welcome to the Platform

Managing Orders via API

Order Push API Setup

Authentication

HMAC Authentication

Basic Authentication

Receiving Orders via API

Example File Format

Example File Format - Annotated

Responses – HTTP Status Codes

Order Consolidation

Branded Dispatch Notes

Dispatch / Delivery Date

Acknowledging Orders via API

Status Updates via API

Status Update API Endpoint

Request Headers

Dispatching Your Order

Request Body (with tracking)

Request Body (without tracking)

Success Response

Cancelling Your Order

Request Body

Success Response

Managing Inventory via Stock API

KornitX Stock API

Stock Availability Endpoint

Request Headers

Request Body

Successful Response Body

Stock Pools

Frequency of Updates

Removing Items from Sale

FAQ's

Related Articles

Next | Order & Stock Management | Integration Guide - CSV

Next | Order & Stock Management | Integration Guide - XML

Next | Order & Stock Management | FAQs

Next | Integration Test Plan - API

Next | Order & Stock Management | KornitX Platform For Label Plus