What Are Lookups and Why Are They Important?

Lookups in GelatoConnect serve as translation tables that convert data from your system into formats that Gelato can understand. They're essential for seamless API integration, particularly for mapping:

Product IDs/SKUs: Convert your custom product identifiers to Gelato's standardized product UIDs
Shipping Methods: Map your shipping method names to Gelato's carrier codes
Carrier Identifiers: Translate carrier names between systems
Other Custom Mappings: Any value that needs consistent translation between systems

Without lookups, orders might fail when your system's identifiers don't match Gelato's expected values. Lookups provide a reliable way to bridge this gap, ensuring consistent order processing.

Key Benefits of Using Lookups

✅ Standardization: Ensures data consistency between your system and Gelato
✅ Error Prevention: Reduces failures due to mismatched identifiers
✅ Fallback Protection: Provides default values if exact matches aren't found
✅ Scalability: Makes adding new products or shipping methods easier to manage
✅ Maintenance: Centralized management of mappings for easier updates

Setting Up Lookups: Step-by-Step Guide

1. Access the Lookups Page

Log in to your GelatoConnect account
Navigate to Workflow > Order Intake in the left-hand menu
Click on Lookups to view existing mappings or create new ones

2. Create a New Lookup Table

Option A: Manual Creation

Click the Create button at the top of the page
Enter a descriptive Name for your lookup (e.g., "Product SKU Mapping")
Select the Customer this lookup will apply to from the dropdown
Add a Description (optional but recommended) to help identify the lookup's purpose
Enter a Template Field - this is the reference used in template mapper code to access this lookup
Add mappings by clicking the + icon:
- Key: Enter the value from your system (e.g., your product SKU or code)
- Value: Enter the corresponding Gelato value (e.g., Gelato's product UID)
Repeat for all values that need mapping
Click Save Changes to apply the configuration

Option B: Bulk Import (Recommended for Many Values)

Prepare an Excel or CSV file with two columns:
- Column A: Header "lookup key" followed by your system's values
- Column B: Header "product UID" followed by Gelato's corresponding values
Click Create to start a new lookup
Fill in the Name, Customer, Description, and Template Field as above
Click Import instead of manually adding entries
Select your prepared Excel/CSV file
Review the imported mappings
Click Save Changes to complete the setup

3. Implement Lookups in Your Template Mapper

After setting up your lookup tables, you need to reference them in your template mapper code (using Jinja2):

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 }}

Example 1: Product UID Mapping

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

Example 2: Shipping Method Mapping

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

The strict=False parameter ensures the code won't error if a match isn't found, and the default parameter provides a fallback value.

Testing Your Lookups

Always test your lookups before using them in production:

Go to your template in the Templates section
Navigate to the Template Testing tab
Use the test form to verify that your lookups are correctly translating values
Check that missing keys correctly use your default value
Submit a test order and verify the order is processed as expected

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 }},

Troubleshooting Lookups

If your lookups aren't working as expected:

Check for exact matches: Keys are case-sensitive and must match exactly with what's in your API data
Verify template field names: Ensure the template field in your lookup matches what's referenced in your template
Use strict=False: This prevents errors when a lookup key is missing
Always provide defaults: Set appropriate default values to handle missing mappings
Check the full request payload: Use the Requests page to examine the payload that's being processed

Best Practices

Use descriptive naming: Name lookups clearly to indicate their purpose
Add descriptions: Include details about when and where each lookup is used
Keep mappings up to date: Regularly review and update lookups as products or services change
Use bulk import for large datasets: Save time by importing lookups in bulk
Test thoroughly: Always test lookups with both matching and non-matching values
Document your lookups: Maintain records of which lookups are used in which templates