Create purchase order shipment
curl --request POST \
--url https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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"
}
}
'import requests
url = "https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments"
payload = {
"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" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'}
})
};
fetch('https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments"
payload := strings.NewReader("{\n \"reference_number\": \"SHIP-1001\",\n \"warehouse_id\": 4,\n \"shipment_status_id\": 2,\n \"shipping_date\": \"2026-11-04\",\n \"tracking_number\": \"1Z999\",\n \"shipped_by\": \"Freight\",\n \"shipment_type\": \"Sea\",\n \"estimated_arrival\": \"2026-12-01\",\n \"volume_target_cbm\": 68,\n \"shipment_items\": [\n {\n \"supplier_purchase_order_id\": 1001,\n \"supplier_purchase_order_item_id\": 55,\n \"quantity\": 10,\n \"cbm\": 1.2,\n \"carton_quantity\": 2,\n \"carton_dimensions\": \"40x30x20\"\n }\n ],\n \"shipment_extra_costs\": [\n {\n \"name\": \"Ocean freight\",\n \"quantity\": 1,\n \"unit_price\": 450\n }\n ],\n \"custom_fields\": {\n \"Cargo Ready Date\": \"2026-11-20\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reference_number\": \"SHIP-1001\",\n \"warehouse_id\": 4,\n \"shipment_status_id\": 2,\n \"shipping_date\": \"2026-11-04\",\n \"tracking_number\": \"1Z999\",\n \"shipped_by\": \"Freight\",\n \"shipment_type\": \"Sea\",\n \"estimated_arrival\": \"2026-12-01\",\n \"volume_target_cbm\": 68,\n \"shipment_items\": [\n {\n \"supplier_purchase_order_id\": 1001,\n \"supplier_purchase_order_item_id\": 55,\n \"quantity\": 10,\n \"cbm\": 1.2,\n \"carton_quantity\": 2,\n \"carton_dimensions\": \"40x30x20\"\n }\n ],\n \"shipment_extra_costs\": [\n {\n \"name\": \"Ocean freight\",\n \"quantity\": 1,\n \"unit_price\": 450\n }\n ],\n \"custom_fields\": {\n \"Cargo Ready Date\": \"2026-11-20\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reference_number\": \"SHIP-1001\",\n \"warehouse_id\": 4,\n \"shipment_status_id\": 2,\n \"shipping_date\": \"2026-11-04\",\n \"tracking_number\": \"1Z999\",\n \"shipped_by\": \"Freight\",\n \"shipment_type\": \"Sea\",\n \"estimated_arrival\": \"2026-12-01\",\n \"volume_target_cbm\": 68,\n \"shipment_items\": [\n {\n \"supplier_purchase_order_id\": 1001,\n \"supplier_purchase_order_item_id\": 55,\n \"quantity\": 10,\n \"cbm\": 1.2,\n \"carton_quantity\": 2,\n \"carton_dimensions\": \"40x30x20\"\n }\n ],\n \"shipment_extra_costs\": [\n {\n \"name\": \"Ocean freight\",\n \"quantity\": 1,\n \"unit_price\": 450\n }\n ],\n \"custom_fields\": {\n \"Cargo Ready Date\": \"2026-11-20\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"reference_number": "<string>",
"total_shipping_cost": 123,
"shipping_date": "2023-11-07T05:31:56Z",
"warehouse_id": 123,
"shipment_status_id": 123,
"notes": "<string>",
"tracking_number": "<string>",
"shipped_by": "Freight",
"shipment_type": "Air",
"estimated_arrival": "2023-12-25",
"is_closed": true,
"volume_target_cbm": 123,
"sync_status": "<string>",
"last_synced_at": "2023-11-07T05:31:56Z",
"last_synced_status": "<unknown>",
"shipment_status": {
"id": 123,
"name": "<string>"
},
"warehouse": {
"id": 123,
"status": "<string>",
"name": "<string>",
"parent_id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
},
"shipment_items": [
{
"id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"supplier_purchase_order_shipment_id": 123,
"supplier_purchase_order_id": 123,
"supplier_purchase_order_item_id": 123,
"quantity": 123,
"unit_of_measure_id": 123,
"cbm": 123,
"carton_quantity": 123,
"carton_dimensions": "<string>"
}
],
"shipment_extra_costs": [
{
"id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"supplier_purchase_order_shipment_id": 123,
"name": "<string>",
"quantity": 123,
"unit_price": 123,
"line_total": 123,
"cost_allocation_type": "<string>"
}
],
"custom_fields": {}
}
}{
"job_status_id": 123,
"status": "queued",
"message": "<string>"
}{
"message": "<string>"
}{
"message": "<string>"
}{
"message": "<string>",
"errors": {}
}Purchase Order Shipments
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_itemsis required and must contain at least one line. Each line’ssupplier_purchase_order_item_idmust belong to itssupplier_purchase_order_id, otherwise422.unit_of_measure_idis optional per line; when omitted it is taken from the purchase order line’s ordered unit (422if that line has no ordered unit).reference_numberis optional and generated when omitted. A reference already used by another shipment returns409.shipped_byandshipment_typeaccept any casing and are stored in their canonical form (e.g.sea→Sea).- A draft or cancelled purchase order on any line returns
422and nothing is written. custom_fieldsis an optional label => value map resolved the same way asPUT /purchase-order-shipments/{id}/custom-fields: an unknown label, or one defined only for another record type, is422and is never auto-created. Whencustom_fieldsis 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_coston 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.
POST
/
purchase-order-shipments
Create purchase order shipment
curl --request POST \
--url https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"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"
}
}
'import requests
url = "https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments"
payload = {
"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" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
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'}
})
};
fetch('https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments"
payload := strings.NewReader("{\n \"reference_number\": \"SHIP-1001\",\n \"warehouse_id\": 4,\n \"shipment_status_id\": 2,\n \"shipping_date\": \"2026-11-04\",\n \"tracking_number\": \"1Z999\",\n \"shipped_by\": \"Freight\",\n \"shipment_type\": \"Sea\",\n \"estimated_arrival\": \"2026-12-01\",\n \"volume_target_cbm\": 68,\n \"shipment_items\": [\n {\n \"supplier_purchase_order_id\": 1001,\n \"supplier_purchase_order_item_id\": 55,\n \"quantity\": 10,\n \"cbm\": 1.2,\n \"carton_quantity\": 2,\n \"carton_dimensions\": \"40x30x20\"\n }\n ],\n \"shipment_extra_costs\": [\n {\n \"name\": \"Ocean freight\",\n \"quantity\": 1,\n \"unit_price\": 450\n }\n ],\n \"custom_fields\": {\n \"Cargo Ready Date\": \"2026-11-20\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reference_number\": \"SHIP-1001\",\n \"warehouse_id\": 4,\n \"shipment_status_id\": 2,\n \"shipping_date\": \"2026-11-04\",\n \"tracking_number\": \"1Z999\",\n \"shipped_by\": \"Freight\",\n \"shipment_type\": \"Sea\",\n \"estimated_arrival\": \"2026-12-01\",\n \"volume_target_cbm\": 68,\n \"shipment_items\": [\n {\n \"supplier_purchase_order_id\": 1001,\n \"supplier_purchase_order_item_id\": 55,\n \"quantity\": 10,\n \"cbm\": 1.2,\n \"carton_quantity\": 2,\n \"carton_dimensions\": \"40x30x20\"\n }\n ],\n \"shipment_extra_costs\": [\n {\n \"name\": \"Ocean freight\",\n \"quantity\": 1,\n \"unit_price\": 450\n }\n ],\n \"custom_fields\": {\n \"Cargo Ready Date\": \"2026-11-20\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{companyName}.api.joinluminous.com/external/api/v1/purchase-order-shipments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reference_number\": \"SHIP-1001\",\n \"warehouse_id\": 4,\n \"shipment_status_id\": 2,\n \"shipping_date\": \"2026-11-04\",\n \"tracking_number\": \"1Z999\",\n \"shipped_by\": \"Freight\",\n \"shipment_type\": \"Sea\",\n \"estimated_arrival\": \"2026-12-01\",\n \"volume_target_cbm\": 68,\n \"shipment_items\": [\n {\n \"supplier_purchase_order_id\": 1001,\n \"supplier_purchase_order_item_id\": 55,\n \"quantity\": 10,\n \"cbm\": 1.2,\n \"carton_quantity\": 2,\n \"carton_dimensions\": \"40x30x20\"\n }\n ],\n \"shipment_extra_costs\": [\n {\n \"name\": \"Ocean freight\",\n \"quantity\": 1,\n \"unit_price\": 450\n }\n ],\n \"custom_fields\": {\n \"Cargo Ready Date\": \"2026-11-20\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"reference_number": "<string>",
"total_shipping_cost": 123,
"shipping_date": "2023-11-07T05:31:56Z",
"warehouse_id": 123,
"shipment_status_id": 123,
"notes": "<string>",
"tracking_number": "<string>",
"shipped_by": "Freight",
"shipment_type": "Air",
"estimated_arrival": "2023-12-25",
"is_closed": true,
"volume_target_cbm": 123,
"sync_status": "<string>",
"last_synced_at": "2023-11-07T05:31:56Z",
"last_synced_status": "<unknown>",
"shipment_status": {
"id": 123,
"name": "<string>"
},
"warehouse": {
"id": 123,
"status": "<string>",
"name": "<string>",
"parent_id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
},
"shipment_items": [
{
"id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"supplier_purchase_order_shipment_id": 123,
"supplier_purchase_order_id": 123,
"supplier_purchase_order_item_id": 123,
"quantity": 123,
"unit_of_measure_id": 123,
"cbm": 123,
"carton_quantity": 123,
"carton_dimensions": "<string>"
}
],
"shipment_extra_costs": [
{
"id": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"supplier_purchase_order_shipment_id": 123,
"name": "<string>",
"quantity": 123,
"unit_price": 123,
"line_total": 123,
"cost_allocation_type": "<string>"
}
],
"custom_fields": {}
}
}{
"job_status_id": 123,
"status": "queued",
"message": "<string>"
}{
"message": "<string>"
}{
"message": "<string>"
}{
"message": "<string>",
"errors": {}
}Authorizations
Authenticate using a bearer token. To create a token, navigate to /settings/api-tokens and click Create API Token.
Body
application/json
Minimum array length:
1Show child attributes
Show child attributes
Supplier reference number. Generated when omitted; 409 when already in use.
Maximum string length:
255Destination warehouse (location) ID
Shipment status ID
Maximum string length:
255Who is responsible for shipping (case-insensitive)
Available options:
Freight, Supplier Mode of transport (case-insensitive)
Available options:
Air, Sea, Road, Rail, Express Container volume target in cubic meters
Required range:
x >= 0Show child attributes
Show child attributes
Custom field values as a label => value map, e.g. { "Cargo Ready Date": "2026-11-20" }
Response
Shipment created
Show child attributes
Show child attributes