API Version: 2.1

Overview

The Order-iT integration covers how an order can be sent to the Custom Gateway platform, after which it will be routed to a suitable supplier.

Requirements

  • A unique company reference ID (provided by Custom Gateway)
  • An alphanumeric private API key (provided by Custom Gateway)

Note Your API key and company reference ID form a pair which must be used together.

Orders and Items

An order consists of all of the information needed to fulfil and ship an order to a customer.

An order may have multiple items and each item can be one of four types.

Type Code Name Description
1 External URL an item for which the artwork is specified as an external URL (not hosted by Custom Gateway).
2 Print Job An item that can be associated with a print job created by the Custom Gateway product designer. Once an order has been created, any referenced print jobs will be set to “Paid” in the “Print Manager”.
3 Print-on-Demand An item that can be associated to a precreated Print-on-Demand sample.
4 Stock Item A item that does not have any generated artwork.
5 Textual Item An item that does not have artwork generated by Custom Gateway but does have textual personalisation.
6 Reserved / Internal Do not use
7 External URL [Multi] identical to the External URL type but allows for multiple images to be provided.

Creating an Order

Orders are created by sending a POST request to the order API endpoint.

https://api-sl-2-1.custom-gateway.net/order/?k={apikey}

Where {apikey} is your private API key provided by Custom Gateway.

  • The request body must be a JSON object.
  • The request body must be encoded as either UTF8 or plain ASCII. Any other encodings may cause issues.
  • The request content type must be application/json rather than application/x-www-form-urlencoded.
  • It is highly recommended that all URLs passed via the API (i.e. external artwork URLs or callback URLs) are specified as using HTTPS rather than HTTP. This recommendation may be enforced in the future due to browsers becoming much stricter in regards to insecure content. Please see Deprecating Non-Secure HTTP for more information.

Order Fields

* Denotes a required field

Name Type Description
external_ref string A reference code that can be used to identify the order in your system.
company_ref_id* integer A unique company ID (supplied by Custom Gateway). Must correspond to the API key provided via the URL.
status integer  
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. 2013-08-07 10:54:23)
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* string Shipping country.
shipping_country_code* string ISO 3166-1 alpha-2 country code.
shipping_method string Shipping method, may be specific to the fulfiller.
shipping_carrier string Shipping carrier.
shipping_tracking string Shipping tracking ID.
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_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 string Billing country.
coupon_code string Coupon code.
payment_trans_id string Payment transaction identifier.
status_callback_url string Order status callback URL.
items array An array of order items

Item Fields

Name Type Description
sku* string Product SKU of the item. The SKU is used to appropriately batch together items from across different orders. It must therefore match your fulfiller or supplier’s SKU for the same product.
external_ref string A reference code that can be used to identify the order item in your system.
description* string Product description.
quantity* integer Item quantity.
colour string Item colour.
size string Item size.
unit_cost_price decimal Unit cost price (only used for reporting purposes).
unit_sale_price decimal Unit sale price (only used for reporting purposes).
textual_product_id integer Determines which CPP product the order item is for (can be used for either textual items or external URL items).
type* integer Item type code
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 the Custom Gateway product designer). 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 Custom Gateway ACP).
external_urls array Required for multi external URL items (type 7). A collection of external URLs, please see the below example.

Example Request Body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
	"external_ref": "TEST-0001",
	"company_ref_id": 99999,
	"sale_datetime": "2013-09-26 15:20:01",
 
	"customer_name": "Custom Gateway",
	"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",
 
	"items": [
		{
			"sku": "IP4",
			"external_ref": "TEST-0001-01",
			"description": "iPhone 4",
			"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": "IP4",
			"external_ref": "TEST-0001-02",
			"description": "iPhone 4",
			"quantity": 1,
			"type": 2,
			"print_job_ref": "ABCDEFGHIJKLM"
		},
 
		{
			"sku": "IP4",
			"external_ref": "TEST-0001-03",
			"description": "iPhone 4",
			"quantity": 1,
			"type": 3,
			"print_on_demand_ref": "hjldskhfj"
		},
 
		{
			"sku": "IP4",
			"external_ref": "TEST-0001-05",
			"description": "iPhone 4",
			"quantity": 1, 	
			"type": 5,
			"attributes": [
				{ "name": "Date_of_birth", "value": "11/11/1988" },
				{ "name": "First_Name", "value": "James" }
			]
		},

		{
			"sku": "IP4",
			"external_ref": "TEST-0001-07",
			"description": "iPhone 4",
			"quantity": 1,
			"type": 7,
			"external_urls": [
				{
					"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"
				}
			]
		}
	]
}

Example Success Response

1
2
3
4
{
	"id": 12345,
	"ref": "abcdefgh"
}

Example Error Response

1
2
3
4
5
{
	"error": {
		"message": "Description of error"
	}
}

Note Either a 4XX or 5XX status code will be returned on error.

Common Errors

Message Reason Solution
Invalid key The API key provided is not valid or does not permit access to the account specified by company_ref_id. Use the appropriate API key.
Invalid item type One or more items have an invalid type code set in the type field. Use an appropriate type code (see below).
Invalid item print job. One or more items have an invalid print job ID specified in the print_job_id field Use the correct print job ID.
Print job company mismatch The value of the guid URL parameter used in the personalisation app to create the print job does not match the value of the company_ref_id field. The company reference ID used to create the order must match what was used to create the print job.
Print Job items must have either print_job_id or print_job_ref set. One or more items are set as print job items but are missing either the print_job_id or print_job_ref fields. The print_job_ref field must be set to the value returned from the personalisation app to your callback page.
Invalid external URL The URL set in the external_url field for an item of type external is not accessible. Use the correct URL.
Invalid external thumbnail URL The URL set in the external_thumbnail_url field for an item of type external is not accessible. Use the correct URL.
Invalid item sample ref One or more Print on Demand items have an incorrect value for the print_on_demand_ref field. Use a correct value for print_on_demand_ref.
Invalid item product   Please contact support@gateway3d.com
Print job has an invalid print size   Please contact support@gateway3d.com

Order Status Callbacks

A callback URL can be specified against an order using the status_callback_url field.

A PUT request with a content type of application/json will be made to the callback URL every time the status of the order changes (for example “Dispatched” or “Sent to Supplier”).

The body of the request shall be a JSON encoded object with the following fields:

Name Type Description
id integer The order’s unique sequential ID.
ref string The order’s reference (determined by the Print-iT system).
external_ref string The order’s external reference (specified by the creator of the order).
status integer The order’s status code
status_name string The status’ name. Please do not rely on this value being constant for each status code, Custom Gateway reserves the right to change the name of a status with no prior warning.

It is highly recommended that you implement your callback URLs in such a way that:

  • They are only valid for a specific order.
  • They are only valid for a specific amount of time.
  • They are served only over HTTPS.
  • They are not easily guessable.

Doing the above will help to ensure that malicious third parties are not able to discover and call your callback URLs.

1
2
3
4
5
6
7
{
	"id": 1234,
	"ref": "abcdefgh",
	"external_ref": "100000103",
	"status": 8,
	"status_name": "Dispatched"
}

The callback response should be a simple “true”

1
true

Order Statuses

Status Code Status Name Description
0 Unknown The status of the order is unknown.
1 Received The order has been received by Custom Gateway.
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 retailer by Custom Gateway.
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 confirm by a shipment courier.
517 Pending Dispatch The order is waiting to be confirmed with a shipper.