When submitting orders to GelatoConnect via the API, you have two options for specifying products: using Product UIDs or using Customer Products. This guide explains both approaches, their benefits, and when to use each one.
Product UID Approach
The Product UID approach involves using unique product identifiers (UIDs) to specify products in your orders.
How It Works
When using Product UIDs, you include the productUid parameter in your order item:
{
"itemReferenceId": "ITEM-001",
"productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
"quantity": 1,
"files": [
{
"type": "default",
"url": "https://example.com/files/printfile.pdf"
}
]
}
Product UID Structure
A Product UID is a structured string that encodes product attributes. For example, in flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor:
flat_product: Product typepf_a4: Paper format (A4 size)pt_200-gsm-uncoated: Paper type (200 gsm uncoated paper)cl_4-0: Color configuration (4-color process on front, 0 colors on back)ct_none: Cutting (none)prt_none: Special printing effects (none)sft_none: Surface treatments (none)set_none: Special effects (none)hor: Orientation (horizontal)
Customer Products Approach
The Customer Products approach involves creating custom product definitions in GelatoConnect and referencing them by name and variant in your orders.
How It Works
First, you set up Customer Products in GelatoConnect, defining product names and their variant options. Then, when placing orders, you reference these products using the productName and productVariant parameters:
{
"itemReferenceId": "ITEM-001",
"productName": "Business Card",
"productVariant": {
"Size": "Standard",
"Paper": "Premium Matte",
"Color": "Full Color Both Sides"
},
"quantity": 100,
"files": [
{
"type": "front",
"url": "https://example.com/files/front.pdf"
},
{
"type": "back",
"url": "https://example.com/files/back.pdf"
}
]
}
Setting Up Customer Products
Before using Customer Products in your API orders, you need to set them up in GelatoConnect:
Navigate to the Products section in GelatoConnect
Create Customer Products with specific names and variant options
Map these Customer Products to Gelato's product specifications
When to Use Each Approach
Use Product UIDs When:
You're just getting started with GelatoConnect
You have a small number of fixed products
You want to implement quickly without additional setup
You're building a proof of concept or test implementation
Use Customer Products When:
You have a large product catalog
You want more intuitive product references in your code
Your product names differ from Gelato's naming conventions
Product configurations might change over time
Implementation Examples
Product UID Example
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"orderReferenceId": "ORDER-123",
"orderType": "order",
"currency": "USD",
"shippingAddress": {
"country": "US",
"firstName": "John",
"lastName": "Doe",
"addressLine1": "123 Main St",
"city": "New York",
"postCode": "10001",
"state": "NY",
"email": "[email protected]",
"phone": "123-456-7890"
},
"items": [
{
"itemReferenceId": "ITEM-001",
"productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
"quantity": 1,
"files": [
{
"type": "default",
"url": "https://example.com/files/printfile.pdf"
}
]
}
]
}'Customer Products Example
curl --location 'https://api.partner-connect.io/api/{partner-prefix}/order' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: your-key:your-secret' \
--data '{
"orderReferenceId": "ORDER-124",
"orderType": "order",
"currency": "USD",
"shippingAddress": {
"country": "US",
"firstName": "John",
"lastName": "Doe",
"addressLine1": "123 Main St",
"city": "New York",
"postCode": "10001",
"state": "NY",
"email": "[email protected]",
"phone": "123-456-7890"
},
"items": [
{
"itemReferenceId": "ITEM-001",
"productName": "Flyer",
"productVariant": {
"Size": "A4",
"Paper": "Uncoated 200gsm",
"Printing": "Full Color One Side"
},
"quantity": 100,
"files": [
{
"type": "default",
"url": "https://example.com/files/flyer.pdf"
}
]
}
]
}'
Best Practices
Regardless of which approach you choose, follow these best practices:
Consistency: Stick to one approach throughout your implementation
Documentation: Maintain clear documentation of your product mappings
Validation: Validate product identifiers before submitting orders
Testing: Thoroughly test with sample orders before going live
Error Handling: Implement robust error handling for invalid products
Transitioning Between Approaches
If you start with Product UIDs and later want to switch to Customer Products:
Set up your Customer Products in GelatoConnect
Map them to the Product UIDs you've been using
Update your API implementation to use productName and productVariant
Test thoroughly before deploying to production
The reverse transition is also possible but less common.
Conclusion
Both approaches have their merits, and the choice depends on your specific requirements and constraints. Product UIDs offer simplicity and direct access to Gelato's catalog, while Customer Products provide better readability, flexibility, and centralized management.
For most long-term implementations, Customer Products offer advantages in terms of maintainability and clarity. However, for quick implementations or specific use cases, Product UIDs may be preferable.
For more information on setting up Customer Products in GelatoConnect, refer to the Creating Customer Products guide.
📝 Not what you needed?
Help us improve this article, send us an email to [email protected] — please include the article title.