Luminous has several different mapping tools, each designed for a specific purpose. The table below will help you identify which one you need, then follow the steps for that type.

Quick reference: which mapping do I need?

Your goalMapping typeWhere to find it
Orders are arriving with SKUs Luminous doesn't recognizeSKU / Data Mapping (Purgatory)Operations → Purgatory
Control exactly which Luminous fields are sent to an external system (e.g. TrackStar)Integration MappingsManage → Mappings
Route a requested shipping service (e.g. "2 Day Shipping") to a specific carrier accountShipping Service MappingsManage → Shipping Service Mappings
Define how incoming order-source fields (e.g. Shopify) map into Luminous fieldsSource Data Field MappingSettings / Integrations (per connection)

1. SKU / Data Mapping — resolving unrecognized SKUs

Use this when orders land in Purgatory because Luminous doesn't recognize one or more SKUs.

  1. Go to Operations → Purgatory.
  2. Orders flagged in red contain unrecognized SKUs. For each one, choose one of the following options:
    • Add as an Alternate SKU — link the incoming SKU to an existing product so Luminous treats them as the same item going forward.
    • Create a New Product — use the inline editor on the Purgatory page to build a new product from scratch.
    • Map to an Existing SKU — search for the correct SKU and attach the flagged value as an Alternate SKU.
  3. Use ignore patterns in Purgatory Settings to prevent certain SKU formats from repeatedly re-appearing.
  4. For proactive mapping, open App Integration Account Settings (your name in the top-right → Settings / Integrations), select the relevant connection (e.g. Shopify, Walmart), and use Manage Products → Auto Map SKUs to bulk-connect incoming SKUs to existing Luminous SKUs before they cause issues.

2. Integration Mappings — field-level control when pushing to external systems

Use this when you need to control exactly which fields Luminous sends to a destination system such as TrackStar, and how values are transformed in transit.

  1. Go to Manage → Mappings.
  2. Select an existing mapping or create a new one. Choose the object type you are mapping (e.g. Fulfillment Order).
  3. Open the mapping editor (row ⋮ → Edit, or Create Mapping). The Mapping view lists each destination field and the Luminous data it is filled from; the Advanced view shows a row-by-row table with transformations.
    • Filled from your order = data available in Luminous.
    • Destination field = where the data will land in the destination system.
    • Required fields are clearly marked; unused optional fields can be deleted.
  4. Optionally apply Transformations — convert values (e.g. state abbreviations to full names) or use Auto Map or the Describe a change AI box (Advanced view) to auto-generate complex mappings.
  5. Use the live preview to confirm the output before saving.
  6. Click Save. The mapping can now be reused across any number of channels.
  7. To activate it, go to Channels, edit the relevant channel, and enable Advanced Mapping under Order destination, then select your saved mapping.

Tip: A mapping can be assigned to multiple channels. If a required field is missing, the system will block the push and show an error until it is filled in.

3. Shipping Service Mappings — routing requested services to carriers

Use this when you use direct label printing and want Luminous to automatically translate a requested shipping service name (as it comes in on an order) into a specific carrier account and service code.

This feature is available on accounts with direct label printing enabled.

  1. Go to Manage → Shipping Service Mappings.
  2. Click Add Mapping to create a new mapping.
  3. Enter the Requested Shipping Service — the exact service name as it appears on incoming orders (e.g. 2 Day Shipping). Use the Discover button to load known values from existing orders.
  4. Choose a Mapping Type:
    • Assign specific service — routes to a single carrier account and service code.
    • Rate shop within transit limit — lets Luminous select the best rate that meets a maximum number of transit days (1–30).
  5. Set Priority (0–100; the lowest number is used first) if you have multiple mappings that could match.
  6. Toggle Active on, add optional notes, and click Create.

4. Source Data Field Mapping — mapping incoming source fields to Luminous

Use this when you need to tell Luminous exactly how fields from an incoming data source (such as a custom Shopify webhook or API feed) correspond to Luminous order fields.

  1. Click your name in the top-right corner and go to Settings / Integrations.
  2. Select the connection you want to configure and click Edit.
  3. In the field mapping configuration, define which source field maps to which Luminous field using either:
    • Simple path — for direct, flat fields (e.g. order_number → Luminous orderNumber).
    • JSONPath expression — for nested or array-based data (e.g. extracting a specific property from Shopify line items).
  4. Save the connection settings.

Still not sure which mapping to use?

Contact Luminous Support via the chat widget and describe what you're trying to achieve — the team can point you to the right tool and walk you through configuration.