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.

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/v1/order
1

Each order has 3 properties that define a unique key for the order:

  • Shop: the Shop ID sent using the X-Colorlab-Shop header
  • OrderId: the Order ID used in your online store
  • Domain: The domain registered in Colorlab where the order was placed, sent using the X-Colorlab-Domain header.

Example

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

Order properties

PropertyDescription
orderIdthe Order ID used in your online store. Must be unique in combination with the Shop ID and the Domain
statusCurrent status of the order (can be any string)
emailEmail address of the customer
firstNameFirst name of the customer
lastNameLast name of the customer
billingDetailsObject containing all details of the customers' bill. Address 2 is optional.
shippingDetailsObject containing all details where the order is shipped to. Address 2 is optional.
createdDate when the order was created by the customer. Dates are formatted in ISO-8601 format (e.g. 2018-01-31T13:45:08.672Z. Example generation in javascript: var d = new Date(); d.toISOString();)
updatedDate when the order was last updated by the customer. Dates are formatted in ISO-8601 format (e.g. 2018-01-31T13:45:08.672Z. Example generation in javascript: var d = new Date(); d.toISOString();)
lineItemsAn array of objects, describing the line items in the order

Line item object properties

PropertyDescription
idThe integer representing the ID of the customization in Colorlab
tokenThe token unique for accessing this customization
quantityThe amount this item is ordered
priceThe total amount of this line item (when quantity > 1, use the total price, not 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/v1/order/: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/v1/order/:id
1

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

Generating the signature

Create a verification string containing this data: shop_id + orderId

Example: with values 123, abc and ORD789, the verification string is:

123ORD789

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.