Field Mappings
Field mappings connect your Lightspeed product data to the fields in your DYMO label template. This determines what information appears on each label when you print.
How Field Mappings Work
When you print a label, LabelLight:
- Reads your label template to find all text and barcode objects
- Looks up your field mappings to see what data should go in each object
- Fetches the corresponding data from Lightspeed's API
- Replaces the template placeholders with actual product data
- Sends the populated label to your printer
📸 Diagram: Field mapping flow from template to printed label
Configuring Field Mappings
-
Set a Default Template
Field mappings are configured for your default label template. Make sure you've uploaded a template and set it as default first.
-
Open Field Mappings Section
In extension settings, scroll to the "Field Mappings" section.
-
Map Each Field
For each object in your template (e.g., "ProductName"), select the corresponding Lightspeed data field from the dropdown.
-
Save Mappings
Click "Save Mappings" to store your configuration.
📸 Screenshot: Field mappings configuration interface
Available API Fields
LabelLight provides access to many Lightspeed product fields. Here are the most commonly used fields:
Core Product Fields
| Field Name | Description | Example |
|---|---|---|
name |
Product name | "Blue T-Shirt" |
variant_name |
Specific variant name | "Medium" |
description |
Product description | "100% cotton t-shirt" |
sku |
Stock Keeping Unit code | "BLU-TSH-M" |
supplier_code |
Supplier's product code | "SUPP-12345" |
Pricing Fields
| Field Name | Description | Example |
|---|---|---|
price_including_tax |
Retail price with tax | "$29.99" |
price_excluding_tax |
Retail price without tax | "$27.27" |
supply_price |
Cost/wholesale price | "$15.00" |
cost |
Product cost | "$14.50" |
loyalty_amount |
Loyalty points value | "30" |
Inventory Fields
| Field Name | Description | Example |
|---|---|---|
quantity |
Quantity (for consignments: ordered quantity) | "10" |
received |
Received quantity (consignments only) | "8" |
Brand & Supplier Fields
| Field Name | Description | Example |
|---|---|---|
brand.name |
Brand name | "Nike" |
supplier.name |
Supplier name | "ABC Distributors" |
type.name |
Product type | "Apparel" |
Variant Option Fields
| Field Name | Description | Example |
|---|---|---|
variant_options[0].name |
First variant option name | "Size" |
variant_options[0].value |
First variant option value | "Medium" |
variant_options[1].name |
Second variant option name | "Color" |
variant_options[1].value |
Second variant option value | "Blue" |
Many extended fields (brand, supplier, variant options) require a configured Lightspeed API Personal Token. See Personal Token for setup instructions.
Additional API Fields
LabelLight also provides access to these additional fields for advanced use cases:
Product Codes
| Field Name | Description |
|---|---|
product_codes[0].code |
Primary product code (e.g., UPC) |
product_codes[0].type |
Primary code type (e.g., "UPC-A") |
Supplier Details
| Field Name | Description |
|---|---|
product_suppliers[0].supplier_name |
Primary supplier name |
product_suppliers[0].code |
Primary supplier's product code |
product_suppliers[0].price |
Primary supplier's price |
Categories
| Field Name | Description |
|---|---|
categories[0].name |
Primary category name |
product_category.name |
Product category name |
Metadata Fields
| Field Name | Description |
|---|---|
id |
Product ID |
created_at |
Product creation date |
updated_at |
Last update date |
Currency Formatting
Price fields are automatically formatted according to your currency settings in LabelLight:
- Currency Symbol - Added before or after the price (e.g., $, €, £)
- Symbol Position - Before ($10.00) or after (10.00€) the price
- Decimal Places - Number of decimal places to display
Configure these options in the General Settings section.
Mapping Tips
- Use consistent names - Name template objects to match the data they'll display (e.g., "ProductName" for the name field)
- Test your mappings - Print a test label to verify all fields display correctly
- Consider empty values - Some products may not have all fields populated (e.g., no brand)
- Map barcodes to SKU - SKU is typically the most reliable field for barcode generation
- Save frequently - Click "Save Mappings" after making changes
Troubleshooting
Field shows blank on label
The mapped Lightspeed field may be empty for that product. Check the product in Lightspeed to verify the data exists.
Field not appearing in dropdown
Ensure you have set a default template. Only fields from the default template appear in the mapping interface.
Price showing wrong format
Check your currency settings in General Settings. The format is applied when labels are generated.
I can only see my product name, without any variant options
Change from the "Product Name" API field to the "Variant Name" API field in your field mappings. The Product Name field only shows the base product name, while the Variant Name field includes the complete name with variant options (e.g., "T-Shirt - Blue - Large" instead of just "T-Shirt").