Skip to content
On this page

Orders

You can push order data from your application to have access to these orders from within Colorlab. This allows you to quickly access customizations in Colorlab by order.

The order endpoints allow you to create, update and delete orders in Colorlab along with customizations.

To retrieve orders, you need to query your own application as this is the source of where orders originate, whereas Colorlab simply acts as a hub for displaying this data.

INFO

  • as per specification of the GDPR, Colorlab is required to only store orders that contain customizations. You need to skip orders without customizations.
  • when pushing order data, you are required to implement all endpoints to ensure that the order data matches the order data in your application at all times.
  • the API will return a status code in the 2xx range (e.g. 200 or 201) when the data is successfully received. You need to implement re-try behaviour to make sure you receive a status code in this range when pushing orders to prevent missing order data in Colorlab.

Please take into account the best practices when implementing these API calls as costs may apply depending on the available amount of orders in your plan.

Changelog

Version 2022-08 (latest)

https://api.colorlab.io/2022-08/orders

  • the endpoint URL ends with orders instead of order
  • all properties of the order object are now required. Empty properties (e.g. companyName) should be sent as an empty string.
  • added required property domain to replace the x-colorlab-domain header containing the domain the order was created on.

Version v1

https://api.colorlab.io/v1/order Initial API version. Will be deprecated in August 2023. Please update your implementation to point to the latest API version.

Creating an order

To create an order, use the POST http method to send a JSON payload to the following endpoint:

POST https://api.colorlab.io/2022-08/orders
1

Each order has 3 properties that ensure the order is unique:

  • Store ID: the Store ID sent using the X-Colorlab-Shop header
  • Order ID: the Order ID sent as the orderId property in the order object. This is the Order ID used in your online store (e.g. ORD867)
  • Domain: The domain sent as the domain property in the order object. This is the domain on which the order was placed (e.g. your-online-store.com). This is the configured domain in your Colorlab account. Contact Colorlab Support to update the domains you are using Colorlab on.

Example order object

json
{
  "billingDetails": {
    "address1": "123 Amoebobacterieae St",
    "address2": "",
    "city": "Ottowa",
    "companyName": "",
    "country": "Canada",
    "countryCode": "CA",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "555-625-1199",
    "province": "KY",
    "zip": "40202"
  },
  "created": "2022-04-20T13:45:08.672Z",
  "domain": "colorlab.io",
  "email": "john.doe@gmail.com",
  "firstName": "John",
  "lastName": "Doe",
  "lineItems": [
    {
      "id": 123,
      "token": "a462a062-7987-4a44-b35f-7009b141fb33",
      "quantity": 2,
      "price": 12.5
    }
  ],
  "orderId": "ORD789",
  "shippingDetails": {
    "address1": "123 Amoebobacterieae St",
    "address2": "bus 2",
    "city": "Ottowa",
    "companyName": "John Doe's Cookie Factory",
    "country": "Canada",
    "countryCode": "CA",
    "firstName": "John",
    "lastName": "Doe",
    "phone": "555-625-1199",
    "province": "KY",
    "zip": "40202"
  },
  "status": "Created",
  "updated": "2022-04-20T13:45:08.672Z"
}
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

Order properties

PropertyDescription
billingDetails
object
Object containing the customers' billing details. All properties are required. Use empty strings for empty values (e.g. when no company name was given)
created
date
Date when the order was created by the customer. Dates are formatted in ISO-8601 format (e.g. 2022-01-31T13:45:08.672Z. Example generation in javascript: var d = new Date(); d.toISOString();)
domain
string
The domain on which the order was placed (e.g. yourdomain.com)
email
string
Email address of the customer (this should be a valid email address)
firstName
string
First name of the customer
lastName
string
Last name of the customer
lineItems
array
An array of objects, describing the line items in the order
orderId
string
the Order ID used in your online store. The combination of orderId + storeId + domain must be unique.
shippingDetails
object
Object containing details where the order is shipped to. All properties are required. Use empty strings for empty values (e.g. when no company name was given)
status
string
Current status of the order (can be any string)
updated
date
Date when the order was last updated by the customer. Dates are formatted in ISO-8601 format (e.g. 2022-01-31T13:45:08.672Z. Example generation in javascript: var d = new Date(); d.toISOString();)

Line item object properties

PropertyDescription
id
int
The integer representing the ID of the customization in Colorlab
token
string
The token unique for accessing this customization
quantity
int
The amount ordered
price
double
The price of a single item

Updating an order

To update an order, use the POST http method to send the JSON payload to the following endpoint:

POST https://api.colorlab.io/2022-08/orders/:id
1

And replace :id with the Order ID of the order that was created before.

Example

Uses the exact same JSON object as the create endpoint.

Deleting an order

To delete an order, use the DELETE http method to the following endpoint:

DELETE https://api.colorlab.io/2022-08/orders/:id
1

You don't need to POST any data to delete an order.

Generating the signature

Create a verification string containing this data: Store ID + Order ID

Example: with values 589adada754c20089ed6cfd8 (Store ID) and ORD789 (Order ID), the verification string is:

589adada754c20089ed6cfd8ORD789

Now use your API secret to compute a sha256 HMAC signature. You can test the output using online generators like https://www.freeformatter.com/hmac-generator.html.

Use the resulting value in the X-Colorlab-Api-Signature header when requesting the API.