Lookups in GelatoConnect help standardize and translate your internal system data into formats Gelato can understand. This ensures your API orders are processed smoothly by resolving potential mismatches between your identifiers and Gelato's expected values. From mapping product SKUs and shipping methods to carrier codes and regional specifics, lookups are essential for maintaining a robust integration with minimal manual adjustments.

Understanding Lookups in GelatoConnect

Lookups function as translation tables that map custom values from your system to the corresponding standardized values required by Gelato. Without them, orders may fail due to mismatched identifiers.

Typical Lookup Scenarios

Product IDs/SKUs: Match your product codes to Gelato’s UIDs.
Shipping Methods: Convert internal names to Gelato's shipment codes.
Carrier Identifiers: Align naming conventions for logistics providers.
Custom Mappings: Handle any value that requires consistent translation.

Key Benefits

Ensures consistent and accurate order intake
Allows fallback values to prevent errors
Supports bulk CSV uploads for large datasets

How to Set Up Lookups

Access the Lookups Section

Log in to your GelatoConnect account.
Navigate to Workflow > Order Intake.
Click Lookups to manage existing mappings or create new ones.

Creating a Lookup Table

Manual Setup

Click Create.
Enter a Name (e.g., "Product SKU Mapping").
Choose the Customer the mapping applies to.
Add an optional Description for context.
Set the Template Field used in templates (e.g., {{sku}}).
Add individual mappings:
- Key: Your internal value.
- Value: Corresponding Gelato value.
Click Save Changes.

Bulk Import (Recommended for Large Data Sets)

Prepare a CSV or Excel file with two columns:
- Lookup key (your internal values)
- Product UID (Gelato values)
Start a new lookup as above.
Click Import and upload your file.
Review the imported data.
Click Save Changes.
Click Save Changes to apply the configuration.

Using Lookups in Template Mappers

To reference lookup tables in your code, use the lookups() function within your template mapper.

Go to Workflow > Order Intake > Templates
Edit the template where you want to use lookups
In the Template Mapper section, use the lookups() function to access your mapping tables
Basic syntax: {{ lookups({"alias": value_to_lookup}, strict=False, default="fallback_value")|js }}

Note: The key "alias" in the lookups() function should match the Template Field you specified when creating the lookup (e.g., shipping_method, sku). This tells the system which lookup table to use.

For example:

{% set productUid = lookups({"sku": item.sku}, strict=False, default=item.sku) %}

In this case, sku is the alias and must match the Template Field in the lookup named {{sku}}.

Example: Product UID Mapping

{% set productUid = lookups({"sku": item.sku}, strict=False, default=item.sku) %}
"productUid": {{ productUid|js }},

Example: Shipping Method Mapping

"shipmentMethodUid": {{ lookups({"shipping_code": order.shipping.method}, strict=False, default="normal")|js }},

Key Parameters

strict=False: Avoids errors if no match is found.
default="value": Sets a fallback value.

When Should You Use Lookups vs. Conditionals?

Use lookups when:

You need to map more than a few values (e.g., many SKUs, shipping methods, carrier codes).
The mappings may change frequently and should be managed outside the template.
You want to delegate mapping logic to non-technical users (who can update the CSV).
You need a centralized table that can be reused across multiple templates.

Use template conditionals when:

You only have 1–2 static values to handle.
The mapping logic is simple and unlikely to change.
Performance and simplicity are more important than reusability.

Example using a conditional:

{% set shippingMethod = "normal" if order.shipping.method == "cheap" else order.shipping.method %}

Example using a lookup:

{% set shippingMethod = lookups({"shipping_method": order.shipping.method}, strict=False, default="normal") %}

Testing Your Lookups

Before going live:

Open your template via Workflow > Order Intake > Templates.
Go to the Template Testing tab.
Enter test values to validate correct translation.
Confirm fallback values are applied for unmatched keys.
Submit a test order to verify full order processing.

Common Use Cases

Product SKU to Gelato UID Mapping

Map your internal product codes to Gelato's product UIDs:

{% set productUid = lookups({"sku": item.sku}, strict=False, default=item.sku) %}
"productUid": {{ productUid|js }},

Shipping Method Translation

Convert your shipping method names to Gelato's shipment method UIDs:

{% set shipMethod = lookups({"shipping_method": order.shipping_type}, strict=False, default="normal") %} "shipmentMethodUid": {{ shipMethod|js }},

Carrier Mapping

Map carrier identifiers between systems:

{% set carrier = lookups({"carrier_code": shipment.carrier}, strict=False, default=shipment.carrier) %} "carrier": {{ carrier|js }},

Country-Specific State Code Mapping

Handle special cases for state codes in specific countries:

{% set stateCode = shipTo.state %}
{% if shipTo.country|upper == "US" %}
    {% set stateCode = lookups({"us_state": shipTo.state}, strict=False, default=shipTo.state) %}
{% endif %}
"state": {{ stateCode|js }},