How Luminous connects to ShipHero, what data flows between systems, and how to configure and support the integration.
Overview
How the connection works
Luminous does not integrate with ShipHero directly. Instead, ShipHero is one of several WMS systems accessible through Trackstar — a middleware layer that normalizes WMS APIs under a single unified interface. From Luminous’s perspective, the integration type is trackstar; ShipHero is the underlying warehouse system.
This matters when troubleshooting: API errors and logs will reference Trackstar endpoints (/wms/products, /wms/orders, etc.) even though the destination is ShipHero.
Data Flows
| Direction | What syncs |
|---|---|
| ← Pull | Inventory quantities — Luminous pulls on-hand or sellable stock counts from ShipHero and writes them into rfq_stock_locations for the channel's picking warehouse. |
| → Push | Sales orders — When a sales order is ready to fulfill, Luminous creates an order in ShipHero with the customer address, line items, shipping method, and optional packing notes. |
| ← Pull | Order shipments — Once ShipHero ships an order, Luminous pulls back tracking numbers, carrier, package weights, and shipment status. |
| → Push | Products / SKUs — Luminous pushes the product catalog (SKU, name, GTIN, dimensions) to ShipHero so it recognizes items before orders or inbound shipments arrive. |
| → Push | Inbound shipments (POs) — Purchase orders are pushed as inbound shipments to ShipHero so the warehouse can receive inventory against expected quantities. |
| ← Pull | Returns — Returns created in ShipHero can be pulled back into Luminous with restocking details, return reasons, and shipment tracking. |
Field Requirements
Different WMS systems often require different fields. ShipHero's requirements differ from Flexport, Extensiv, and others in a few key ways:
| Object | Required fields (ShipHero) | Notable ShipHero-only fields |
|---|---|---|
| Product | sku, name, gtin | warehouse_id or warehouse_ids — seeds the product into specific warehouses |
| Inbound shipment | warehouse_id, purchase_order_number, expected_arrival_date, line items with sku + expected_quantity | warehouse_customer_id (if 3PL); shipping_price and line-item unit_cost are required by ShipHero even though listed as optional in the base schema |
| Sales order | Full ship-to address, line items with sku, quantity, unit_price | warehouse_id per line item; shipping_method_name; wholesale EDI fields (gs1_labels_required, trading_partner_id, etc.) |
| Return | warehouse_id, order_id, line items | label_type, return_reason, carrier_id, measurements — all required for returns |
Key Note: ShipHero requires gtin on product creation but does not require dimensions (measurements.*). If a product push fails for a ShipHero tenant, check that the SKU has a UPC set in Luminous.
Configuration
These settings are stored per integration account in app_integration_account_settings (in Luminous) and control how the sync behaves.
trackstar_inventory_quantity_type
Controls which quantity field Luminous reads from ShipHero. sellable is the most common choice — it reflects what ShipHero considers available to ship, excluding committed and held stock. onhand returns the raw physical count. Most DTC brands should use sellable.
trackstar_get_fulfilled_orders_only
When true, Luminous only pulls back orders in a fully fulfilled status in ShipHero. When false (default), it pulls orders in all statuses and lets Luminous's own status mapping determine how they appear.
get_products
Enables Luminous to pull the product list from ShipHero and match records. Required if you want inventory pull to resolve correctly — Luminous needs to know the ShipHero product IDs for each SKU.
show_inventory_location
When enabled, inventory sync includes bin/location-level data from ShipHero. Useful for multi-location warehouses where you want per-location stock visible in Luminous.
pushInboundShipmentCustomFieldMapping
A JSON array mapping Luminous purchase order fields to ShipHero inbound shipment fields. Without this mapping, inbound shipment pushes may fail or land in the wrong warehouse. Example mapping:
custom_warehouse_id→warehouse_idSupplier→supplier_object.supplier_name
Troubleshooting
Product push fails with a validation error
ShipHero requires gtin (UPC/EAN/ISBN) when creating products. Check that the SKU in Luminous has a UPC set at the integration level.
Inbound shipment push fails or lands in the wrong warehouse
ShipHero requires a warehouse_id on every inbound shipment. This comes from the pushInboundShipmentCustomFieldMapping setting — Luminous reads a custom field from the PO and passes it to ShipHero. If the mapping is wrong or the PO is missing the custom field, the push will fail or use a default warehouse.