# 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:


```bash
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:**


```json
{
  "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:


```json
{
  "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:


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

## Get a Consignment


```bash
# 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


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

## Search Consignments


```bash
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:


```bash
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:


```bash
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:


```json
{
  "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:


```bash
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:


```bash
# 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](/guides/quickstart)
- Plan trips for your consignments in [Trips & Planning](/guides/trips-and-planning)
- See the full [API Reference](/apis) for all consignment and goods endpoints