Map Luminous order data to ShipStation using simple templates. Step-by-step setup, common examples, and a sample ShipStation payload.
Purpose & when to use
Use outgoing field mappings to pass custom order data from Luminous to ShipStation—e.g., Customer PO, internal notes, or ship-to company. This lets you control exactly how order details appear in ShipStation for warehouse processing or label printing.
Why it matters: Field mappings reduce manual edits in ShipStation and ensure downstream teams see the right context.
Before you start
- Verify your ShipStation channel is connected in Manage → Channels. This may be a fulfillment channel or an end-to-end channel configured to push to ShipStation.
- Prepare a test order with realistic values (PO, internal notes, ship-to).
- Decide which ShipStation field(s) you want to populate. You can map into any valid field in the ShipStation API payload.
Caution: Some fields (e.g., certain advanced options) may appear on labels or packing slips. Avoid sending sensitive or verbose data unless that’s intentional.
How mappings work
- Templates use double braces:
#{{variable}} - Fallbacks use pipes:
#{{primary|fallback|"default text"}}(first non-empty wins) - Each mapping links a Luminous variable (left side) to a ShipStation field path (right side)
Example:
#{{customerPoNumber}} ⇒ advancedOptions.customField2
Steps
- Open the correct channel
Action: Go to Manage → Channels → [your ShipStation channel] and click Edit.
Expected: Channel edit page opens.
Verify: You see configuration options for ShipStation. - Find outgoing mappings
Action: In Order Destination, with Mapping Type set to Basic Mapping, scroll to Outgoing Custom Field Mapping.
Expected: You see a list (empty or existing) of mappings.
Verify: Section title shows “Outgoing Custom Field Mapping.” - Add a mapping
Action: Click + Add Custom Field Mapping.- In LUM Field choose Custom Template and enter a variable (e.g.
#{{customerPoNumber}}). - In Push Field enter a ShipStation payload field (e.g.
advancedOptions.customField2).
Save.
Expected: New row appears.
Verify: Mapping row shows your template and target.
- In LUM Field choose Custom Template and enter a variable (e.g.
- Test with an order
Action: Push a test order to ShipStation.
Expected: Order appears with mapped values in the correct fields.
Verify: Open order in ShipStation → check target field(s) you mapped. - Confirm fallbacks
Action: If you used fallbacks, test both scenarios.
Expected: The first non-empty value is passed.
Verify: Compare two test orders (PO present vs. empty).
Common variables
| Variable | Meaning | Example |
#{{customerPoNumber}} | Customer PO | PO-2024-001 |
#{{internalNotes}} | Internal warehouse notes | Rush order |
#{{shipToCompany}} | Ship-to company name | JanYo Frozen Yogurt, Inc |
#{{requestedShippingService}} | Requested service | FedEx Ground |
#{{orderNumber}} | Luminous order number | ORD-12345 |
#{{foIndex()}} | Fulfillment index (blank if single) | -1, -2 |
#{{customerEmail}} | Customer email | john.doe@example.com |
Common ShipStation target fields
You can map to any ShipStation payload field. Common examples include:
| Target field | Use case |
advancedOptions.customField1 | General reference data |
advancedOptions.customField2 | Short codes, PO numbers, routing IDs |
advancedOptions.customField3 | URLs or metadata |
internalNotes | Notes for warehouse staff |
requestedShippingService | Requested carrier/service |
orderNumber | Override the ShipStation order number |
Example mappings
1) PO number into a custom field
#{{customerPoNumber}} ⇒ advancedOptions.customField2
Result: PO appears in ShipStation “Custom Field 2”.
2) Fallback: PO or order number
#{{customerPoNumber|orderNumber}} ⇒ advancedOptions.customField1
Result: Uses PO if available; falls back to order number.
3) Enrich internal notes
Customer: #{{customerEmail}} | Notes: #{{internalNotes}} ⇒ internalNotes
Result: Shows both customer email and warehouse notes.
4) Split orders with unique IDs
#{{orderNumber}}#{{foIndex()}} ⇒ orderNumber
Result: Split fulfillments show as ORD-12345-1, ORD-12345-2.
Troubleshooting
- Variable not resolving → Check spelling (case-sensitive); test with fallbacks.
- Data missing in ShipStation → Ensure mapping is saved; re-push order; confirm target field name.
- Formatting issues → Keep mapped text under ~100 chars for label fields; avoid HTML or special characters.
Example payload
Here’s a full ShipStation payload with mapped fields for reference:
{ "orderNumber": "ORD-12345-1", "orderKey": "ORD-12345-1", "orderDate": "2024-01-15T10:00:00Z", "orderStatus": "awaiting_shipment", "customerEmail": "john.doe@example.com", "customerNotes": "Please handle with care", "internalNotes": "Customer: john.doe@example.com | Notes: Rush order", "giftMessage": "Happy Birthday!", "paymentMethod": "credit_card", "requestedShippingService": "FedEx Ground", "shipByDate": "2024-01-16", "advancedOptions": { "customField1": "Order ORD-12345 for JanYo Frozen Yogurt, Inc - PO: PO-2024-001", "customField2": "PO-2024-001", "customField3": "https://example.com/orders/ORD-12345", "source": "Luminous", "warehouseId": 123456, "storeId": 78910 }, "billTo": { "name": "John Doe", "company": "Test Company", "street1": "123 Billing St", "city": "Billing City", "state": "CA", "postalCode": "90210", "country": "US", "phone": "555-0123" }, "shipTo": { "name": "Jane Smith", "company": "JanYo Frozen Yogurt, Inc", "street1": "1520 Buttehouse Rd #500", "city": "Yuba City", "state": "CA", "postalCode": "95993", "country": "US", "phone": "555-0456", "email": "katelynvaughn00@gmail.com" }, "items": [ { "sku": "SKU-001", "name": "Frozen Yogurt Mix - Vanilla", "quantity": 3, "unitPrice": 59.99 }, { "sku": "SKU-002", "name": "Topping Pack - Assorted", "quantity": 2, "unitPrice": 9.50 } ], "amountPaid": 199.99, "taxAmount": 10.00, "shippingAmount": 10.00, "subtotal": 179.99, "totalAmount": 199.99, "carrierCode": "fedex", "serviceCode": "fedex_ground", "shipDate": "2024-01-16" }