Order-iT Integration
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 thanapplication/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. |