What Are Shipping Service Mappings?
When a sales order arrives in Luminous (for example, from Shopify), it carries a Requested Shipping Service string — whatever label the customer or channel attached to the order (e.g. "2 Day Shipping", "Express", "Priority Mail"). That string is free-form text and means nothing to a carrier API on its own.
Shipping Service Mappings are rules that translate each Requested Shipping Service value into a concrete carrier account and service code that Luminous can use to purchase a shipping label directly — this is part of the Direct Label Printing feature. Without at least one mapping in place, Luminous cannot automatically resolve which carrier and service to use when you print labels in bulk.
Feature requirement: Shipping Service Mappings are only available when the Direct Label Printing feature is enabled on your account. If you do not see the menu option below, contact your Luminous account manager.
Where to Find Them
Go to Manage → Shipping Service Mappings.
The page lists all your mappings with columns for Requested Service, Type, Details, Active, and Priority. Use the Add Mapping button to create a new one.
Two Mapping Types
When you click Add Mapping, you choose one of two types:
1. Assign Specific Service
Directly pins the order's shipping service name to a specific carrier account and (optionally) a service code.
- Carrier Account (required) — select one of your connected carrier accounts (e.g. your FedEx account).
- Service Code (optional) — the carrier's internal service identifier (e.g.
FEDEX_2_DAY). If left blank, Luminous will use whichever service the carrier defaults to for that account.
Use this type when you always want orders with a specific shipping method to go through exactly one carrier service.
2. Rate Shop Within Transit Limit
Instead of pinning a specific carrier service, you tell Luminous the maximum number of transit days allowed (1–30). Luminous then rate-shops across your carrier accounts and picks the best available service that meets the transit constraint.
- Max Transit Days (required) — enter a number between 1 and 30.
Use this type when the goal is "deliver within N days at the best price" rather than a fixed carrier service.
Scoping a Mapping to a Channel
Mappings can be global (applied to all channels) or channel-specific (applied only to orders from one particular sales channel). Channel-specific mappings always take precedence over global ones when Luminous resolves a mapping for an order.
The Add/Edit Mapping dialog does not currently include a channel selector, so mappings created there apply globally as a fallback for any channel that does not have its own mapping for that service string. Contact Luminous Support if you need a channel-specific mapping.
Using the Discover Button
Not sure what Requested Shipping Service values are actually arriving on your orders? Click the Discover button inside the Add/Edit Mapping dialog. Luminous will query your existing fulfillment orders and return a list of distinct shipping service values it has already seen. Click any value in the list to auto-fill the Requested Shipping Service field — this removes guesswork and ensures the mapping text matches exactly what comes in on orders.
Other Settings
| Setting | What it does |
|---|---|
| Active | Toggle a mapping on or off without deleting it. Inactive mappings are ignored during resolution. |
| Priority | A number from 0 to 100 used to break ties when multiple active mappings match the same service string and channel. Lower numbers are evaluated first — a mapping with priority 0 wins over one with priority 10. |
| Notes | Free-text field for internal documentation (e.g. "Covers all ShipBob express orders"). |
How Resolution Works (Summary)
When Luminous needs to resolve a shipping service for an order:
- It looks for active mappings that match the order's Requested Shipping Service (case-insensitive).
- Among those matches, channel-specific mappings rank above global mappings.
- Within the same tier, the mapping with the lowest Priority number wins.
- The first matched mapping is used; if none match, no carrier service is auto-resolved and you may need to select one manually.
Resolved mappings are cached for one hour. If you create, edit, or delete a mapping, the cache is cleared for that service string immediately.
Step-by-Step: Setting Up a Mapping
- Make sure at least one carrier account is connected under Manage → Carrier Accounts.
- Go to Manage → Shipping Service Mappings and click Add Mapping.
- In the Requested Shipping Service field, type the exact string that arrives on your orders — or click Discover to pick from values already seen in your orders.
- Choose a Mapping Type — Assign Specific Service or Rate Shop Within Transit Limit.
- For Assign Specific Service: select a Carrier Account and (optionally) enter a Service Code.
- For Rate Shop: enter a Max Transit Days value.
- (Optional) If a mapping should only apply to one sales channel, contact Luminous Support — the dialog does not currently offer a channel selector.
- Set Active to Yes and set a Priority (0 is highest precedence).
- Click Create.
Repeat for each shipping method name your orders may carry.
Important Note on External Fulfillment Channels
Shipping Service Mappings control how Luminous selects a carrier and service when printing labels directly inside Luminous (the Direct Label Printing feature). They do not configure how shipping data is translated when Luminous pushes a fulfillment order to an external warehouse management system (e.g. a 3PL). For translating carrier codes and service codes sent to external systems, Luminous uses a separate Integration Field Mappings system. If you need help mapping carrier or service codes for an external fulfillment system integration, contact Luminous Support.