# Order endpoints You can **push order data** from your application to have access to these orders from within Printlane. This allows you to quickly access designs in Printlane by order. The order endpoints allow you to **create**, **update** and **delete** orders in Printlane along with designs. To retrieve orders, you need to query your own application as this is the source of where orders originate, whereas Printlane simply acts as a hub for displaying this data. - as per specification of the GDPR, Printlane is required to only store orders that contain designs. You need to **skip orders without designs**. - 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 Printlane. lease take into account the [best practices](https://support.printlane.com/en/articles/10470412-authentication-and-best-practices) when implementing these API calls as costs may apply depending on the available amount of orders in your plan. # Changelog ## Version 2026-01 (latest)**[​](https://help.printlane.com/api/media.html#version-2023-10-latest)** The only change is that the usage of the domain `colorlab.io` and headers containing `colorlab` are not allowed anymore. If you have already implemented these changes, you can simply use that latest version. ## Version 2023-10 - You can now use api version `2023-10` - The domain name of all API endpoints has changed from `colorlab.io` to `printlane.com`. - header `X-Colorlab-Shop` has changed to `X-Printlane-Store` (notice the change from `Shop` to `Store`) - header `X-Colorlab-Api-Key` has changed to `X-Printlane-Api-Key` - header `X-Colorlab-Api-Signature` has changed to `X-Printlane-Api-Signature` - Please find the overview of all URL changes below: | **New URL** | **Old URL** | | ---------------------------------------------- | -------------------------------------------- | | `https://api.printlane.com/2023-10/orders` | `https://api.colorlab.io/2022-08/orders` | | `https://api.printlane.com/2023-10/orders/:id` | `https://api.colorlab.io/2022-08/orders/:id` | ## Version 2022-08 - 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. - the endpoint URL ends with `orders` instead of `order` - Please find the overview of all URL changes below: | **New URL** | **Old URL** | | -------------------------------------------- | ------------------------------------------- | | `https://api.colorlab.io/2022-08/orders` | `https://api.colorlab.io/2022-08/order` | | `https://api.colorlab.io/2022-08/orders/:id` | `https://api.colorlab.io/2022-08/order/:id` | ## Version v1 (deprecrated)**[​](https://help.printlane.com/api/orders.html#version-v1-deprecrated)** 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.printlane.com/2023-10/orders ``` Each order has 3 properties that ensure the order is unique: - **Store ID**: the Store ID sent using the `X-Printlane-Store` 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 Printlane account. Contact Printlane Support to update the domains you are using Printlane 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": "printlane.com", "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 | **Property** | **Description** | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | **Property** | **Description** | | ----------------- | ---------------------------------------------------------- | | id ​`int` | The integer representing the ID of the design in Printlane | | token ​`string` | The token unique for accessing this design | | 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.printlane.com/2023-10/orders/:id ``` And replace `:id` with the Order ID of the order that was created before. ## Example**[​](https://help.printlane.com/api/orders.html#example)** Uses the exact same `JSON` object as the `create` endpoint. # Deleting an order**[​](https://help.printlane.com/api/orders.html#deleting-an-order)** To delete an order, use the `DELETE` http method to the following endpoint: ``` DELETE https://api.printlane.com/2023-10/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 . Use the resulting value in the `X-Printlane-Api-Signature` header when requesting the API.