Create Orders API

Kornit^X provides an easy-to-use Order API that gives retailers and brands the ability to push orders into the Kornit^X platform.

Orders can be created in the KornitX platform by making a HTTP POST request to the order endpoint.

Endpoint

https://api-sl-2-2.kornitx.net/order

Rate Limiting

Requests to the API are rate limited to 1000 requests per hour and 10000 requests per day.

A 400 HTTP status code will be returned in the event of the limit being exceeded, please check the error code table towards the bottom of this document for more details.

If you need this limit to be increased on a per account basis, please contact us.

IP Restrictions

For additional security, an IP white list can be enabled for your company reference ID.

Any requests made using your company reference ID and API key from an IP address that isn't white listed will be rejected.

Please contact us to set up IP restrictions, quoting the IP addresses that you will be sending requests from.

We currently only support IPv4

Authentication

To authenticate against the API, include the Authorization HTTP header with every request.

For example,

Authorization: Basic COMPANYREFID:APIKEY

Don't forget to replace COMPANYREFID and APIKEY with your sales channels company reference ID and API key respectively!

Headers

As well as the Authorization header mentioned above, please also include the Content-Type header with the value application/json, as shown below.

Content-Type: application/json

Submitting an Order

An order can be created by sending a JSON encoded order object via a POST request to the API.

The API may split orders if separate lines need to be routed to different fulfillers.

Duplicate orders (based on the value of the external_ref field) will be rejected.

Order Object

Bold text denotes a required field
† denotes a field which the API will try to auto populate if left blank

Name	Type	Description
external_ref	string	A unique reference code that can be used to identify the order in your system.
company_ref_id	integer	A unique company ID (supplied by Kornit^X).
sale_datetime	string	The date and time (must be UTC) of when the order was placed in the format `YYYY-MM-DD HH:MM:SS` (i.e. 2023-04-30 10:54:23)
required_dispatch_date	string	The required dispatch date for the order in the format `YYYY-MM-DD` (i.e. 2023-04-30)
customer_name	string	Customer's full name.
customer_email	string	Customer's contact email.
customer_telephone	string	Customer's contact telephone number.
shipping_company	string	Shipping address company.
shipping_address_1	string	Shipping address 1.
shipping_address_2	string	Shipping address 2.
shipping_address_3	string	Shipping address 3.
shipping_address_4	string	Shipping town or city.
shipping_address_5	string	Shipping region.
shipping_postcode	string	Shipping post or ZIP code.
shipping_country_code	string	ISO 3166-1 alpha-2 country code.
shipping_method	string	Shipping method.
shipping_carrier	string	Shipping carrier.
shipping_note_url	string	An optional URL for a specifying an external shipping note. If no value is provided then a basic shipping note will be generated. The URL must begin with either `http://` or `https://`.
billing_customer_name	string	Billing name.
billing_company	string	Billing address company.
billing_address_1	string	Billing address 1.
billing_address_2	string	Billing address 2.
billing_address_3	string	Billing address 3.
billing_address_4	string	Billing town or city.
billing_address_5	string	Billing region.
billing_postcode	string	Billing post or ZIP code.
billing_country_code	string	Billing country code.
coupon_code	string	Coupon code.
payment_trans_id	string	Payment transaction identifier.
status_callback_url	string	Order status callback URL.
attributes	array	An array of order level attributes such as TaxID or additional require information
items	array	An array of order item objects.

Item Object

Bold text denotes a required field
† denotes a field which the API will try to auto populate if left blank

Name	Type	Description
external_ref	string	A reference code that can be used to identify the order item in your system.
sku^†	string	Product SKU.
description^†	string	Product description.
quantity	integer	Item quantity.
colour^†	string	Item colour.
size^†	string	Item size.
textual_product_id	integer	Determines which Catalog product the order item is for (can be used for either textual items or external URL items).
type	integer	Item type code. Please see the Item Type Codes Table below and the “Which Order Item Type is Right for Me?“ page.
external_url	string	Required for external items (type 1). URL to an image which will be used for this item. This URL must be available until the order has been processed.
external_thumbnail_url	string	Required for external items (type 1). URL to a thumbnail of an image which will be used for this item. This URL must be available until the order has been processed.
print_job_ref	string	Required for print job items (type 2). A unique identifier linking this item to an already existing print job (created by a Kornit X Smartlink). The specified print job must have been created using a company ID which the current API key (URL parameter k) is permitted access to.
print_on_demand_ref	string	Required for print on demand items (type 3). A unique identifier linking this item to a pre-created Print-on-Demand sample (created from within the Kornit X Catalog Module).
external_urls	array	Required for external URL (multi) items (type 7). An array of ExternalUrl objects.
attributes	array	An array of item level attributes

