Overview

When this feature is enabled for your account, Luminous reads every shipped ShipStation record, identifies which box type was used, and deducts the configured packaging materials (box, inserts, etc.) from on-hand inventory and cost layers automatically. The workflow has three parts: configuring tenant settings, building a box-mapping library, and (optionally) adding a ShipStation API V2 key for richer package matching.

Prerequisites

  • The packaging consumption feature flag must be enabled by your Luminous account team.
  • Your ShipStation connection must be a Direct API account (not a Custom Store).
  • The packaging materials you want to deduct must already exist as SKUs in Luminous inventory.
  • Each SKU must be set up as a bill-of-materials line on your box mappings (see below).

Step 1 — Enable the tenant settings

  1. Go to Settings → System Settings (or the Inventory settings area where your account team directs you).
  2. Turn on Packaging Consumption (the toggle or checkbox labelled accordingly).
  3. Set a Packaging Consumption Since date (format YYYY-MM-DD). Luminous will only process shipments created on or after this date.
  4. Save. All three conditions — feature flag active, setting enabled, and a valid since-date — must be met before any deductions occur.

Step 2 — Build your box-mapping library

Box mappings live under Settings → Inventory → Packaging Box Mappings.

Each mapping links a specific package type to the Luminous SKUs that should be deducted when that package is used.

Adding a mapping

  1. Click New Mapping.
  2. Select the ShipStation integration account this mapping applies to.
  3. Identify the box type using one or more of the following (Luminous checks them in priority order):
    • Package code — the ShipStation package code string (e.g. my_branded_box_medium). Preferred when available.
    • Package type ID — the ShipStation V2 package UUID (populated automatically if you supply a V2 API key; see Step 3).
    • Dimension signature — length × width × height in inches. Luminous normalizes orientation so 12×10×8 and 10×12×8 match the same mapping.
  4. Add BOM lines — one row per material to deduct. For each line choose the SKU and the quantity consumed per shipment.
  5. Set the mapping to Active and save.

Tip: If two of your box sizes have identical dimensions but different packaging contents (e.g., a plain box vs. a branded box), supply a ShipStation V2 API key so Luminous can distinguish them by package ID or code rather than dimensions.

Step 3 (optional) — Add a ShipStation API V2 key

ShipStation's V2 API (available on Standard and Premium plans) exposes a custom package catalog and provides package_id / package_code on individual shipment records. When Luminous has this key it can:

  • List your custom packages in the box-mapping UI for easy selection.
  • Match shipments by package identity instead of dimensions alone.

Where to add it

  1. Go to Settings → App Integration Accounts and open your ShipStation account.
  2. Expand the Advanced section.
  3. Paste your ShipStation API V2 key (this is a separate key from your V1 API Key / Secret — obtain it from ShipStation under Account Settings → API).
  4. Click Save & Test. Luminous will verify both the V1 credentials and the V2 key. A 402 Payment Required error from ShipStation means the account plan does not include V2 API access.

Note: Adding the V2 key does not change how orders, labels, or tracking sync — those continue to use the V1 API exactly as before.

How deductions work

  • A scheduled background job processes shipped ShipStation shipments in batches.
  • For each shipment, Luminous looks for a matching active box mapping (by code → type ID → dimensions).
  • When a match is found, all BOM lines are deducted from on-hand inventory and FIFO cost layers in a single transaction.
  • Deductions are idempotent — the same shipment will never be deducted twice.
  • If a shipment is later voided in ShipStation, Luminous reverses the deduction automatically.

The attention queue

If a shipment cannot be matched — because no active mapping covers its box type — it lands in an attention state rather than being silently skipped. Common reasons:

ReasonWhat to do
No mapping matches the box dimensions / codeCreate a new box mapping for that package type
Mapping has an empty BOMAdd SKU lines to the existing mapping
No stock record found for a BOM SKUEnsure the SKU exists and has a stock record in the correct warehouse group

Attention rows are re-evaluated automatically the next time the sync runs. Once you add or fix the mapping, previously unmatched shipments resolve without any manual trigger.

Troubleshooting

  • No deductions happening at all: Confirm the feature flag is on, the setting is enabled, and a valid since-date is set (all three are required).
  • V2 key rejected: Check that the key is the V2 key (not the V1 secret) and that your ShipStation plan includes API V2 access.
  • Same-size boxes deducting the wrong BOM: Add a ShipStation V2 key and ensure your custom package codes are distinct. Luminous prefers code-based matching over dimension matching.