Overview
When pushing shipment tracking information back to a sales channel, Luminous may encounter a carrier name that the channel doesn't recognize. The Carrier Mapping Required prompt allows you to translate your internal Luminous carrier name into an accepted value so the push can complete successfully.
How It Works (Step-by-Step)
- Trigger the push — Attempt to push tracking information from a fulfillment order back to your sales channel (e.g., Shopify, WooCommerce).
- Carrier Mapping Required dialog appears — This modal surfaces automatically when Luminous detects that the carrier name (e.g., "LaserShip") is not recognized by the destination channel.
- Review the mapping — The dialog shows two fields:
- Luminous Value (Current) — the carrier name as stored in Luminous (highlighted in yellow)
- External Value (Maps To) — the value the sales channel will accept (editable field)
- Select or confirm the external value — Luminous displays a list of accepted values from the channel. Click the correct one to populate the field. An AI Suggestion with a confidence score may appear to help you choose.
- Choose your action:
- Create Mapping Only — saves the mapping for future use but does not retry the push immediately
- Create Mapping & Retry Push — saves the mapping and immediately re-attempts the tracking push
- Cancel — dismisses the dialog without saving anything
Key Features / Options
AI Suggestion — Luminous analyzes the carrier name and suggests the closest accepted value with a confidence percentage. A "High confidence (100%)" tag means the match is very reliable; lower confidence scores warrant a manual review.
Auto Mode — Clicking "Enable Auto Mode" tells Luminous to automatically create carrier mappings and retry pushes in the future without prompting you. Best suited for accounts with stable, predictable carrier usage.
View all field mappings — The link at the bottom of the dialog takes you to the full field mappings list for the account, where you can review, edit, or delete existing mappings.
Tips & Best Practices
- Use "Create Mapping & Retry Push" in most cases — it resolves the current failure and saves you from repeating the step manually.
- Enable Auto Mode cautiously — it's convenient for high-volume accounts, but if a carrier name changes or is entered inconsistently, auto-mapping could silently create incorrect mappings.
- Always verify the AI suggestion before accepting it, especially if the confidence score is below 100%. A close-but-wrong match (e.g., "LaserShip" → "LSO") will cause the push to fail or send incorrect tracking data to the customer.
- Check your carrier names for consistency upstream — typos or variations in how carriers are entered in Luminous (e.g., "Laser Ship" vs. "LaserShip") will generate repeat mapping prompts.
FAQs & Troubleshooting
Why does this keep appearing for the same carrier? A mapping may not have been saved the last time, or a new variation of the carrier name was introduced. Check your existing field mappings to confirm the correct mapping is in place.
The accepted values list doesn't include my carrier — what do I do? The list is sourced directly from the sales channel. If your carrier isn't listed, the channel itself may not support it. Contact your channel administrator or reach out to Luminous support.
I enabled Auto Mode but the push still failed. Auto Mode applies to future pushes. It does not retroactively resolve a push that already failed. Complete the current mapping manually, then Auto Mode will handle it going forward.
The AI suggested the wrong carrier. Can I override it? Yes — simply click a different value from the accepted values list or type directly into the External Value field. The AI suggestion is a starting point, not a locked selection.
Where do I find and manage all my carrier mappings? Navigate to the "View all field mappings for this account →" link inside the dialog, or go directly through your account's integration settings. To access this go to Settings - Integration Field Mappings.
Additional Help
If the Carrier Mapping Required dialog continues to appear after a mapping is saved, or if your carrier is not available in the accepted values list, contact Luminous Support for assistance.