Orders

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.

INFO

• 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.

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 2023-10 (latest)
  • Version 2022-08
  • Version v1 (deprecrated)
• Creating an order
  • Example order object
  • Order properties
  • Line item object properties
• Updating an order
  • Example
• Deleting an order
• Generating the signature

Changelog

Version 2023-10 (latest)

• 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

• You can now use api 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)

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

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.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 https://www.freeformatter.com/hmac-generator.html.

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