> ## Documentation Index > Fetch the complete documentation index at: https://docs.joinluminous.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a product > Create a new product with optional variants, custom fields, and tags. **Kit Products:** When creating a kit product (type = KIT), the `kit_items` field is required and must contain at least one kit item. Each kit item must specify either `product_id` or `sku`, along with a `quantity`. **Working with variants** A product with options like Size or Color is modeled as a parent product plus one child SKU per option combination, nested under the parent's `variants` array. Each child variant is itself a product — it has its own SKU, prices, weights, and dimensions. **You don't need to declare the option taxonomy on the parent.** Just tag each child SKU with the terms it represents (Size = Large, Color = Red, etc.) on `variants[].product_variants`, and Luminous will figure out the parent's taxonomy for you — the union of every term you've used across the children becomes the parent's set of axes and allowed values. New term on a child? It's added to the parent automatically. New axis on a child? Same — the axis is created on the parent. The practical result: you can build a product with any number of variants in a single request, without a separate "define the options first" step, and you can keep adding new variants to it later without ever touching the parent's `product_variants` field. (The parent's `product_variants` field is still writable as an escape hatch — e.g. to seed an empty option set or trim an unused term — but day-to-day you can ignore it.) Each entry in a child's `product_variants` is one option axis: `variant_name` is the axis label ("Size", "Color", …) and `variant_terms` is the term(s) the child is assigned to on that axis (usually a single string, but the field is an array so a child can sit on more than one term of the same axis if that's how you model it). ```json { "name": "Classic Tee", "sku": "TEE-100", "category_id": 1, "variants": [ { "name": "Classic Tee — Small / Red", "sku": "TEE-100-S-RED", "product_variants": [ { "variant_name": "Size", "variant_terms": ["Small"] }, { "variant_name": "Color", "variant_terms": ["Red"] } ] }, { "name": "Classic Tee — Large / Red", "sku": "TEE-100-L-RED", "product_variants": [ { "variant_name": "Size", "variant_terms": ["Large"] }, { "variant_name": "Color", "variant_terms": ["Red"] } ] }, { "name": "Classic Tee — Large / Blue", "sku": "TEE-100-L-BLU", "product_variants": [ { "variant_name": "Size", "variant_terms": ["Large"] }, { "variant_name": "Color", "variant_terms": ["Blue"] } ] } ] } ``` After this call, the parent ends up with taxonomy `Size: [Small, Large]`, `Color: [Red, Blue]` — even though you never wrote it down. The resulting taxonomy and each child's term assignments are returned in the `variant_attributes` field on the response (same shape, on both the parent and each variant). To add a new variant to the same product later, send just that one child in `variants[]` on a `PATCH /products` or `POST /products/{id}` — the parent's taxonomy will pick up any new axis or term it contains automatically. See those endpoints for more on upsert semantics. ## OpenAPI ````yaml /api-reference/build.yaml post /products openapi: 3.0.0 info: title: Luminous API version: 1.0.0 description: API documentation for Luminous servers: - url: https://{companyName}.api.joinluminous.com/external/api/v1 variables: companyName: default: companyName description: Your company-specific subdomain security: [] tags: - name: Products description: Get and manage products - name: Pricing description: Manage price schedules, levels, and customizations - name: BOMs description: Manage Bills of Materials (BOMs) - name: Labels description: Label rendering via Labelary ZPL service - name: Companies description: Manage business accounts and their associated data - name: Contacts description: Manage contact information for individuals - name: Suppliers description: Manage suppliers (factories) — vendors used on purchase orders - name: Supplier SKUs description: Manage per-supplier SKU and unit-cost overrides for products - name: Locations description: Manage warehouses and locations - name: Inventory description: Get and adjust product stock levels - name: Lots description: Create, update, and delete product lots (batches) - name: Transfer Orders description: Manage transfer orders - name: Fulfillment Orders description: Manage fulfillment orders and picklists - name: Purchase Orders description: Get and modify purchase orders - name: Receiving Reports description: Manage receiving reports - name: Payment Obligations description: Manage payment obligations for purchase orders - name: Sales Orders description: Manage sales orders and sales order shipments - name: Purgatory description: >- Inspect and resolve non-posted sales orders in the purgatory staging workflow - name: PickFlow Shipping description: >- Provider-agnostic shipping rates, services, packages, and label purchase for PickFlow - name: Cycle Counts description: >- Create, drive, and post PickFlow cycle counts — batches, per-warehouse sessions, and CSV import/export - name: Print Stations description: List paired print stations and enqueue print jobs to them - name: Invoices description: Get and manage invoices - name: Work Orders description: >- Manage work orders — production lifecycle, steps, materials, links, shipments, and comments - name: Production Batches description: Group and manage work orders as production batches - name: Bills description: >- Accounts payable bill management, payments, attachments, allocations, and variance - name: Prepayments description: Manage vendor prepayments and applications - name: Vendor Credits description: Manage vendor credits and applications - name: Vendor Returns description: Manage vendor returns and credit generation - name: Customer Returns description: Manage customer returns (sales returns), receiving, and restock behavior - name: Stock Snapshot description: Point-in-time stock snapshots with export support - name: Consumption description: Consumption reports and exports - name: Inventory Aging description: Cost-layer-based inventory aging reports - name: Bills Reports description: Accounts payable bills aging reports - name: Forecast description: Materialized forecast data - name: Reports description: Close the books, inventory discrepancy, transaction COGS, and EDI reports - name: Tags description: Add/remove tags across various resources - name: Custom Fields description: Get and set custom fields across various resources - name: Currency description: Currency configuration, exchange rates, and conversion - name: Integration Mappings description: Manage integration mappings for external systems - name: Integration Field Mappings description: Manage field-level mappings between Luminous and external systems paths: /products: post: tags: - Products summary: Create a product description: > Create a new product with optional variants, custom fields, and tags. **Kit Products:** When creating a kit product (type = KIT), the `kit_items` field is required and must contain at least one kit item. Each kit item must specify either `product_id` or `sku`, along with a `quantity`. **Working with variants** A product with options like Size or Color is modeled as a parent product plus one child SKU per option combination, nested under the parent's `variants` array. Each child variant is itself a product — it has its own SKU, prices, weights, and dimensions. **You don't need to declare the option taxonomy on the parent.** Just tag each child SKU with the terms it represents (Size = Large, Color = Red, etc.) on `variants[].product_variants`, and Luminous will figure out the parent's taxonomy for you — the union of every term you've used across the children becomes the parent's set of axes and allowed values. New term on a child? It's added to the parent automatically. New axis on a child? Same — the axis is created on the parent. The practical result: you can build a product with any number of variants in a single request, without a separate "define the options first" step, and you can keep adding new variants to it later without ever touching the parent's `product_variants` field. (The parent's `product_variants` field is still writable as an escape hatch — e.g. to seed an empty option set or trim an unused term — but day-to-day you can ignore it.) Each entry in a child's `product_variants` is one option axis: `variant_name` is the axis label ("Size", "Color", …) and `variant_terms` is the term(s) the child is assigned to on that axis (usually a single string, but the field is an array so a child can sit on more than one term of the same axis if that's how you model it). ```json { "name": "Classic Tee", "sku": "TEE-100", "category_id": 1, "variants": [ { "name": "Classic Tee — Small / Red", "sku": "TEE-100-S-RED", "product_variants": [ { "variant_name": "Size", "variant_terms": ["Small"] }, { "variant_name": "Color", "variant_terms": ["Red"] } ] }, { "name": "Classic Tee — Large / Red", "sku": "TEE-100-L-RED", "product_variants": [ { "variant_name": "Size", "variant_terms": ["Large"] }, { "variant_name": "Color", "variant_terms": ["Red"] } ] }, { "name": "Classic Tee — Large / Blue", "sku": "TEE-100-L-BLU", "product_variants": [ { "variant_name": "Size", "variant_terms": ["Large"] }, { "variant_name": "Color", "variant_terms": ["Blue"] } ] } ] } ``` After this call, the parent ends up with taxonomy `Size: [Small, Large]`, `Color: [Red, Blue]` — even though you never wrote it down. The resulting taxonomy and each child's term assignments are returned in the `variant_attributes` field on the response (same shape, on both the parent and each variant). To add a new variant to the same product later, send just that one child in `variants[]` on a `PATCH /products` or `POST /products/{id}` — the parent's taxonomy will pick up any new axis or term it contains automatically. See those endpoints for more on upsert semantics. operationId: createProduct requestBody: required: true content: application/json: schema: type: object required: - name - category_id - sku properties: name: type: string maxLength: 200 description: Product name category_id: type: integer description: ID of the product category category: type: object nullable: true properties: name: type: string description: >- Name of the product category. If the category is not found in Luminous, it will be created. description: Product category information sku: type: string maxLength: 100 description: Internal SKU supplier_id: type: integer nullable: true description: ID of the preferred supplier supplier: type: object nullable: true properties: name: type: string description: >- Name of the preferred supplier. If the supplier is not found in Luminous, it will be created. description: Product preferred supplier information image_url: type: string maxLength: 255 nullable: true description: URL to product image sellable: type: boolean nullable: true description: Whether the product can be sold lot_tracking: type: boolean nullable: true description: Whether to track product by lots sub_category_id: type: integer nullable: true description: ID of the product subcategory subcategory: type: object nullable: true properties: name: type: string description: >- Name of the product sub-category. If the sub-category is not found in Luminous, it will be created. description: Product sub-category information default_receiving_location_id: type: integer nullable: true description: Default location ID for receiving this product description: type: string nullable: true description: Product description wholesale_price: type: number format: float minimum: 0 nullable: true description: Wholesale price retail_price: type: number format: float minimum: 0 nullable: true description: Retail price unit_cost: type: number format: float minimum: 0 nullable: true description: Cost per unit manufacturing_fee: type: number format: float minimum: 0 nullable: true description: Manufacturing fee per unit product_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) dimensional_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) product_length: type: number format: float minimum: 0 nullable: true description: Length of the product (in inches) product_width: type: number format: float minimum: 0 nullable: true description: Width of the product (in inches) product_height: type: number format: float minimum: 0 nullable: true description: Height of the product (in inches) box_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) box_length: type: number format: float minimum: 0 nullable: true description: Length of the box (in inches) box_width: type: number format: float minimum: 0 nullable: true description: Width of the box (in inches) box_height: type: number format: float minimum: 0 nullable: true description: Height of the box (in inches) carton_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) carton_length: type: number format: float minimum: 0 nullable: true description: Length of the carton (in inches) carton_width: type: number format: float minimum: 0 nullable: true description: Width of the carton (in inches) carton_height: type: number format: float minimum: 0 nullable: true description: Height of the carton (in inches) shipping_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) shipping_length: type: number format: float minimum: 0 nullable: true description: Shipping length (in inches) shipping_width: type: number format: float minimum: 0 nullable: true description: Shipping width (in inches) shipping_height: type: number format: float minimum: 0 nullable: true description: Shipping height (in inches) pallet_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) pallet_length: type: number format: float minimum: 0 nullable: true description: Length of the pallet (in inches) pallet_width: type: number format: float minimum: 0 nullable: true description: Width of the pallet (in inches) pallet_height: type: number format: float minimum: 0 nullable: true description: Height of the pallet (in inches) upc: type: string nullable: true description: UPC/Barcode default_supply_method: type: string nullable: true maxLength: 50 enum: - purchase - vendor_supplied - assemble - on_hand - assembly_order - buy_and_ship - brand_supplied description: > Default supply mode used when planning replenishment for this product. Determines whether the system expects to purchase, drop-ship, assemble, or pull from on-hand stock when supplying demand. priority_list_id: type: integer nullable: true description: >- ID of the fulfillment priority list to assign to this product priority_list: type: object nullable: true description: >- Priority list to assign by ID or name (alternative to priority_list_id) properties: id: type: integer nullable: true description: Priority list ID name: type: string nullable: true maxLength: 255 description: Priority list name custom_fields: type: object nullable: true description: Custom field values additionalProperties: type: string tags: type: array nullable: true description: Tags to associate with the product items: type: string product_variants: type: array nullable: true description: > Variant option taxonomy for the product — the axes (e.g. Size, Color) and the allowed terms on each axis. **You almost never need to set this.** Tag each child SKU under `variants[].product_variants` with the terms it represents instead, and Luminous will derive the parent taxonomy automatically as the union of every term used by the children. Setting this directly is only useful as an escape hatch (e.g. seeding an empty option set, or pruning a term no child uses). Returned on the response as `variant_attributes` (same shape). items: type: object required: - variant_name properties: variant_name: type: string description: Name of the variant axis (e.g. "Size", "Color") variant_terms: type: array nullable: true description: Allowed terms for this variant axis items: type: string variants: type: array nullable: true description: Product variants items: type: object required: - name - sku properties: name: type: string maxLength: 200 description: Variant name sku: type: string maxLength: 100 description: Variant SKU image_url: type: string maxLength: 255 nullable: true description: URL to variant image supplier_id: type: integer nullable: true description: >- ID of the variant's preferred supplier. Supplier must already exist in Luminous. supplier: type: object nullable: true properties: name: type: string description: >- Name of the preferred supplier. If the supplier is not found in Luminous, it will be created. description: Product preferred supplier information sellable: type: boolean nullable: true description: Whether the variant can be sold discontinued: type: boolean nullable: true description: >- If an item is discontinued it will be hidden by default in the Luminous UI default_receiving_location_id: type: integer nullable: true description: Default location ID for receiving this variant description: type: string nullable: true description: Variant description wholesale_price: type: number format: float minimum: 0 nullable: true description: Variant wholesale price retail_price: type: number format: float minimum: 0 nullable: true description: Variant retail price unit_cost: type: number format: float minimum: 0 nullable: true description: Variant cost per unit product_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) dimensional_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) product_length: type: number format: float minimum: 0 nullable: true description: Length of the variant (in inches) product_width: type: number format: float minimum: 0 nullable: true description: Width of the variant (in inches) product_height: type: number format: float minimum: 0 nullable: true description: Height of the variant (in inches) (in inches) box_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) box_length: type: number format: float minimum: 0 nullable: true description: Length of the box (in inches) box_width: type: number format: float minimum: 0 nullable: true description: Width of the box (in inches) box_height: type: number format: float minimum: 0 nullable: true description: Height of the box (in inches) carton_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) carton_length: type: number format: float minimum: 0 nullable: true description: Length of the carton (in inches) carton_width: type: number format: float minimum: 0 nullable: true description: Width of the carton (in inches) carton_height: type: number format: float minimum: 0 nullable: true description: Height of the carton (in inches) shipping_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) shipping_length: type: number format: float minimum: 0 nullable: true description: Shipping length (in inches) shipping_width: type: number format: float minimum: 0 nullable: true description: Shipping width (in inches) shipping_height: type: number format: float minimum: 0 nullable: true description: Shipping height (in inches) pallet_weight: nullable: true oneOf: - type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit (lb for pounds, oz for ounces) value: type: number format: float minimum: 0 description: Weight value - type: array items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz value: type: number format: float minimum: 0 description: >- Array of weight entries (e.g. 4 lbs + 6 oz as [{"unit":"lb","value":4},{"unit":"oz","value":6}]) pallet_length: type: number format: float minimum: 0 nullable: true description: Length of the pallet (in inches) pallet_width: type: number format: float minimum: 0 nullable: true description: Width of the pallet (in inches) pallet_height: type: number format: float minimum: 0 nullable: true description: Height of the pallet (in inches) upc: type: string nullable: true description: Variant UPC/Barcode custom_fields: type: object nullable: true description: Custom field values for the variant additionalProperties: type: string tags: type: array nullable: true description: Tags to associate with the variant items: type: string product_variants: type: array nullable: true description: > The variant option term(s) this child SKU is assigned to (e.g. Size=Large, Color=Red). Use one entry per axis, with the term(s) on `variant_terms`. Any terms used here that aren't yet on the parent's taxonomy are added to it automatically. Returned on the response as the child variant's `variant_attributes` (same shape). items: type: object required: - variant_name properties: variant_name: type: string description: Name of the variant axis (e.g. "Size", "Color") variant_terms: type: array nullable: true description: Term value(s) for this axis on this child SKU items: type: string type: type: string enum: - PRODUCT - KIT nullable: true default: PRODUCT description: >- Product type. PRODUCT for regular products, KIT for kit products that contain other products as components. kit_items: type: array nullable: true description: > Array of kit items (components) for kit products. Required when type = KIT. Each kit item must specify either product_id or sku, and quantity. items: type: object required: - quantity properties: product_id: type: integer nullable: true description: >- ID of the product component. Either product_id or sku must be provided. sku: type: string nullable: true description: >- SKU of the product component. Either product_id or sku must be provided. quantity: type: number format: float minimum: 0 description: Quantity of this component in the kit uom_id: type: integer nullable: true description: >- Unit of measure ID for the quantity. If not provided, defaults to the product's default selling unit. price: type: number format: float minimum: 0 nullable: true description: Price for this kit item original_price: type: number format: float minimum: 0 nullable: true description: Original price for this kit item oneOf: - required: - product_id - required: - sku boms: type: array nullable: true description: > Array of BOM IDs to attach to the product. If null or empty array, all BOMs will be detached. items: type: integer description: BOM ID responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: object properties: id: type: integer description: Unique identifier for the product name: type: string description: Product name description: type: string nullable: true description: Product description retail_price: type: number format: float description: Retail price wholesale_price: type: number format: float description: Wholesale price unit_cost: type: number format: float description: Cost per unit landed_cost: type: number format: float nullable: true description: Landed cost per unit manufacturing_fee: type: number format: float nullable: true description: Manufacturing fee per unit product_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value product_weight_oz: type: number format: float nullable: true description: >- Total product weight in ounces (computed from product_weight) product_weight_lb: type: number format: float nullable: true description: >- Total product weight in pounds (computed from product_weight) dimensional_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value dimensional_weight_oz: type: number format: float nullable: true description: >- Total dimensional weight in ounces (computed from dimensional_weight) dimensional_weight_lb: type: number format: float nullable: true description: >- Total dimensional weight in pounds (computed from dimensional_weight) product_length: type: number format: float description: Length of the product (in inches) product_width: type: number format: float description: Width of the product (in inches) product_height: type: number format: float description: Height of the product (in inches) box_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value box_weight_oz: type: number format: float nullable: true description: Total box weight in ounces (computed from box_weight) box_weight_lb: type: number format: float nullable: true description: Total box weight in pounds (computed from box_weight) box_length: type: number format: float nullable: true description: Length of the box (in inches) box_width: type: number format: float nullable: true description: Width of the box (in inches) box_height: type: number format: float nullable: true description: Height of the box (in inches) carton_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value carton_weight_oz: type: number format: float nullable: true description: >- Total carton weight in ounces (computed from carton_weight) carton_weight_lb: type: number format: float nullable: true description: >- Total carton weight in pounds (computed from carton_weight) carton_length: type: number format: float nullable: true description: Length of the carton (in inches) carton_width: type: number format: float nullable: true description: Width of the carton (in inches) carton_height: type: number format: float nullable: true description: Height of the carton (in inches) shipping_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value shipping_weight_oz: type: number format: float nullable: true description: >- Total shipping weight in ounces (computed from shipping_weight) shipping_weight_lb: type: number format: float nullable: true description: >- Total shipping weight in pounds (computed from shipping_weight) shipping_length: type: number format: float nullable: true description: Shipping length (in inches) shipping_width: type: number format: float nullable: true description: Shipping width (in inches) shipping_height: type: number format: float nullable: true description: Shipping height (in inches) pallet_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value pallet_weight_oz: type: number format: float nullable: true description: >- Total pallet weight in ounces (computed from pallet_weight) pallet_weight_lb: type: number format: float nullable: true description: >- Total pallet weight in pounds (computed from pallet_weight) pallet_length: type: number format: float nullable: true description: Length of the pallet (in inches) pallet_width: type: number format: float nullable: true description: Width of the pallet (in inches) pallet_height: type: number format: float nullable: true description: Height of the pallet (in inches) sellable: type: boolean description: Whether the product can be sold discontinued: type: boolean description: >- Whether the product is discontinued. Discontinued products will be hidden in the Luminous UI by default. lot_tracking: type: boolean description: >- Whether lot (batch) tracking is enabled for this product. When true, on-hand stock is tracked per lot and lot-aware endpoints (e.g. `/lots`, the `lot_stocks` breakdown on inventory stock, and lot fields on adjustments/receiving) apply. default_supply_method: type: string nullable: true enum: - purchase - vendor_supplied - assemble - on_hand - assembly_order - buy_and_ship - brand_supplied description: >- Default supply mode used when planning replenishment for this product image_url: type: string nullable: true description: URL to the product's main image category: type: object nullable: true properties: id: type: integer name: type: string description: Product category information subcategory: type: object nullable: true properties: id: type: integer name: type: string description: Product subcategory information custom_fields: type: object description: Dynamic custom fields with key-value pairs additionalProperties: type: string attachments: type: array description: Product attachments items: type: object properties: id: type: integer description: Unique identifier for the attachment name: type: string description: Filename of the attachment type: type: string description: MIME type of the attachment size: type: integer description: File size in bytes full_url: type: string description: Full resolution URL of the attachment thumb_url: type: string description: Thumbnail URL of the attachment (if applicable) required: - id - name - type - size - full_url variants: type: array description: Product variants items: type: object properties: id: type: integer name: type: string description: type: string nullable: true product_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value product_weight_oz: type: number format: float nullable: true product_weight_lb: type: number format: float nullable: true dimensional_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value dimensional_weight_oz: type: number format: float nullable: true dimensional_weight_lb: type: number format: float nullable: true box_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value box_weight_oz: type: number format: float nullable: true box_weight_lb: type: number format: float nullable: true carton_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value carton_weight_oz: type: number format: float nullable: true carton_weight_lb: type: number format: float nullable: true shipping_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value shipping_weight_oz: type: number format: float nullable: true shipping_weight_lb: type: number format: float nullable: true pallet_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value pallet_weight_oz: type: number format: float nullable: true pallet_weight_lb: type: number format: float nullable: true attachments: type: array description: Variant-specific attachments items: type: object properties: id: type: integer description: Unique identifier for the attachment name: type: string description: Filename of the attachment type: type: string description: MIME type of the attachment size: type: integer description: File size in bytes full_url: type: string description: Full resolution URL of the attachment thumb_url: type: string description: >- Thumbnail URL of the attachment (if applicable) required: - id - name - type - size - full_url retail_price: type: number format: float wholesale_price: type: number format: float custom_fields: type: array items: type: object variant_attributes: type: array nullable: true description: > The variant option terms this child SKU is assigned to (e.g. Size=Large, Color=Red). Returned in the same `[{variant_name, variant_terms[]}]` shape as the parent product's `variant_attributes` taxonomy, with each entry holding the term(s) selected for this child on that axis. items: type: object properties: variant_name: type: string description: Name of the variant axis (e.g. "Size") variant_terms: type: array description: >- Term value(s) selected for this child on that axis items: type: string sku: type: string upc: type: string created_at: type: string format: date-time updated_at: type: string format: date-time variant_attributes: type: array nullable: true description: > Variant option taxonomy for this product — the axes (e.g. Size, Color) and the allowed terms on each axis. On a parent product, this is the union of all terms used by its child variants. On a child variant, this holds the specific term(s) the child is assigned to. Set via the request field `product_variants` (same shape) on create/update. items: type: object properties: variant_name: type: string description: Name of the variant axis (e.g. "Size", "Color") variant_terms: type: array description: Terms on this axis items: type: string sku: type: string description: Internal SKU alternate_skus: type: array description: Alternate SKUs items: type: object properties: id: type: integer sku: type: string upc: type: string description: UPC/Barcode tags: type: array description: Tags associated with the product items: type: object properties: id: type: integer description: Unique identifier for the tag name: type: string description: Name of the tag description: type: string nullable: true description: Description of the tag icon: type: string nullable: true description: Icon identifier or URL for the tag color: type: string nullable: true description: Color code for the tag required: - id - name substitutions: type: array description: >- Product substitutions, these products may be substituted if the main product is out of stock items: type: object properties: id: type: integer description: Substitution record ID priority: type: integer description: >- Substitution priority (lower number = higher priority) product: type: object description: The substitute product properties: id: type: integer description: Unique identifier for the product name: type: string description: Product name description: type: string nullable: true description: Product description retail_price: type: number format: float description: Retail price wholesale_price: type: number format: float description: Wholesale price unit_cost: type: number format: float description: Cost per unit product_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value product_weight_oz: type: number format: float nullable: true product_weight_lb: type: number format: float nullable: true dimensional_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value dimensional_weight_oz: type: number format: float nullable: true dimensional_weight_lb: type: number format: float nullable: true product_length: type: number format: float description: Length of the product (in inches) product_width: type: number format: float description: Width of the product (in inches) product_height: type: number format: float description: Height of the product (in inches) box_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value box_weight_oz: type: number format: float nullable: true box_weight_lb: type: number format: float nullable: true box_length: type: number format: float nullable: true description: Length of the box (in inches) box_width: type: number format: float nullable: true description: Width of the box (in inches) box_height: type: number format: float nullable: true description: Height of the box (in inches) carton_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value carton_weight_oz: type: number format: float nullable: true carton_weight_lb: type: number format: float nullable: true carton_length: type: number format: float nullable: true description: Length of the carton (in inches) carton_width: type: number format: float nullable: true description: Width of the carton (in inches) carton_height: type: number format: float nullable: true description: Height of the carton (in inches) shipping_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value shipping_weight_oz: type: number format: float nullable: true shipping_weight_lb: type: number format: float nullable: true shipping_length: type: number format: float nullable: true description: Shipping length (in inches) shipping_width: type: number format: float nullable: true description: Shipping width (in inches) shipping_height: type: number format: float nullable: true description: Shipping height (in inches) pallet_weight: type: array nullable: true items: type: object required: - unit - value properties: unit: type: string enum: - lb - oz description: Weight unit value: type: number format: float minimum: 0 description: Weight value pallet_weight_oz: type: number format: float nullable: true pallet_weight_lb: type: number format: float nullable: true pallet_length: type: number format: float nullable: true description: Length of the pallet (in inches) pallet_width: type: number format: float nullable: true description: Width of the pallet (in inches) pallet_height: type: number format: float nullable: true description: Height of the pallet (in inches) sellable: type: boolean description: Whether the product can be sold discontinued: type: boolean description: Whether the product is discontinued image_url: type: string nullable: true description: URL to the product's main image sku: type: string description: Internal SKU upc: type: string description: UPC/Barcode created_at: type: string format: date-time description: Timestamp when the product was created updated_at: type: string format: date-time description: Timestamp when the product was last updated supplier: type: object nullable: true description: Supplier information type: type: string enum: - PRODUCT - KIT description: >- Product type. PRODUCT for regular products, KIT for kit products that contain other products as components. kit_items: type: array nullable: true description: >- Kit items (components) for kit products. Only present when type = KIT. items: type: object properties: id: type: integer description: Unique identifier for the kit item product_id: type: integer description: ID of the product component quantity: type: number format: float description: Quantity of this component in the kit uom_id: type: integer description: Unit of measure ID for the quantity base_uom_quantity: type: number format: float description: Quantity converted to base unit of measure price: type: number format: float description: Price for this kit item original_price: type: number format: float description: Original price for this kit item total: type: number format: float description: Calculated total (quantity * price) product: type: object nullable: true description: >- Product information for this kit item (when loaded) properties: id: type: integer name: type: string sku: type: string description: type: string nullable: true retail_price: type: number format: float wholesale_price: type: number format: float unit_of_measure: type: object nullable: true description: Unit of measure information (when loaded) properties: id: type: integer name: type: string description: type: string nullable: true base_unit: type: boolean priority_list: type: object nullable: true description: Fulfillment priority list assigned to this product properties: id: type: integer description: Priority list ID name: type: string description: Priority list name description: type: string nullable: true description: Priority list description boms: type: array description: BOMs (Bills of Materials) associated with this product items: type: object properties: id: type: integer description: Unique identifier for the BOM name: type: string description: BOM name items: type: array description: BOM items (components/products) items: type: object properties: id: type: integer description: Unique identifier for the BOM item bom_id: type: integer description: ID of the BOM this item belongs to product_id: type: integer description: ID of the product/component product: type: object nullable: true description: Product information (when loaded) properties: id: type: integer name: type: string sku: type: string description: type: string nullable: true quantity: type: number format: float description: Quantity required for this item base_quantity: type: number format: float description: >- Base quantity (converted to base unit of measure) note: type: string nullable: true description: Optional note for this item uom_id: type: integer nullable: true description: Unit of measure ID unit_of_measure: type: object nullable: true description: Unit of measure information (when loaded) properties: id: type: integer name: type: string order: type: integer nullable: true description: Display order for this item consumption_basis: type: string enum: - planned - actual description: >- Determines how much of this component an assembly/work order consumes. `planned` consumes the BOM-defined quantity; `actual` consumes the quantity actually reported during production. Defaults to `planned`. created_at: type: string format: date-time description: Timestamp when the item was created updated_at: type: string format: date-time description: Timestamp when the item was last updated required: - id - bom_id - product_id - quantity extra_costs: type: array description: Additional costs associated with the BOM items: type: object properties: id: type: integer description: Unique identifier for the extra cost name: type: string description: Name/description of the extra cost quantity: type: number format: float description: Quantity for this cost item unit_price: type: number format: float description: Unit price for this cost item line_total: type: number format: float description: >- Total cost (quantity × unit_price), calculated automatically on the backend. This field is read-only and should not be provided when creating or updating extra costs. created_at: type: string format: date-time description: Timestamp when the extra cost was created updated_at: type: string format: date-time description: >- Timestamp when the extra cost was last updated required: - id - name - quantity - unit_price - line_total created_at: type: string format: date-time description: Timestamp when the BOM was created updated_at: type: string format: date-time description: Timestamp when the BOM was last updated required: - id - name created_at: type: string format: date-time description: Timestamp when the product was created updated_at: type: string format: date-time description: Timestamp when the product was last updated '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string '409': description: Conflict - SKU already exists content: application/json: schema: type: object properties: message: type: string '422': description: Validation error content: application/json: schema: type: object properties: message: type: string errors: type: object additionalProperties: type: array items: type: string security: - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer description: >- Authenticate using a bearer token. To create a token, navigate to /settings/api-tokens and click Create API Token. ````