> ## 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 shipment packages > Create detailed package and item tracking for a sales order shipment. This endpoint allows you to create hierarchical package structures with: - Multiple packages per shipment - Child packages (packages within packages) - Detailed item tracking within each package - Package dimensions, weights, and tracking information - Item-level details including lot numbers, serial numbers, and expiration dates ## Use Cases - Track individual packages within a shipment - Manage nested packaging (e.g., items in boxes, boxes in pallets) - Record detailed inventory information for compliance - Provide granular tracking for complex shipments ## Package Hierarchy Packages can contain: - **Items**: Individual products with quantities and details - **Child Packages**: Nested packages that can themselves contain items or more child packages This allows for complex packaging scenarios like: - Individual items packed in small boxes, then grouped in larger shipping boxes - Palletized shipments with multiple layers of packaging - Mixed shipments with different packaging types ## OpenAPI ````yaml /api-reference/build.yaml post /sales-orders/{salesOrderId}/shipments/{shipmentId}/packages 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: /sales-orders/{salesOrderId}/shipments/{shipmentId}/packages: post: tags: - Sales Orders summary: Create shipment packages description: > Create detailed package and item tracking for a sales order shipment. This endpoint allows you to create hierarchical package structures with: - Multiple packages per shipment - Child packages (packages within packages) - Detailed item tracking within each package - Package dimensions, weights, and tracking information - Item-level details including lot numbers, serial numbers, and expiration dates ## Use Cases - Track individual packages within a shipment - Manage nested packaging (e.g., items in boxes, boxes in pallets) - Record detailed inventory information for compliance - Provide granular tracking for complex shipments ## Package Hierarchy Packages can contain: - **Items**: Individual products with quantities and details - **Child Packages**: Nested packages that can themselves contain items or more child packages This allows for complex packaging scenarios like: - Individual items packed in small boxes, then grouped in larger shipping boxes - Palletized shipments with multiple layers of packaging - Mixed shipments with different packaging types operationId: createSalesOrderShipmentPackages parameters: - in: path name: salesOrderId required: true schema: type: integer description: ID of the sales order - in: path name: shipmentId required: true schema: type: integer description: ID of the shipment to add packages to requestBody: required: true content: application/json: schema: type: object required: - packages properties: packages: type: array minItems: 1 items: type: object properties: sscc: type: string description: >- Serial Shipping Container Code - unique identifier for the package example: 123456789012345680 tracking: type: string description: Tracking number for the package example: PKG-001 package_quantity: type: integer minimum: 1 description: Number of identical packages example: 1 package_type: type: string description: >- Type of package (e.g., box, pallet, envelope, inner_box) example: box packing_type: type: string description: >- Packing method used (e.g., standard, protective, fragile) example: standard length_in: type: number format: float minimum: 0 description: Package length in inches example: 12 width_in: type: number format: float minimum: 0 description: Package width in inches example: 8 height_in: type: number format: float minimum: 0 description: Package height in inches example: 6 weight_lb: type: number format: float minimum: 0 description: Package weight in pounds example: 5 contained_items: type: array items: type: object required: - order_item_id - quantity properties: order_item_id: type: integer description: ID of the sales order line item being packaged example: 1001 line_item_key: type: string description: Unique key for the line item within the package example: line-1 sku: type: string description: Product SKU example: WIDGET-001 internal_sku: type: string description: Internal product SKU example: WIDGET-001 upc: type: string description: Universal Product Code example: '123456789012' quantity: type: integer minimum: 1 description: Quantity of the item being packaged example: 5 description: type: string description: Description of the item example: Premium Widget lot_number: type: string description: Lot number for tracking and traceability example: LOT-2024-001 serial_number: type: string description: Serial number for individual item tracking example: SN-001 expiration_date: type: string format: date description: Expiration date in YYYY-MM-DD format example: '2024-12-31' weight_lb: type: number format: float minimum: 0 description: Total weight of the items in pounds example: 2.5 description: Items contained directly in this package child_packages: type: array items: type: object properties: sscc: type: string description: >- Serial Shipping Container Code - unique identifier for the package tracking: type: string description: Tracking number for the package package_quantity: type: integer minimum: 1 description: Number of identical packages package_type: type: string description: >- Type of package (e.g., box, pallet, envelope, inner_box) packing_type: type: string description: >- Packing method used (e.g., standard, protective, fragile) length_in: type: number format: float minimum: 0 description: Package length in inches width_in: type: number format: float minimum: 0 description: Package width in inches height_in: type: number format: float minimum: 0 description: Package height in inches weight_lb: type: number format: float minimum: 0 description: Package weight in pounds contained_items: type: array items: type: object required: - order_item_id - quantity properties: order_item_id: type: integer description: >- ID of the sales order line item being packaged example: 1001 line_item_key: type: string description: >- Unique key for the line item within the package example: line-1 sku: type: string description: Product SKU example: WIDGET-001 internal_sku: type: string description: Internal product SKU example: WIDGET-001 upc: type: string description: Universal Product Code example: '123456789012' quantity: type: integer minimum: 1 description: Quantity of the item being packaged example: 5 description: type: string description: Description of the item example: Premium Widget lot_number: type: string description: Lot number for tracking and traceability example: LOT-2024-001 serial_number: type: string description: Serial number for individual item tracking example: SN-001 expiration_date: type: string format: date description: Expiration date in YYYY-MM-DD format example: '2024-12-31' weight_lb: type: number format: float minimum: 0 description: Total weight of the items in pounds example: 2.5 description: Items contained directly in this package child_packages: type: array items: type: object description: >- Recursively nested child packages (supports unlimited depth) description: Child packages nested within this package description: >- Child packages nested within this package (supports unlimited nesting) description: Array of packages to create for the shipment bol_number: type: string nullable: true description: >- Bill of Lading Number for logistics tracking; saved on the shipment example: BOL-123456789 pro_number: type: string nullable: true description: >- Progressive Rotating Order Number (common in LTL shipping); saved on the shipment example: PRO-987654321 partner_reference_number: type: string nullable: true description: >- General reference number from/for the shipping partner; saved on the shipment example: PARTNER-REF-001 trailer_number: type: string nullable: true description: >- Trailer number for the shipment (common in LTL/FTL freight); saved on the shipment example: TRL-456789 scac: type: string nullable: true maxLength: 10 description: >- Standard Carrier Alpha Code (SCAC) for the shipment's carrier; saved on the shipment and included on outbound EDI 856/810 documents examples: simple_package: summary: Simple package with items description: A basic package containing multiple items value: packages: - sscc: 123456789012345680 tracking: PKG-001 package_quantity: 1 package_type: box packing_type: standard length_in: 12 width_in: 8 height_in: 6 weight_lb: 5 contained_items: - order_item_id: 1001 line_item_key: line-1 sku: WIDGET-001 internal_sku: WIDGET-001 upc: '123456789012' quantity: 5 description: Premium Widget lot_number: LOT-2024-001 serial_number: SN-001 expiration_date: '2024-12-31' weight_lb: 1 - order_item_id: 1002 line_item_key: line-2 sku: GADGET-002 internal_sku: GADGET-002 quantity: 3 description: Electronic Gadget weight_lb: 0.5 nested_packages: summary: Nested packages with multiple levels description: >- Complex package structure with child packages and items at multiple levels value: packages: - sscc: 123456789012345680 tracking: PALLET-001 package_quantity: 1 package_type: pallet packing_type: standard length_in: 48 width_in: 40 height_in: 60 weight_lb: 150 contained_items: - order_item_id: 1001 line_item_key: pallet-item-1 sku: BULK-ITEM-001 internal_sku: BULK-ITEM-001 quantity: 100 description: Bulk packaged items weight_lb: 50 child_packages: - sscc: 123456789012345680 tracking: BOX-001 package_quantity: 2 package_type: box packing_type: standard length_in: 18 width_in: 12 height_in: 10 weight_lb: 25 contained_items: - order_item_id: 1002 line_item_key: box-item-1 sku: WIDGET-SMALL internal_sku: WIDGET-SMALL upc: '987654321098' quantity: 10 description: Small Widgets lot_number: LOT-2024-002 weight_lb: 2 child_packages: - sscc: 123456789012345680 tracking: INNER-001 package_quantity: 5 package_type: inner_box packing_type: protective length_in: 6 width_in: 4 height_in: 3 weight_lb: 2.5 contained_items: - order_item_id: 1003 line_item_key: inner-item-1 sku: FRAGILE-001 internal_sku: FRAGILE-001 quantity: 2 description: Fragile Electronic Component serial_number: FRAG-001-002 expiration_date: '2026-06-30' weight_lb: 0.1 multiple_packages: summary: Multiple independent packages description: Multiple separate packages in the same shipment value: packages: - sscc: 123456789012345680 tracking: PKG-A001 package_quantity: 1 package_type: box packing_type: standard length_in: 10 width_in: 8 height_in: 6 weight_lb: 3 contained_items: - order_item_id: 1001 sku: ITEM-A quantity: 5 description: Product A - sscc: 123456789012345680 tracking: PKG-B001 package_quantity: 1 package_type: envelope packing_type: standard length_in: 12 width_in: 9 height_in: 1 weight_lb: 0.5 contained_items: - order_item_id: 1002 sku: ITEM-B quantity: 1 description: Product B - Documents responses: '201': description: Packages created successfully content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: integer description: Unique identifier for the package example: 1 sscc: type: string description: >- Serial Shipping Container Code - unique identifier for the package example: 123456789012345680 tracking: type: string description: Tracking number for the package example: PKG-001 package_quantity: type: integer description: Number of identical packages example: 1 package_type: type: string description: >- Type of package (e.g., box, pallet, envelope, inner_box) example: box packing_type: type: string description: >- Packing method used (e.g., standard, protective, fragile) example: standard length_in: type: number format: float description: Package length in inches example: 12 width_in: type: number format: float description: Package width in inches example: 8 height_in: type: number format: float description: Package height in inches example: 6 weight_lb: type: number format: float description: Package weight in pounds example: 5 parent_package_id: type: integer nullable: true description: ID of the parent package if this is a child package example: null shipment_id: type: integer description: ID of the shipment this package belongs to example: 123 created_at: type: string format: date-time description: Timestamp when the package was created example: '2024-01-15T10:30:00Z' updated_at: type: string format: date-time description: Timestamp when the package was last updated example: '2024-01-15T10:30:00Z' items: type: array items: type: object properties: id: type: integer description: Unique identifier for the package item example: 1 package_id: type: integer description: ID of the package containing this item example: 1 order_item_id: type: integer description: ID of the sales order line item being packaged example: 1001 line_item_key: type: string description: >- Unique key for the line item within the package example: line-1 sku: type: string description: Product SKU example: WIDGET-001 internal_sku: type: string description: Internal product SKU example: WIDGET-001 upc: type: string description: Universal Product Code example: '123456789012' quantity: type: integer description: Quantity of the item being packaged example: 5 description: type: string description: Description of the item example: Premium Widget lot_number: type: string nullable: true description: Lot number for tracking and traceability example: LOT-2024-001 serial_number: type: string nullable: true description: Serial number for individual item tracking example: SN-001 expiration_date: type: string format: date nullable: true description: Expiration date in YYYY-MM-DD format example: '2024-12-31' weight_lb: type: number format: float nullable: true description: Total weight of the items in pounds example: 2.5 created_at: type: string format: date-time description: Timestamp when the item was created example: '2024-01-15T10:30:00Z' updated_at: type: string format: date-time description: Timestamp when the item was last updated example: '2024-01-15T10:30:00Z' description: Items contained directly in this package child_packages: type: array items: type: object properties: id: type: integer description: Unique identifier for the package sscc: type: string description: >- Serial Shipping Container Code - unique identifier for the package tracking: type: string description: Tracking number for the package package_quantity: type: integer description: Number of identical packages package_type: type: string description: >- Type of package (e.g., box, pallet, envelope, inner_box) packing_type: type: string description: >- Packing method used (e.g., standard, protective, fragile) length_in: type: number format: float description: Package length in inches width_in: type: number format: float description: Package width in inches height_in: type: number format: float description: Package height in inches weight_lb: type: number format: float description: Package weight in pounds parent_package_id: type: integer description: ID of the parent package shipment_id: type: integer description: ID of the shipment this package belongs to created_at: type: string format: date-time description: Timestamp when the package was created updated_at: type: string format: date-time description: Timestamp when the package was last updated items: type: array items: type: object properties: id: type: integer description: Unique identifier for the package item example: 1 package_id: type: integer description: ID of the package containing this item example: 1 order_item_id: type: integer description: >- ID of the sales order line item being packaged example: 1001 line_item_key: type: string description: >- Unique key for the line item within the package example: line-1 sku: type: string description: Product SKU example: WIDGET-001 internal_sku: type: string description: Internal product SKU example: WIDGET-001 upc: type: string description: Universal Product Code example: '123456789012' quantity: type: integer description: Quantity of the item being packaged example: 5 description: type: string description: Description of the item example: Premium Widget lot_number: type: string nullable: true description: Lot number for tracking and traceability example: LOT-2024-001 serial_number: type: string nullable: true description: >- Serial number for individual item tracking example: SN-001 expiration_date: type: string format: date nullable: true description: Expiration date in YYYY-MM-DD format example: '2024-12-31' weight_lb: type: number format: float nullable: true description: Total weight of the items in pounds example: 2.5 created_at: type: string format: date-time description: Timestamp when the item was created example: '2024-01-15T10:30:00Z' updated_at: type: string format: date-time description: Timestamp when the item was last updated example: '2024-01-15T10:30:00Z' description: Items contained directly in this package child_packages: type: array items: type: object description: Recursively nested child packages description: Child packages nested within this package description: Child packages nested within this package examples: simple_response: summary: Simple package response value: data: - id: 1 sscc: 123456789012345680 tracking: PKG-001 package_quantity: 1 package_type: box packing_type: standard length_in: 12 width_in: 8 height_in: 6 weight_lb: 5 parent_package_id: null shipment_id: 123 created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' items: - id: 1 order_item_id: 1001 line_item_key: line-1 sku: WIDGET-001 internal_sku: WIDGET-001 upc: '123456789012' quantity: 5 description: Premium Widget lot_number: LOT-2024-001 serial_number: SN-001 expiration_date: '2024-12-31' weight_lb: 1 created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' child_packages: [] nested_response: summary: Nested packages response value: data: - id: 1 sscc: 123456789012345680 tracking: PALLET-001 package_quantity: 1 package_type: pallet packing_type: standard length_in: 48 width_in: 40 height_in: 60 weight_lb: 150 parent_package_id: null shipment_id: 123 created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' items: - id: 1 order_item_id: 1001 sku: BULK-ITEM-001 quantity: 100 description: Bulk packaged items weight_lb: 50 child_packages: - id: 2 sscc: 123456789012345680 tracking: BOX-001 package_quantity: 2 package_type: box parent_package_id: 1 items: - id: 2 order_item_id: 1002 sku: WIDGET-SMALL quantity: 10 description: Small Widgets child_packages: - id: 3 sscc: 123456789012345680 tracking: INNER-001 package_type: inner_box parent_package_id: 2 items: - id: 3 order_item_id: 1003 sku: FRAGILE-001 quantity: 2 description: Fragile Electronic Component '400': description: Invalid request content: application/json: schema: type: object properties: message: type: string examples: invalid_shipment: summary: Invalid shipment ID value: message: Shipment not found or does not belong to this sales order '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string '404': description: Sales order or shipment not found 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 examples: validation_errors: summary: Validation error examples value: message: The given data was invalid. errors: packages.0.sscc: - The sscc field must be a string. packages.0.package_quantity: - The package quantity must be at least 1. packages.0.length_in: - The length in must be at least 0. packages.0.contained_items.0.quantity: - The quantity must be at least 1. packages.0.contained_items.0.order_item_id: - The selected order item id is invalid. packages.0.contained_items.0.expiration_date: - The expiration date does not match the format Y-m-d. 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. ````