Production Hub & OMS API Documentation

1. General API Information

Our RESTful API enables interaction with the Order Management System (OMS).

Setup and Requirements:

Contact our support team to set up API access and receive credentials.
Use API tokens for authentication (see Authentication section).
Store IDs are required for API calls (see Store IDs section).
Multiple stores may be associated with one account.

Responses:

All responses are in JSON format.
Standard HTTP status codes are used.

Common status codes:

Code	Meaning
200	Success
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
500	Server Error

Error responses include details about the issue in JSON format.

2. Authentication

Our API uses token-based authentication.

Key points:

We manually generate a unique API token for each client.
Tokens are provided securely off-band, not through the API.
Include the token in all API requests via the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Security notes:

Keep your token confidential.
Don't expose it in client-side code.
Contact support immediately if you suspect token compromise.
Tokens don't expire automatically.
We'll notify you if token regeneration is necessary.

For token rotation or authentication questions, contact our support team.

3. Store IDs

We manually create and assign store IDs for each client.

Key points:

Store IDs are unique identifiers for your stores.
Include the store ID in all relevant API requests.
Use the following parameter in your API calls:

Parameter	Description
store_id	Your unique store identifier

Contact our support team to obtain your store ID(s).

4. Order Endpoints

4.1 Create Order (POST)

Endpoint: /api/v1/orders
Creates a new order in the system.

Parameters

Parameter	Required	Type	Description
store_id	Yes	string	Your unique store identifier
items	Yes	array	Array of items in the order
ecommerce_order_id	Yes	string	ID of the order in your ecommerce system
ecommerce_order_number	No	string	Order number from your ecommerce system
total_price	No	number	Total price of the order
subtotal_price	No	number	Subtotal price of the order
currency_code	No	string	Currency code for the order
customer	No	object	Object containing customer details
note	No	string	Additional notes for the order
addresses	No	array	Array of address objects for the order
shippings	No	array	Array of shipping objects for the order
create_print_files	No	boolean	Specifies if individual print files should be created for all order items immediately. When a print file is generated, we can send a webhook or call an external API to notify when certain order items from ecommerce are ready to be printed.

Customer Object (Optional)

Parameter	Required	Type	Description
email	No	string	Customer's email address
ecommerce_customer_id	No	string	Customer's ID in your ecommerce system
name	No	string	Customer's first name
surname	No	string	Customer's last name
phone	No	string	Customer's phone number

Item Object

Parameter	Required	Type	Description
ecommerce_order_item_id	Yes	string	ID of the order item in your ecommerce system
ecommerce_variant_id	Yes	string	ID of the product variant in your ecommerce system
quantity	Yes	integer	Quantity of the item
price	No	number	Price per item
properties	No	object	Additional properties of the item
template_config	Yes	string	Template config generated from customiser. It's urlencoded json string
thumbnails	Yes	array	Array of strings representing thumbnail URLs
design_version_id	No	string	UID of the design version

Address Object (Optional)

Parameter	Required	Type	Description
type_id	Yes	string	Type of address ('billing' or 'shipping')
address_1	Yes	string	First line of the address
address_2	No	string	Second line of the address
post_code	Yes	string	Postal code
city	Yes	string	City name
county	No	string	County or province
country_code	Yes	string	Country code
country_id	No	integer	ID of the country

Shipping Object (Optional)

Parameter	Required	Type	Description
code	Yes	string	Shipping service code
shipping_price	Yes	number	Price of the shipping service

Response

A successful request will return the created order details.

{
  "uid": "ORDER_UID",
  "ecommerce_order_id": "ORD-001",
  "items": [
      {
          "uid": "ORDER_ITEM_UID",
          "ecommerce_order_item_id": "ORD_ITEM-001"
      }
  ]
}

4.2 Get Order (GET)

Endpoint: /api/v1/orders/{order_uid}
Retrieves details of a specific order.

Parameters

Parameter	Required	Type	Description
order_uid	Yes	string	UID of the order

Response

A successful request will return the order details (similar to the Create Order response).

4.3 Update Order (PUT)

Endpoint: /api/v1/orders/{order_uid}
Updates an existing order.

