> ## 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 or update product > Create a new product or update an existing one by SKU or ID. **Adding or updating variants** The `variants` array upserts by `sku` (or `id`) — include a child to create or update it, and omit children you don't want to change (they're left untouched, not deleted). To add a new variant to an existing product, PATCH the parent with just the new entry in `variants[]`. To change a variant's option assignment, PATCH the parent with that child's `sku` plus its new `product_variants` axis/terms — the parent's taxonomy will pick up any new terms automatically. See **Working with variants** under `POST /products` for the full parent/child model and a worked example. ## OpenAPI ````yaml /api-reference/build.yaml patch /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: patch: tags: - Products summary: Create or update product description: > Create a new product or update an existing one by SKU or ID. **Adding or updating variants** The `variants` array upserts by `sku` (or `id`) — include a child to create or update it, and omit children you don't want to change (they're left untouched, not deleted). To add a new variant to an existing product, PATCH the parent with just the new entry in `variants[]`. To change a variant's option assignment, PATCH the parent with that child's `sku` plus its new `product_variants` axis/terms — the parent's taxonomy will pick up any new terms automatically. See **Working with variants** under `POST /products` for the full parent/child model and a worked example. operationId: createOrUpdateProduct requestBody: required: true content: application/json: schema: allOf: - type: object 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 qty_low_alert: type: integer nullable: true description: Quantity threshold for low stock alerts qty_reorder_threshold: type: integer nullable: true description: Quantity threshold for reordering qty_minimum: type: integer nullable: true description: Minimum quantity to maintain 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 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 extend 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: - 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 qty_low_alert: type: integer nullable: true description: Quantity threshold for low stock alerts qty_reorder_threshold: type: integer nullable: true description: Quantity threshold for reordering qty_minimum: type: integer nullable: true description: Minimum quantity to maintain supplier_id: type: integer nullable: true description: ID of the variant's 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 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) 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 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. When updating, this will replace all existing BOM associations. items: type: integer description: BOM ID - type: object properties: id: type: integer description: Product ID (required if SKU not provided) sku: type: string description: Product SKU (required if ID not provided) oneOf: - required: - id - required: - sku 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 '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. ````