ExternalUrl Object

Bold text denotes a required field

Name	Type	Description
fullsize	string	A public URL to full-sized print ready artwork.
thumbnail	string	A public URL to a thumbnail of the artwork.
name	string	Position name, i.e. Front or Back. The given name must correlate to the products' print area name set in the Catalog module

Item Type Codes

Type Code	Name	Description
1	External URL	An item that you have print ready artwork that is available on a publicly accessible URL (not hosted by Kornit^X).
2	Print Job	An item that is associated with a print job created using a Kornit^X Smartlink. Once an order has been created, any referenced print jobs will have their artwork queued for generation.
3	Print-on-Demand	An item that can be associated to a pre-created Print-on-Demand product in the Kornit^X platform. This item type is falling out of general use and submitting items as textual along with the textual product ID and variant details is used in most cases.
4	Stock Item	A item that does not have any generated artwork.
5	Textual Item	An item that does not have artwork generated by Kornit X but does have text and/or image personalisation submitted as attributes.
7	External URL [Multi]	Identical to the External URL type but allows for multiple images to be provided. i.e. for a t-shirt that has a Front and a Back print.

Example Request Body

JSON

{
   "external_ref":"TEST-0001",
   "company_ref_id":99999,
   "sale_datetime":"2023-04-30 15:20:01",
   "customer_name":"Kornit X",
   "customer_email":"test@example.com",
   "shipping_address_1":"Shipping Address 1",
   "shipping_address_2":"Shipping Address 2",
   "shipping_address_3":"Shipping Address 3",
   "shipping_address_4":"Shipping Address 4",
   "shipping_address_5":"Shipping Address 5",
   "shipping_postcode":"Shipping Postcode",
   "shipping_country":"Shipping Country",
   "shipping_country_code":"GB",
   "shipping_method":"Shipping Method",
   "shipping_carrier":"Shipping Carrier",
   "shipping_tracking":"Shipping Tracking",
   "billing_address_1":"Billing Address 1",
   "billing_address_2":"Billing Address 2",
   "billing_address_3":"Billing Address 3",
   "billing_address_4":"Billing Address 4",
   "billing_address_5":"Billing Address 5",
   "billing_postcode":"Billing Postcode",
   "billing_country":"Billing Country",
   "payment_trans_id":"0123456789ABC",
   "status_callback_url":"https://mydomain.com/order/status/orderid",
   "attributes":[
            {
               "name":"TaxID",
               "value":"123456789"
            },
   "items":[
      {
         "sku":"Tshirt",
         "external_ref":"TEST-0001-01",
         "description":"Tshirt",
         "quantity":1,
         "type":1,
         "external_url":"http://my.gateway3d.com/ep/output/output_viewer/0/49020//49020_final.png",
         "external_thumbnail_url":"http://my.gateway3d.com/ep/output/output_viewer/0/49020/49020_thumbnail.png"
      },
      {
        "sku":"Tshirt",
         "external_ref":"TEST-0001-02",
         "description":"Tshirt",
         "quantity":1,
         "type":2,
         "print_job_ref":"ABCDEFGHIJKLM"
      },
      {
        "sku":"Tshirt",
         "external_ref":"TEST-0001-03",
         "description":"Tshirt",
         "quantity":1,
         "type":3,
         "print_on_demand_ref":"hjldskhfj"
      },
      {
        "sku":"Tshirt",
         "external_ref":"TEST-0001-04",
         "description":"Tshirt",
         "quantity":1,
         "type":5,
         "attributes":[
            {
               "name":"Date_of_birth",
               "value":"11/11/1988"
            },
            {
               "name":"First_Name",
               "value":"James"
            }
         ]
      },
      {
        "sku":"Tshirt",
         "external_ref":"TEST-0001-05",
         "description":"Tshirt",
         "quantity":1,
         "type":5,
         "colour":"White",
         "size":"XL",
        "textual_product_id":1234567,
      },
      {
        "sku":"Tshirt",
         "external_ref":"TEST-0001-06",
         "description":"Tshirt",
         "quantity":1,
         "type":7,
         "external_urls":[
            {
               "name":"front",
               "fullsize":"http://www.gateway3d.com/wp-content/uploads/2016/10/Custom-Gateway-250-x-56.png",
               "thumbnail":"http://www.gateway3d.com/wp-content/uploads/2016/10/Custom-Gateway-250-x-56.png"
            },
            {
               "name":"back",
               "fullsize":"http://www.gateway3d.com/wp-content/uploads/2016/10/Custom-Gateway-250-x-56.png",
               "thumbnail":"http://www.gateway3d.com/wp-content/uploads/2016/10/Custom-Gateway-250-x-56.png"
            }
         ]
      }
   ]
}

Status Callbacks

Every time an order's status changes in the Kornit X platform, the URL that you specified in the status_callback_url field will be sent a PUT request with a JSON encoded request body.

Your status callback should return a 200 HTTP response code if successful. In the event of a 4XX or 5XX error response code, Kornit X will keep retrying the request up to a maximum of 5 times at 2 hour intervals. For statuses that you are not interested in, please be sure to still reply with a 200 response code to prevent unnecessary retries.

It is highly recommended that your status callback URL can only be access via HTTPS.

It is highly recommended that your status callback URL is unique for each of your orders (i.e. by using a token that is tied to the order and is impossible to guess).

Don't forget that the API may have split your order if it needed to be fulfilled by multiple suppliers. It's your responsibility to consolidate the status callbacks.

Request Fields

Name	Type	Description
id	Number	The unique sequential ID of the order.
ref	String	The unique alphanumeric reference code of the order.
external_ref	String	The order reference number provided when creating the order.
shipping_tracking	String	A shipment tracking ID. This field may be blank and its population is dependent on the product supplier.
status	Number	The status code of the current status of the order.
status_name	String	The status name of the current status of the order.
shipping_method	String	The shipping method that will be used for shipping the order.
shipping_carrier	String	The shipping carrier that will be used for shipping the order.
shipping_price	Number	The shipping price of the order.
new_shipments	Array	An array of new shipment objects for one or more items in the order.
new_cancellations	Array	An array of new cancellation objects for one or more items in the order.
required_dispatch_date	String	The orders required dispatch date in the format “YYYY-MM-DD”.

The new_shipments object

Name	Type	Description
dispatch_datetime	String	The time and date of the shipment in the format “YYYY-MM-DD HH:MM:SS”.
tracking	String	The tracking ID of the shipment.
tracking_url	String	A tracking URL if provided by the carrier
items	Array	An array of item objects contained within the shipment.

The new_shipments item object

Name	Type	Description
quantity	Number	The quantity shipped.
ref	String	The Kornit^X item ref of the item being shipped.
external_ref	String	The external ref of the item being shipped.

The new_cancellations object

Name	Type	Description
cancellation_datetime	String	The time and date of the cancellation in the format “YYYY-MM-DD HH:MM:SS”.
items	Array	An array of item objects contained within the cancellation.

The new_cancellations item object

Name	Type	Description
quantity	Number	The quantity cancelled.
ref	String	The Kornit^X item ref of the item being cancelled.
external_ref	String	The external ref of the item being cancelled.

The shipping_carrier and shipping_method values may be different to what was specified during order creation. It is common for the values of both fields to mapped to different but equivalent values that the supplier is able to accept.

For example, if Standard Delivery Next Day is specified as the shipping_method during order creation, it may be mapped to Royal Mail and RM1 for shipping_carrier and shipping_method by the fulfiller.

Please do not rely on status_name being constant. It should be used for display purposes only. Any logic should be based on the status field which is guaranteed to remain constant for each status.

JSON

{
   "id":46467232,
   "ref":"A13EE287640A5EF1",
   "external_ref":"PAHTEST000121",
   "shipping_tracking":"JD12578404919C",
   "status":8,
   "status_name":"Dispatched",
   "shipping_method":"stamps_com|usps_first_class_mail",
   "shipping_carrier":"Shipstation",
   "shipping_price":2.99,
   "new_shipments":[
      {
         "dispatch_datetime":"2023-03-30 07:43:12",
         "tracking":"JD12578404919C",
         "tracking_url":"https://www.url.com/123456",
         "items":[
            {
               "quantity":1,
               "ref":"9F312934EA6",
               "external_ref":"123456789000"
            }
         ]
      }
   ],
   "new_cancellations":[
      
   ],
   "required_dispatch_date":"2023-03-30"
}

Statuses

Generally your status callback would not need to handle all possible order statuses.

* denotes a status that you should handle at a minimum.

Status Code	Status Name	Description
0	Unknown	The status of the order is unknown.
1*	Received	The order has been received by Kornit X.
2	Unused	Unused
4	In Production	(Only when batching is enabled) At least a part of the order has been downloaded by a fulfilment operative.
8*	Dispatched	The order has been fully dispatched.
32	QC Query	The order has a QC query against it.
64	Dispatched (Retailer Notified)	Dispatch confirmation has been explicitly pushed to the Sales Channel by Kornit^X.
128	Cancelled	The order has been cancelled.
256	On Hold	The order is on hold.
512	Sent to Supplier	The order has been routed to an appropriate supplier.
513	Received by Supplier	The order has been confirmed as received by an appropriate supplier.
515	Sent to Shipper	The order details have been sent to a shipment courier (such as UPS or DPD).
516	Received by Shipper	The order details have been confirmed by a shipment courier.

For legacy reasons, it is recommended that you treat status codes 8 and 516 in the same manner. They both indicate that an order has been fulfilled and is on its way to the customer. Status code 8 may be deprecated in the future.

Please read the Order Status Notifications page for more information on order status callbacks, along with some additional functionality.

Errors

API Errors

An example HTTP 400 error response body

JSON

{
    "error": {
        "code": 12345,
        "message": "A brief description of the problem"
    }
}

An example HTTP 500 error response body

JSON

{
    "error": {
        "code": null,
        "message": "An unexpected error occured 84C1E94BAF83D9C2A43CFCCBC04FE937"
    }
}

When the API encounters an error, it will return either a 400 or 500 HTTP status code along with a JSON encoded error response.

The 500 HTTP status code indicates an internal error that should be reported to us. Please quote the full error message, including the long alphanumeric identifier.

The JSON encoded error response will contain both an error code and a message.

The error code in the response is different to the HTTP status code.

Error Code	Meaning	Solution
0	Please check the error message for more details
100	Invalid JSON	Please check the error message for details on syntax errors etc.
8000	No items	At least one order item must be specified
8001	An order already exists with the specified value for `external_ref`	Ensure that `external_ref` is unique for each order
8011	Invalid `sale_datetime`	`sale_datetime` must be in the correct format and not in the future.
8012	Invalid `status_callback_url`	`status_callback_url` must be a valid URL and have a public DNS entry
8013	Invalid country code	`shipping_country_code` must be valid 2 character ISO 3166-1 alpha-2 country codes
8014	Invalid `required_dispatch_date`	`required_dispatch_date` must be in the correct format and not in the past.
8030	Order `company_ref_id` not specified
8031	Order `external_ref` not specified
8032	Order `shipping_address_1` not specified
8033	Order `shipping_postcode` not specified
8034	Order `shipping_country_code` not specified
8040	Invalid item `type`
8041	Invalid item `quantity`	`quantity` must be greater than 0
8042	Invalid item attribute for a textual item	The attribute must exist as an image or text area on the specified product
8043	Invalid item print job	The `print_job_ref` field must be valid and be a print job that is owned by your account
8050	Item `external_ref` not specified
8051	Item `print_job_ref` not specified
8052	Item `textual_product_id` not specified
8053	Item `external_url` not specified
8054	Item `external_thumbnail_url` not specified
50000	Either your company reference ID or API key are incorrect	Please make sure your details are correct
50001	Your company type does not allow receiving orders	Please contact support
50002	Your company has been deactivated
50003	The IP address used to send the request does not appear in the IP white list
50004	The rate limit has been exceeded	Please contact support

Administrative Errors

An example response for when an order is created in an error state

JSON

[
    {
        "id": "...",
        "external_ref": "TEST001",

        ...,

        "has_error": true,
        "error_message": "Failed to split order due to invalid supplier information",

        "items": [
            {
                "id": "...",

                ...
            }
        ]
    }
]

In certain circumstances, the API might return a success response code but create an order that is in an error state.

Such error states can be dealt with by non-technical staff and do not represent issues with how the API has been used.

One example scenario could be if the API is unable to correctly determine the supplier of an order line due to a misconfigured product in the Catalog module.

When an administrative error occurs, the order fields has_error and error_message will be populated with true and an error message respectively. The order status will also be set to QC Query.