Parameters

Parameter	Required	Type	Description
order_uid	Yes	string	UID of the order
customer	No	object	Object containing customer details
items	No	array	Array of items in the order
ecommerce_order_number	No	string	Order number from your ecommerce system
total_price	No	number	Total price of the order
subtotal_price	No	number	Subtotal price of the order
currency_code	No	string	Currency code for the order
note	No	string	Additional notes for the order
addresses	No	array	Array of address objects for the order
shippings	No	array	Array of shipping objects for the order

Request Example

PUT /api/v1/orders/ORDER_UID
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "note": "Updated shipping instructions",
  "total_price": 69.98,
  "shippings": [
    {
      "code": "STANDARD",
      "shipping_price": 9.99
    }
  ]
}

Response

A successful request will return the updated order details.

4.4 Delete Order (DELETE)

Endpoint: /api/v1/orders/{order_uid}
Deletes a specific order.

Parameters

Parameter	Required	Type	Description
order_uid	Yes	string	UID of the order

Response

A successful request will return a confirmation of deletion.

{
  "message": "Order successfully deleted",
  "order_uid": "ORDER_UID"
}

5. Order Items Endpoints

5.1 Get Order Item Print File (GET)

Endpoint: /api/v1/order-items/{ecommerce_order_item_id}/print

Retrieves the print file status and URL for a specific order item.

Description

This endpoint allows you to check the status of a print file for a specific order item and retrieve the URL of the print file when it's ready. The print file goes through various processing stages before it becomes available for download.

Parameters

Parameter	Required	Type	Description
ecommerce_order_item_id	Yes	string	ID of the order item in your ecommerce system

Response

The response will include the status of the print file and, if ready, the URL to download it.

{
  "ecommerce_order_item_id": "ITEM-001",
  "status": "ready",
  "url": "https://example.com/print-files/ITEM-001.pdf"
}

Print File Statuses

The status field in the response can have the following values:

received: The order item has been received and is queued for processing.
processing: The print file is currently being generated.
processingfailed: There was an error during the print file generation process.
ready: The print file has been successfully generated and is ready for download.

Response Examples

When the print file is still processing:

{
  "ecommerce_order_item_id": "ITEM-002",
  "status": "processing",
  "url": null
}

When the print file generation has failed:

{
  "ecommerce_order_item_id": "ITEM-003",
  "status": "processingfailed",
  "url": null
}

When the print file is ready:

{
  "ecommerce_order_item_id": "ITEM-004",
  "status": "ready",
  "url": "https://example.com/print-files/ITEM-004.pdf"
}

{warning} The url field will only contain a value when the status is ready. For all other statuses, url will be null.

6. Product Categories Endpoints

6.1 Create Product Category (POST)

Endpoint: /api/v1/product-categories
Creates a new product category.

Parameters

Parameter	Required	Type	Description
name	Yes	string	Name of the category
parent_id	No	string	UID of the parent category
description	No	string	Description of the category
default_dpi	No	integer	Default DPI for the category. Set to 300 by default.
editor_category_id	No	string	UID of the editor category
default_location_id	No	string	UID of the default location

Request Example

POST /api/v1/product-categories
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "name": "T-Shirts",
  "parent_id": aef6d9d6-4cc6-4b45-bccf-aab97e886440,
  "description": "All types of T-Shirts",
  "default_dpi": 300,
  "editor_category_id": "8jeu2oo9",
  "default_location_id": 3bb7725c-11ea-4487-99f8-e025fc6617ac
}

Response

A successful request will return the created product category details.

6.2 Get Product Category (GET)

Endpoint: /api/v1/product-categories/{category_id}
Retrieves details of a specific product category.

Parameters

Parameter	Required	Type	Description
category_id	Yes	string	UID of the product category

Response

A successful request will return the product category details.

6.3 Update Product Category (PUT)

Endpoint: /api/v1/product-categories/{category_id}
Updates an existing product category.

Parameters

