> ## 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 purchase order shipment > Create one supplier purchase order shipment, using the same writer as the in-app form. The body uses the same snake_case field names as the shipment response. - `shipment_items` is required and must contain at least one line. Each line's `supplier_purchase_order_item_id` must belong to its `supplier_purchase_order_id`, otherwise `422`. - `unit_of_measure_id` is optional per line; when omitted it is taken from the purchase order line's ordered unit (`422` if that line has no ordered unit). - `reference_number` is optional and generated when omitted. A reference already used by another shipment returns `409`. - `shipped_by` and `shipment_type` accept any casing and are stored in their canonical form (e.g. `sea` → `Sea`). - A draft or cancelled purchase order on any line returns `422` and nothing is written. - `custom_fields` is an optional label => value map resolved the same way as `PUT /purchase-order-shipments/{id}/custom-fields`: an unknown label, or one defined only for another record type, is `422` and is never auto-created. When `custom_fields` is sent, every custom field marked required for purchase order shipments must be included. Omit it to create the shipment without setting any custom fields. - `total_shipping_cost` on the created shipment is the sum of the extra-cost line totals (`quantity × unit_price`). A successful create returns `201` with the shipment in `data` (same shape as `GET /purchase-order-shipments/{id}`). A request with more than 200 lines is queued instead and returns `202` with a `job_status_id`; the shipment is written by the background job. ## OpenAPI ````yaml /api-reference/build.yaml post /purchase-order-shipments 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: Freight description: >- Freightview LTL freight — quotes, booking and documents for fulfillment orders - name: Fulfillment Priority Lists description: Configure fulfillment routing priority lists - name: Purchase Orders description: Get and modify purchase orders - name: Supplier Portal description: >- Read a supplier's response to a purchase order and control the one-click portal link - 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 Warehouse description: >- Warehouse-floor lookups for PickFlow — barcode resolution, bin and product stock, bin search, and receivables - 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: Drive description: > Browse, upload, tag and manage files in your Luminous Drive. An API token sees the shared drive only, never My Files or restricted folders and files. Every write and download made through the API is recorded in the file's activity log (`GET /file-cabinet/files/{id}/activity`) with `actor_kind: api_token`. - name: Integration Mappings description: Manage integration mappings for external systems - name: Integration Field Mappings description: Manage field-level mappings between Luminous and external systems - name: Automations description: Create, test, and inspect automation rules and their runs paths: /purchase-order-shipments: post: tags: - Purchase Order Shipments summary: Create purchase order shipment description: > Create one supplier purchase order shipment, using the same writer as the in-app form. The body uses the same snake_case field names as the shipment response. - `shipment_items` is required and must contain at least one line. Each line's `supplier_purchase_order_item_id` must belong to its `supplier_purchase_order_id`, otherwise `422`. - `unit_of_measure_id` is optional per line; when omitted it is taken from the purchase order line's ordered unit (`422` if that line has no ordered unit). - `reference_number` is optional and generated when omitted. A reference already used by another shipment returns `409`. - `shipped_by` and `shipment_type` accept any casing and are stored in their canonical form (e.g. `sea` → `Sea`). - A draft or cancelled purchase order on any line returns `422` and nothing is written. - `custom_fields` is an optional label => value map resolved the same way as `PUT /purchase-order-shipments/{id}/custom-fields`: an unknown label, or one defined only for another record type, is `422` and is never auto-created. When `custom_fields` is sent, every custom field marked required for purchase order shipments must be included. Omit it to create the shipment without setting any custom fields. - `total_shipping_cost` on the created shipment is the sum of the extra-cost line totals (`quantity × unit_price`). A successful create returns `201` with the shipment in `data` (same shape as `GET /purchase-order-shipments/{id}`). A request with more than 200 lines is queued instead and returns `202` with a `job_status_id`; the shipment is written by the background job. operationId: createPurchaseOrderShipment requestBody: required: true content: application/json: schema: type: object required: - shipment_items properties: reference_number: type: string nullable: true maxLength: 255 description: >- Supplier reference number. Generated when omitted; `409` when already in use. warehouse_id: type: integer nullable: true description: Destination warehouse (location) ID shipment_status_id: type: integer nullable: true description: Shipment status ID shipping_date: type: string format: date nullable: true notes: type: string nullable: true tracking_number: type: string nullable: true maxLength: 255 shipped_by: type: string nullable: true enum: - Freight - Supplier description: Who is responsible for shipping (case-insensitive) shipment_type: type: string nullable: true enum: - Air - Sea - Road - Rail - Express description: Mode of transport (case-insensitive) estimated_arrival: type: string format: date nullable: true is_closed: type: boolean nullable: true default: false volume_target_cbm: type: number format: float nullable: true minimum: 0 description: Container volume target in cubic meters shipment_items: type: array minItems: 1 items: type: object required: - supplier_purchase_order_id - supplier_purchase_order_item_id - quantity properties: supplier_purchase_order_id: type: integer description: Purchase order ID. Must not be draft or cancelled. supplier_purchase_order_item_id: type: integer description: >- Purchase order line ID. Must belong to `supplier_purchase_order_id`. quantity: type: number format: float minimum: 0 exclusiveMinimum: true unit_of_measure_id: type: integer nullable: true description: >- Defaults to the purchase order line's ordered unit when omitted. cbm: type: number format: float nullable: true minimum: 0 description: Cubic meters (volume) for this line carton_quantity: type: integer nullable: true minimum: 0 carton_dimensions: type: string nullable: true maxLength: 100 shipment_extra_costs: type: array nullable: true items: type: object required: - name - quantity - unit_price properties: name: type: string quantity: type: number format: float unit_price: type: number format: float cost_allocation_type: type: string nullable: true reference_number: type: string nullable: true category_ids: type: array nullable: true items: type: integer tag_ids: type: array nullable: true items: type: integer internal_skus: type: array nullable: true items: type: integer supplier_skus: type: array nullable: true items: type: integer po_numbers: type: array nullable: true items: type: integer custom_fields: type: object nullable: true additionalProperties: true description: >- Custom field values as a label => value map, e.g. `{ "Cargo Ready Date": "2026-11-20" }` example: reference_number: SHIP-1001 warehouse_id: 4 shipment_status_id: 2 shipping_date: '2026-11-04' tracking_number: 1Z999 shipped_by: Freight shipment_type: Sea estimated_arrival: '2026-12-01' volume_target_cbm: 68 shipment_items: - supplier_purchase_order_id: 1001 supplier_purchase_order_item_id: 55 quantity: 10 cbm: 1.2 carton_quantity: 2 carton_dimensions: 40x30x20 shipment_extra_costs: - name: Ocean freight quantity: 1 unit_price: 450 custom_fields: Cargo Ready Date: '2026-11-20' responses: '201': description: Shipment created content: application/json: schema: type: object properties: data: type: object properties: id: type: integer created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true reference_number: type: string description: Supplier reference number for this shipment total_shipping_cost: type: number format: float shipping_date: type: string format: date-time nullable: true warehouse_id: type: integer nullable: true description: Destination warehouse ID shipment_status_id: type: integer nullable: true notes: type: string nullable: true description: Free-text notes on the shipment tracking_number: type: string nullable: true description: Carrier tracking number shipped_by: type: string nullable: true enum: - Freight - Supplier description: Who is responsible for shipping shipment_type: type: string nullable: true enum: - Air - Sea - Road - Rail - Express description: Mode of transport for the shipment estimated_arrival: type: string format: date nullable: true description: Estimated arrival date is_closed: type: boolean description: >- Whether the shipment is marked as closed. Closing has no enforced behavior (it does not gate edits, pushes, or receiving) and is provided for filtering and reporting. It can be set manually, and is also set to `true` automatically when a receiving report brings every shipment line to fully received (the shipment status is moved to its "received"/Arrived mapping at the same time). Automatic closing never reopens a shipment — if received quantity later drops (e.g. a voided receipt), `is_closed` stays `true`. volume_target_cbm: type: number format: float nullable: true description: >- Container volume target in cubic meters. Null when unset. sync_status: type: string nullable: true description: Integration sync status (e.g. "synced", "unsynced") last_synced_at: type: string format: date-time nullable: true last_synced_status: description: >- Raw sync status payload from the integration (shape varies) nullable: true shipment_status: type: object nullable: true properties: id: type: integer name: type: string warehouse: allOf: - type: object properties: id: type: integer status: type: string name: type: string parent_id: type: integer nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time nullable: true shipment_items: type: array description: Line items (present when the relation is loaded) items: type: object properties: id: type: integer created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true supplier_purchase_order_shipment_id: type: integer supplier_purchase_order_id: type: integer supplier_purchase_order_item_id: type: integer quantity: type: number format: float unit_of_measure_id: type: integer cbm: type: number format: float nullable: true description: Cubic meters (volume) for this line carton_quantity: type: integer nullable: true description: Number of cartons for this line carton_dimensions: type: string nullable: true description: Carton dimensions for this line shipment_extra_costs: type: array description: >- Extra costs applied to the shipment (present when the relation is loaded) items: type: object properties: id: type: integer created_at: type: string format: date-time nullable: true updated_at: type: string format: date-time nullable: true supplier_purchase_order_shipment_id: type: integer name: type: string quantity: type: number format: float unit_price: type: number format: float line_total: type: number format: float cost_allocation_type: type: string nullable: true custom_fields: type: object nullable: true description: >- Custom field values for this shipment as a label => value map, e.g. `{ "Cargo Ready Date": "2026-10-20" }`. Only fields with a stored value appear, so a field defined for shipments but never filled in is absent and the object can be `{}`. Date values are `YYYY-MM-DD`. To list the fields defined for shipments (including unset ones), call `GET /custom-fields?object_type=SHIPMENT`. additionalProperties: true '202': description: >- More than 200 lines — creation was queued and the shipment is written by a background job content: application/json: schema: type: object properties: job_status_id: type: integer nullable: true status: type: string example: queued message: type: string '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string '409': description: '`reference_number` is already used by another shipment' content: application/json: schema: type: object properties: message: type: string '422': description: >- Validation failed, a line is not on the named purchase order, a purchase order is draft or cancelled, or a custom field was rejected. Nothing was written. 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.