Overview

The Product Substitutions tab on the SKU edit page lets you define a prioritized list of other SKUs that can serve as stand-ins for a given product. This is a reference configuration feature: Luminous stores the relationships and exposes them for your team and for external integrations, but it does not automatically swap one SKU for another during order processing — acting on a substitution is a deliberate, manual (or integration-driven) step.

Finding the Tab

  1. Go to Inventory → SKUs.
  2. Open any SKU by clicking its name.
  3. In the section menu on the left side of the SKU detail page, select Product Substitutions.

Adding a Substitute

  1. On the Product Substitutions tab, use the Search And Select SKU dropdown to find the SKU you want to designate as a substitute.
  2. Click Add Product Substitute.
  3. The substitute appears in the list with a priority number automatically assigned.

Rules to know:

  • A SKU cannot be a substitute for itself.
  • The same SKU cannot appear in the list more than once.

Understanding Priority

Each substitute has a Priority number (1 = highest preference, 2 = second choice, and so on). The priority determines the recommended substitution order if multiple alternatives exist.

To reorder: Click and drag the ☰ handle on any row up or down. Priorities update automatically when you drop the row into its new position.

Removing a Substitute

Click the Delete button on the row for any substitute you want to remove. The removal takes effect immediately and the remaining items renumber automatically.

Filtering the List

If a SKU has a long list of substitutes, use the Filter Table input (top-left of the tab) to search by SKU code or product name.

Bulk Operations

Bulk SKU import: When importing SKUs via the bulk import template, include a SUBSTITUTIONS column with a comma-separated list of substitute SKU values (for example: SKU1, SKU2, SKU3). Substitutes are applied in the order listed, with the first entry receiving Priority 1.

Bulk edit: The bulk SKU edit form also includes a Product Substitutions section, allowing you to apply or replace the substitution list across multiple SKUs at once.

Substitutions in the External API

When you retrieve a product via the External V1 API (GET /products/{id} or GET /products), the response includes a substitutions array. Each entry contains the substitute's product details (name, SKU, id, retail price) and its priority value — making it straightforward for external systems or integrations to read and act on the configured substitution preferences.

What Happens When a SKU Is Deleted?

Deleting a SKU automatically removes all of its substitution links — both where it was listed as the original product and where it appeared as a substitute for another product. No orphaned substitution records are left behind.