Parameter	Required	Type	Description
category_id	Yes	string	UID of the product category
name	No	string	Name of the category
parent_id	No	string	UID of the parent category
description	No	string	Description of the category
default_dpi	No	integer	Default DPI for the category
editor_category_id	No	string	UID of the editor category
default_location_id	No	string	UID of the default location

Request Example

PUT /api/v1/product-categories/1 Authorization: Bearer YOUR_API_TOKEN Content-Type: application/json

{
  "name": "Premium T-Shirts",
  "default_dpi": 600
}

Response

A successful request will return the updated product category details.

6.4 Delete Product Category (DELETE)

Endpoint: /api/v1/product-categories/{category_id}
Deletes a specific product category.

Parameters

Parameter	Required	Type	Description
category_id	Yes	string	UID of the product category

Response

A successful request will return a confirmation of deletion.

{
  "message": "Product category successfully deleted",
  "category_id": 1
}

7. Products Endpoints

7.1 Create Product (POST)

Endpoint: /api/v1/products
Creates a new product.

Parameters

Parameter	Required	Type	Description
category_id	Yes	integer	ID of the product category
name	Yes	string	Name of the product
code	No	string	Product code
order_column	Yes	integer	Order of the product in listings
active	Yes	boolean	Whether the product is active
description	No	string	Description of the product
default_dpi	No	integer	Default DPI for the product
team_id	Yes	integer	ID of the team associated with the product
editor_category_id	No	string	ID of the editor category
default_location_id	No	integer	ID of the default location

Request Example

POST /api/v1/products Authorization: Bearer YOUR_API_TOKEN Content-Type: application/json

{ "category_id": 1, "name": "Classic White T-Shirt", "code": "CWT001", "order_column": 1, "active": true, "description": "A comfortable, classic white t-shirt", "default_dpi": 300, "team_id": 5, "editor_category_id": "TSHIRT_CAT", "default_location_id": 2 }

Response

A successful request will return the created product details, including the auto-generated UUID.

7.2 Get Product (GET)

Endpoint: /api/v1/products/{product_id}
Retrieves details of a specific product.

Parameters

Parameter	Required	Type	Description
product_id	Yes	integer	Unique identifier of the product

Response

A successful request will return the product details.

7.3 Update Product (PUT)

Endpoint: /api/v1/products/{product_id}
Updates an existing product.

Parameters

Parameter	Required	Type	Description
product_id	Yes	integer	Unique identifier of the product
category_id	No	integer	ID of the product category
name	No	string	Name of the product
code	No	string	Product code
order_column	No	integer	Order of the product in listings
active	No	boolean	Whether the product is active
description	No	string	Description of the product
default_dpi	No	integer	Default DPI for the product
team_id	No	integer	ID of the team associated with the product
editor_category_id	No	string	ID of the editor category
default_location_id	No	integer	ID of the default location

Request Example

PUT /api/v1/products/1 Authorization: Bearer YOUR_API_TOKEN Content-Type: application/json

{ "name": "Premium White T-Shirt", "active": false, "default_dpi": 600 }

Response

A successful request will return the updated product details.

7.4 Delete Product (DELETE)

Endpoint: /api/v1/products/{product_id}
Deletes a specific product.

Parameters

Parameter	Required	Type	Description
product_id	Yes	integer	Unique identifier of the product

Response

A successful request will return a confirmation of deletion.

{ "message": "Product successfully deleted", "product_id": 1 }

8. Product Variants Endpoints

8.1 Create Product Variant (POST)

Endpoint: /api/v1/product-variants
Creates a new product variant.

Parameters

Parameter	Required	Type	Description
uuid	No	string	Unique identifier (36 characters)
name	Yes	string	Name of the product variant
product_variant_category_id	No	integer	ID of the product variant category
product_id	Yes	integer	ID of the associated product
price_id	No	integer	ID of the associated price
editor_product_id	No	string	ID of the editor product
weight	No	integer	Weight of the variant (unsigned)
length	No	integer	Length of the variant
width	No	integer	Width of the variant
height	No	integer	Height of the variant
description	No	string	Description of the variant
country_id	Yes	integer	ID of the associated country
customs_code	No	string	Customs code for the variant
customs_description	No	string	Customs description
long_customs_description	No	string	Long customs description
default_dpi	No	integer	Default DPI for the variant (unsigned)
seo_details	No	string	SEO details for the variant
ecommerce_tags	No	string	E-commerce tags (comma-separated)
default_location_id	No	integer	ID of the default location

