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.

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

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 ​

{
  "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"
}

Order properties ​

Line item object properties ​

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

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

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.