Consignments & Goods

Consignments are line-item groupings of goods within a transport order. They represent what needs to be moved. This guide covers creating, managing, splitting, and combining consignments.

Creating a Consignment

Consignments are typically created as part of a transport order, but can also be created independently:

curl -X POST https://api.otms.transportial.com/api/consignment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "requested",
    "goods": [
      {
        "type": "items",
        "description": "Electronics",
        "quantity": 120,
        "weight": { "value": 2400, "unit": "kg" }
      }
    ],
    "originalPhysicalSender": { "id": "sender-business-uuid" },
    "originalPhysicalAddressee": { "id": "receiver-business-uuid" }
  }'

Response:

{
  "success": true,
  "message": "OK",
  "consignment": {
    "id": "consignment-uuid",
    "status": "requested",
    "goods": [
      {
        "id": "goods-uuid",
        "type": "items",
        "description": "Electronics",
        "quantity": 120,
        "weight": { "value": 2400, "unit": "kg" }
      }
    ],
    "createdAt": "2026-03-22T10:00:00Z"
  }
}

Consignment Statuses

Status	Description
`draft`	Being composed
`requested`	Submitted
`confirmed`	Accepted and ready for planning
`planned`	Trip assigned
`partially_planned`	Some goods assigned to trips
`in_transit`	Currently moving
`partially_in_transit`	Some goods in transit
`completed`	Delivered
`partially_completed`	Some goods delivered
`cancelled`	Cancelled

Goods Types

Goods are polymorphic — the type field determines the structure:

Items

General cargo with quantity, weight, and dimensions:

{
  "type": "items",
  "description": "Consumer electronics",
  "quantity": 50,
  "weight": { "value": 1200, "unit": "kg" },
  "dimensions": {
    "length": { "value": 120, "unit": "cm" },
    "width": { "value": 80, "unit": "cm" },
    "height": { "value": 100, "unit": "cm" }
  }
}

Transport Equipment

Containers, trailers, and other transport equipment:

{
  "type": "transportEquipment",
  "equipmentType": "container",
  "containerNumber": "MSKU1234567",
  "containerSize": "40ft"
}

Get a Consignment

# Standard view
curl -X GET "https://api.otms.transportial.com/api/consignment/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Extended view (full relation data)
curl -X GET "https://api.otms.transportial.com/api/consignment:extended/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

List Consignments

curl -X GET "https://api.otms.transportial.com/api/consignments/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Search Consignments

curl -X POST "https://api.otms.transportial.com/api/consignments/0/20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "requested"
  }'

Splitting Consignments

Split a consignment into multiple parts — useful when goods need to go to different destinations or be transported on separate trips:

curl -X POST https://api.otms.transportial.com/api/consignments/split \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "consignmentId": "consignment-uuid",
    "splits": [
      {
        "goods": [
          {
            "id": "goods-uuid",
            "quantity": 60
          }
        ]
      },
      {
        "goods": [
          {
            "id": "goods-uuid",
            "quantity": 60
          }
        ]
      }
    ]
  }'

Combining Consignments

Merge multiple consignments into one — useful when consolidating shipments:

curl -X POST https://api.otms.transportial.com/api/consignments/combine \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "consignmentIds": [
      "consignment-uuid-1",
      "consignment-uuid-2"
    ]
  }'

Consignment Parties

Each consignment can specify the parties involved:

Field	Description
`originalPhysicalSender`	Business physically sending the goods
`originalPhysicalAddressee`	Business physically receiving the goods
`originalLegalSender`	Legal sender (may differ from physical)
`originalLegalAddressee`	Legal receiver (may differ from physical)

Financial Fields

Consignments carry pricing data:

{
  "expectedCost": { "value": 450.00, "currency": "EUR" },
  "expectedRevenue": { "value": 650.00, "currency": "EUR" },
  "pricingElements": [
    {
      "name": "Base rate",
      "value": 400.00
    },
    {
      "name": "Fuel surcharge",
      "value": 50.00
    }
  ]
}

Attach Documents

Add CMR, photos, or other documents to a consignment:

curl -X PUT "https://api.otms.transportial.com/api/consignment/{id}/documents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "documents": [
      { "id": "document-uuid" }
    ]
  }'

Goods CRUD

Manage goods independently:

# Create goods
curl -X POST https://api.otms.transportial.com/api/goods \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "type": "items",
    "description": "Palletized food products",
    "quantity": 33,
    "weight": { "value": 800, "unit": "kg" }
  }'

# Get goods
curl -X GET "https://api.otms.transportial.com/api/goods/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN"

# List goods
curl -X GET "https://api.otms.transportial.com/api/goodss/0/20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Next Steps

Create transport orders with consignments in the Quickstart guide
Plan trips for your consignments in Trips & Planning
See the full API Reference for all consignment and goods endpoints