Request Example

POST /api/v1/product-variants
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "name": "Classic White T-Shirt - Large",
  "product_id": 1,
  "country_id": 1,
  "weight": 200,
  "length": 70,
  "width": 50,
  "height": 5,
  "description": "Large size of our classic white t-shirt",
  "default_dpi": 300,
  "ecommerce_tags": "tshirt,white,large"
}

Response

A successful request will return the created product variant details, including the auto-generated ID.

8.2 Get Product Variant (GET)

Endpoint: /api/v1/product-variants/{variant_id}
Retrieves details of a specific product variant.

Parameters

Parameter	Required	Type	Description
variant_id	Yes	integer	Unique identifier of the product variant

Response

A successful request will return the product variant details.

8.3 Update Product Variant (PUT)

Endpoint: /api/v1/product-variants/{variant_id}
Updates an existing product variant.

Parameters

Parameter	Required	Type	Description
variant_id	Yes	integer	Unique identifier of the product variant
name	No	string	Name of the product variant
product_variant_category_id	No	integer	ID of the product variant category
product_id	No	integer	ID of the associated product
price_id	No	integer	ID of the associated price
editor_product_id	No	string	ID of the editor product
weight	No	integer	Weight of the variant (unsigned)
length	No	integer	Length of the variant
width	No	integer	Width of the variant
height	No	integer	Height of the variant
description	No	string	Description of the variant
country_id	No	integer	ID of the associated country
customs_code	No	string	Customs code for the variant
customs_description	No	string	Customs description
long_customs_description	No	string	Long customs description
default_dpi	No	integer	Default DPI for the variant (unsigned)
seo_details	No	string	SEO details for the variant
ecommerce_tags	No	string	E-commerce tags (comma-separated)
default_location_id	No	integer	ID of the default location

Request Example

PUT /api/v1/product-variants/1
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "name": "Classic White T-Shirt - Extra Large",
  "weight": 220,
  "length": 75,
  "width": 55,
  "height": 5,
  "description": "Extra large size of our classic white t-shirt",
  "ecommerce_tags": "tshirt,white,xl,extra-large"
}

Response

A successful request will return the updated product variant details.

8.4 Delete Product Variant (DELETE)

Endpoint: /api/v1/product-variants/{variant_id}
Deletes a specific product variant.

Parameters

Parameter	Required	Type	Description
variant_id	Yes	integer	Unique identifier of the product variant

Response

A successful request will return a confirmation of deletion.

{
  "message": "Product variant successfully deleted",
  "variant_id": 1
}

9. Batch Order Endpoints

9.1 Create Batch Order (POST)

Endpoint: /api/v1/batch-orders
Creates a new batch order to combine multiple items into a single print file.

Description

Batch orders allow you to combine multiple order items from different orders into a single print file. This is useful for optimizing the printing process and managing large volumes of orders efficiently. Print templates are created manually in the dashboard and assigned to product variants.

When a print file is generated, we can send a webhook or call an external API to notify when certain order items from ecommerce are ready to be printed.

Parameters

Parameter	Required	Type	Description
order_items	Yes	array	Array of order item UIDs to be included in the batch
print_templates	Yes	array	Array of print template UIDs to be used for the batch

Request Example

POST /api/v1/batch-orders
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

{
  "order_items": ["ITEM_UID_1", "ITEM_UID_2", "ITEM_UID_3"],
  "print_templates": ["TEMPLATE_UID_1", "TEMPLATE_UID_2"]
}

Response

A successful request will return the created batch order details, including its status.

{
  "uid": "BATCH_ORDER_UID",
  "status": "Batching"
}

Batch Order Statuses

The status field in the response can have the following values:

Batching
Batched
ProcessingFailed
Archiving
Archived
Downloading
Downloaded
Printed
Complete

These statuses represent the various stages of the batch order process, from initial creation to completion.

Introduction