Overview
This article explains how to create customer products in Gelato and use them when placing orders through Gelato's API. Customer products allow you to customize product configurations for different customers, linking their specific data format requirements to a standard product model.
A product model defines your product internally (e.g., its parts, attributes, and derived attributes), while a customer product allows you to tailor how customers send data and interact with your product when placing orders.
Steps to Create Customer Products
1. Set Up the Product Model
Before creating a customer product, ensure that you have a product model already set up. For example, let’s assume the product model is called Poster Product and it has 9 attributes and several derived attributes. (See the "Creating a Product Model" guide for details.)
2. Creating the Customer Product
A customer product is a customized version of your product model that reflects how your customer prefers to send data (e.g., size, color, etc.). Here's how to set up a customer product:
Step 1: Navigate to the Customer Products section.
Step 2: Select the product model (e.g., Poster Product) and give your customer product a name. This name is crucial because it will be used when placing an order through the API.
For example, let's call this product Poster SP for the customer Sandbox Customer.
Note: The customer product name can be used directly in order requests sent via Gelato's API.
Step 3: Set up Base Attributes and Variants:
Base Attributes are fixed attributes that are the same across all product variants.
Variants represent the customizable options, such as size, color, or paper type, that the customer can choose from.
3. Setting Base Attributes
Base attributes have a single, fixed value across all variants. For instance:
Orientation: Always vertical
Coating: No coating
These base attributes do not vary from one product variant to another.
4. Setting Variants
Variants are the product options your customer can select, such as size and color. Here's how to configure them:
Step 1: Add the customer’s options (e.g., size and color) and link them to the product model attributes.
Example: The customer wants to send in attributes named Size, Paper Type, and Color.
Step 2: Map customer-provided values to the internal product model attributes:
Color: The customer might call their color option "Black White" for black-and-white prints and "Full Color" for color prints. You can map these to the internal Gelato values "1/1" for black and white and "4/4" for full color.
Size: The customer might send in dimensions in inches, while you need to map those values to the internal metric system (e.g., 20x28 inches = 508x711 mm).
Step 3: Set a Default Value for attributes if needed. For example:
If the customer doesn’t provide a color option, you can set the default to Full Color (4/4).
Step 4: Configure multiple option values:
You can map multiple customer values to a single internal value. For example, a customer may use "Black White" or "BW" to indicate the same black-and-white print, and you can map both of these to your internal value of "1/1."
5. Saving the Customer Product
Once all attributes and variants are set up, save the customer product. You now have a customer product linked to the internal product model, allowing you to receive and process orders based on the customer’s preferred format.
Placing an Order via the API Using Customer Products
Once the customer product is set up, the customer can place orders through the Gelato API. Here's how that works:
1. The API Request Structure
When placing an order, the customer product name (e.g., Poster SP) will be used in the API request along with any selected options. Here's an example of an API request:
<pseudo code pending link to API reference docs>
{
"items": [
{
"productName": "Poster SP",
"productVariant": {
"color": "black-white",
"paper-size": "20x28-inch"
}
}
]
}
In this example:
The productName is set to Poster SP.
The productVariant includes the selected variant option values, such as "black-white" for color and "20x28-inch" for paper size.
2. Handling Multiple Customer Products
You can set up different customer products for different customers, each linking to the same product model but with different configurations. For example:
Customer A might send "paper size" and "color" as options.
Customer B might send "paper type" and "size" instead.
Despite these differences, both customer products will point to the same internal Product UID in Gelato’s system, ensuring consistent production processes under the hood.
3. Backward Compatibility
Gelato’s system supports backward compatibility with existing workflows, meaning you can continue using Product UIDs from older configurations while adopting new customer product setups in the flow configurator.