# Managing Transport Orders

## Objective

Transport orders are the starting point of every operation in Transportial. This example walks through creating, updating, and managing transport orders from different sources.

## Creating a Transport Order via API

The most direct way to create a transport order:


```bash
curl -X POST https://api.otms.transportial.com/api/transportOrder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Shipment AMS-RTD #1042",
    "status": "requested",
    "customer": { "id": "customer-business-uuid" },
    "consignments": [
      {
        "status": "requested",
        "goods": [
          {
            "type": "items",
            "description": "Electronics",
            "quantity": 120,
            "weight": { "value": 2400, "unit": "kg" }
          }
        ]
      }
    ]
  }'
```

**Response:**


```json
{
  "success": true,
  "message": "OK",
  "transportOrder": {
    "id": "to-uuid",
    "name": "Shipment AMS-RTD #1042",
    "status": "requested",
    "consignments": [
      {
        "id": "consignment-uuid",
        "status": "requested",
        "goods": [
          {
            "type": "items",
            "description": "Electronics",
            "quantity": 120,
            "weight": { "value": 2400, "unit": "kg" }
          }
        ]
      }
    ],
    "createdAt": "2026-03-22T10:30:00Z"
  }
}
```

## Creating from Email

Transport orders can also be created from incoming emails using the mail receiver endpoint:


```bash
curl -X PUT https://api.otms.transportial.com/api/transportOrder/mail/receiver \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "from": "customer@example.com",
    "subject": "Transport request - 50 pallets RTD to BER",
    "body": "Please arrange transport for 50 pallets..."
  }'
```

Transportial parses the email content and creates a transport order automatically.

## Updating a Transport Order

Update fields on an existing transport order:


```bash
curl -X PUT https://api.otms.transportial.com/api/transportOrder \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "id": "to-uuid",
    "name": "Shipment AMS-RTD #1042 (updated)",
    "status": "accepted"
  }'
```

## Listing Transport Orders

Retrieve a paginated list of transport orders:


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

**Response:**


```json
{
  "success": true,
  "message": "OK",
  "totalResults": 142,
  "items": [
    {
      "id": "to-uuid",
      "name": "Shipment AMS-RTD #1042",
      "status": "requested",
      "createdAt": "2026-03-22T10:30:00Z"
    }
  ]
}
```

## Searching with Filters

Use POST to search with advanced filters:


```bash
curl -X POST "https://api.otms.transportial.com/api/transportOrders/0/20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "status": "requested",
    "customer": { "id": "customer-business-uuid" }
  }'
```

## Transport Order Lifecycle

A transport order progresses through these statuses:

| Status | Description |
|  --- | --- |
| `concept` | Draft, not yet submitted |
| `requested` | Submitted, awaiting acceptance |
| `accepted` | Confirmed by the carrier |
| `calculated_trip` | Route has been calculated |
| `partially_planned` | Some consignments are planned |
| `planned` | All consignments have trips assigned |
| `actual` | Currently in execution |
| `realized` | Completed successfully |
| `cancelled` | Cancelled before completion |
| `declined` | Rejected by the carrier |


## Adding Consignments

A single transport order can have multiple consignments. Add additional consignments to group different goods or destinations:


```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": "Furniture",
        "quantity": 30,
        "weight": { "value": 900, "unit": "kg" }
      }
    ]
  }'
```

## Attaching Documents

Add documents (CMR, POD, photos) to a transport order:


```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" }
    ]
  }'
```

## Next Steps

- Plan trips for your consignments with the [Trips & Planning guide](/guides/trips-and-planning)
- Generate invoices from completed orders with the [Invoicing guide](/guides/invoicing-and-finance)
- Learn about the [full entity hierarchy](/guides/concepts)