ShipHero Integration

Last updated: June 29, 2026

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_id

  • Supplier → 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.