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 Settings → 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 Settings → Channels → [your ShipStation channel].
Expected: Channel detail page opens.
Verify: You see configuration options for ShipStation.Find outgoing mappings
Action: Scroll to Outgoing field mappings.
Expected: You see a list (empty or existing) of mappings.
Verify: Section title shows “Outgoing mappings.”Add a mapping
Action: Click Add mapping.In Template enter a variable (e.g.
{{customerPoNumber}}).In Target field enter a ShipStation payload field (e.g.
advancedOptions.customField2).
Save.
Expected: New row appears.
Verify: Mapping row shows your template and target.
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 |
| Customer PO |
|
| Internal warehouse notes |
|
| Ship-to company name |
|
| Requested service |
|
| Luminous order number |
|
| Fulfillment index (blank if single) |
|
| Customer email |
|
Common ShipStation target fields
You can map to any ShipStation payload field. Common examples include:
Target field | Use case |
| General reference data |
| Short codes, PO numbers, routing IDs |
| URLs or metadata |
| Notes for warehouse staff |
| Requested carrier/service |
| 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" }