API docs by Redocly

4klyft API (1.0.0)

Download OpenAPI specification:

4klyft API Support: support@4klyft.com License: Proprietary

Logistics operations API for the 4klyft platform.

Overview

This API provides comprehensive endpoints for managing:

  • Routes & Execution: Create, manage, and execute delivery routes
  • Shipments & Loads: Track shipments from pickup to delivery
  • Fleet Management: Manage carriers, vehicles, and drivers
  • Proof of Delivery: Capture signatures, photos, and delivery confirmations
  • Settings: Configure system-wide and tenant-specific settings
  • Webhooks: Subscribe to real-time event notifications
  • Analytics: Access delivery performance metrics and reports

Authentication

All API endpoints (except /api/docs and /api/v1/iam/auth/*) require JWT Bearer token authentication. Include the token in the Authorization header:

Authorization: Bearer <your-jwt-token>

Rate Limiting

API requests are rate-limited to ensure fair usage. Standard limits are:

  • 1000 requests per minute for read operations
  • 100 requests per minute for write operations

Error Handling

The API uses RFC 7807 Problem Details for error responses.

Routes & Execution

The current tenant's routing config — a singleton sub-resource.

GET /routing/config returns the tenant's stored row or a virtual platform-defaults-seeded config when no row exists. PATCH /routing/config overwrites the row (creating it on first write).

The identifier is tenantId so the URI surfaces a stable, addressable id even though the request path itself is parameterless — the tenant is resolved bus-side from the execution context per Rule 17.

Get the current tenant routing config

Returns the routing defaults for the authenticated tenant. When no per-tenant row has been written, the response is seeded from platform defaults — never a 404.

Authorizations:
Bearer

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "tenantId": "string",
  • "defaultOptimizationGoal": "fastest",
  • "defaultAvoidances": [
    ],
  • "defaultSolverKind": "greedy_two_opt",
  • "defaultAwaitDecisionTimeoutHours": 0,
  • "defaultMaxStopsBeforeBreak": 0,
  • "defaultMaxDailyDrivingMinutes": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

Update the current tenant routing config

Overwrites the tenant's routing defaults. All fields are required (full replace, not a partial patch).

Authorizations:
Bearer
Request Body schema: application/merge-patch+json
required

The updated TenantRoutingConfig resource

defaultOptimizationGoal
string
Default: ""
Enum: "fastest" "shortest" "fuel_efficient" "balanced"
avoidances
Array of strings
defaultSolverKind
string
Default: ""
Enum: "greedy_two_opt" "external"
defaultAwaitDecisionTimeoutHours
integer > 0
Default: 24
defaultMaxStopsBeforeBreak
integer > 0
Default: 0
defaultMaxDailyDrivingMinutes
integer > 0
Default: 0

Responses

Request samples

Content type
application/merge-patch+json
{
  • "defaultOptimizationGoal": "fastest",
  • "avoidances": [
    ],
  • "defaultSolverKind": "greedy_two_opt",
  • "defaultAwaitDecisionTimeoutHours": 24,
  • "defaultMaxStopsBeforeBreak": 0,
  • "defaultMaxDailyDrivingMinutes": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "tenantId": "string",
  • "defaultOptimizationGoal": "fastest",
  • "defaultAvoidances": [
    ],
  • "defaultSolverKind": "greedy_two_opt",
  • "defaultAwaitDecisionTimeoutHours": 0,
  • "defaultMaxStopsBeforeBreak": 0,
  • "defaultMaxDailyDrivingMinutes": 0,
  • "createdAt": "string",
  • "updatedAt": "string"
}

List all route executions

Retrieve a paginated list of route executions with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "pending" "in_progress" "paused" "completed" "cancelled" "failed"
Example: status=in_progress

Filter by execution status

routeId
string <uuid>
Example: routeId=01912345-6789-7abc-def0-123456789abc

Filter by route UUID

driverId
string <uuid>
Example: driverId=01912345-6789-7abc-def0-123456789abc

Filter by driver UUID

dateFrom
string <date>
Example: dateFrom=2024-06-01

Filter executions from this date (inclusive)

dateTo
string <date>
Example: dateTo=2024-06-30

Filter executions up to this date (inclusive)

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 30
Example: itemsPerPage=30

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Get a route execution

Retrieve a single route execution by ID with detailed node execution progress.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route execution UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "driverId": "01912345-6789-7abc-def0-123456789abc",
  • "driverName": "string",
  • "status": "pending",
  • "completedNodes": 5,
  • "totalNodes": 12,
  • "progressPercent": 41.67,
  • "startedAt": "2024-06-15T08:00:00+00:00",
  • "completedAt": "2024-06-15T16:30:00+00:00",
  • "currentLegToNodeId": "01912345-6789-7abc-def0-123456789abc",
  • "nodeExecutions": [
    ],
  • "createdAt": "2024-06-15T07:00:00+00:00",
  • "updatedAt": "2024-06-15T12:30:00+00:00"
}

Complete a route execution

Mark a route execution as completed. All nodes must be in a terminal state.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route execution UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "driverId": "01912345-6789-7abc-def0-123456789abc",
  • "driverName": "string",
  • "status": "pending",
  • "completedNodes": 5,
  • "totalNodes": 12,
  • "progressPercent": 41.67,
  • "startedAt": "2024-06-15T08:00:00+00:00",
  • "completedAt": "2024-06-15T16:30:00+00:00",
  • "currentLegToNodeId": "01912345-6789-7abc-def0-123456789abc",
  • "nodeExecutions": [
    ],
  • "createdAt": "2024-06-15T07:00:00+00:00",
  • "updatedAt": "2024-06-15T12:30:00+00:00"
}

List issues for a route execution

Retrieve all issues reported for a specific route execution.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route execution UUID

query Parameters
page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 30
Example: itemsPerPage=30

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Report an execution issue

Report an issue encountered during route execution.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route execution UUID

Request Body schema: application/json
required

Execution issue data

type
required
string
Enum: "vehicle_breakdown" "traffic_delay" "customer_unavailable" "address_incorrect" "weather" "other"

Type of issue

severity
required
string
Enum: "low" "medium" "high" "critical"

Severity level of the issue

description
required
string

Description of the issue

nodeExecutionId
string or null <uuid>

Optional node execution UUID this issue relates to

Responses

Request samples

Content type
application/json
{
  • "type": "traffic_delay",
  • "severity": "medium",
  • "description": "Heavy traffic on highway causing 30 minute delay",
  • "nodeExecutionId": "01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "executionId": "01912345-6789-7abc-def0-123456789abc",
  • "type": "vehicle_breakdown",
  • "severity": "low",
  • "description": "Heavy traffic on highway causing 30 minute delay",
  • "reportedAt": "2024-06-15T10:30:00+00:00"
}

Mark a node as arrived

Mark the driver as having arrived at the specified route node. The driver app sends arrivalSource=geofence when auto-detected, manual otherwise.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route execution UUID

nodeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Node execution UUID

Request Body schema: application/json
optional

Node arrival data

arrivalSource
string
Default: "manual"
Enum: "geofence" "manual"

How the arrival was recorded

Responses

Request samples

Content type
application/json
{
  • "arrivalSource": "geofence"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "driverId": "01912345-6789-7abc-def0-123456789abc",
  • "driverName": "string",
  • "status": "pending",
  • "completedNodes": 5,
  • "totalNodes": 12,
  • "progressPercent": 41.67,
  • "startedAt": "2024-06-15T08:00:00+00:00",
  • "completedAt": "2024-06-15T16:30:00+00:00",
  • "currentLegToNodeId": "01912345-6789-7abc-def0-123456789abc",
  • "nodeExecutions": [
    ],
  • "createdAt": "2024-06-15T07:00:00+00:00",
  • "updatedAt": "2024-06-15T12:30:00+00:00"
}

Complete a node

Mark a route node as completed with optional delivery details.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route execution UUID

nodeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Node execution UUID

Request Body schema: application/json
optional

Node completion data

notes
string or null

Optional notes about the delivery

receiverName
string or null

Name of the person who received the delivery

podId
string or null <uuid>

Optional reference to the captured Pod aggregate for this delivery

Responses

Request samples

Content type
application/json
{
  • "notes": "Left package at front door",
  • "receiverName": "John Smith",
  • "podId": "01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "driverId": "01912345-6789-7abc-def0-123456789abc",
  • "driverName": "string",
  • "status": "pending",
  • "completedNodes": 5,
  • "totalNodes": 12,
  • "progressPercent": 41.67,
  • "startedAt": "2024-06-15T08:00:00+00:00",
  • "completedAt": "2024-06-15T16:30:00+00:00",
  • "currentLegToNodeId": "01912345-6789-7abc-def0-123456789abc",
  • "nodeExecutions": [
    ],
  • "createdAt": "2024-06-15T07:00:00+00:00",
  • "updatedAt": "2024-06-15T12:30:00+00:00"
}

Fail a node

Mark a route node as failed with a reason. Distinct from skip — records a failed delivery outcome.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route execution UUID

nodeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Node execution UUID

Request Body schema: application/json
required

Node failure data

reason
required
string

Reason for the failed delivery

Responses

Request samples

Content type
application/json
{
  • "reason": "Recipient refused delivery"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "driverId": "01912345-6789-7abc-def0-123456789abc",
  • "driverName": "string",
  • "status": "pending",
  • "completedNodes": 5,
  • "totalNodes": 12,
  • "progressPercent": 41.67,
  • "startedAt": "2024-06-15T08:00:00+00:00",
  • "completedAt": "2024-06-15T16:30:00+00:00",
  • "currentLegToNodeId": "01912345-6789-7abc-def0-123456789abc",
  • "nodeExecutions": [
    ],
  • "createdAt": "2024-06-15T07:00:00+00:00",
  • "updatedAt": "2024-06-15T12:30:00+00:00"
}

Skip a node

Skip a route node with a reason.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route execution UUID

nodeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Node execution UUID

Request Body schema: application/json
required

Node skip data

reason
required
string

Reason for skipping the node

Responses

Request samples

Content type
application/json
{
  • "reason": "Customer not available, rescheduling delivery"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "driverId": "01912345-6789-7abc-def0-123456789abc",
  • "driverName": "string",
  • "status": "pending",
  • "completedNodes": 5,
  • "totalNodes": 12,
  • "progressPercent": 41.67,
  • "startedAt": "2024-06-15T08:00:00+00:00",
  • "completedAt": "2024-06-15T16:30:00+00:00",
  • "currentLegToNodeId": "01912345-6789-7abc-def0-123456789abc",
  • "nodeExecutions": [
    ],
  • "createdAt": "2024-06-15T07:00:00+00:00",
  • "updatedAt": "2024-06-15T12:30:00+00:00"
}

Start a route execution

Start executing a confirmed route. Assigns a driver and begins tracking progress.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route execution UUID

Request Body schema: application/json
required

Execution start data

driverId
required
string <uuid>

UUID of the driver executing the route

vehicleId
string or null <uuid>

Optional vehicle UUID

Responses

Request samples

Content type
application/json
{
  • "driverId": "01912345-6789-7abc-def0-123456789abc",
  • "vehicleId": "01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "driverId": "01912345-6789-7abc-def0-123456789abc",
  • "driverName": "string",
  • "status": "pending",
  • "completedNodes": 5,
  • "totalNodes": 12,
  • "progressPercent": 41.67,
  • "startedAt": "2024-06-15T08:00:00+00:00",
  • "completedAt": "2024-06-15T16:30:00+00:00",
  • "currentLegToNodeId": "01912345-6789-7abc-def0-123456789abc",
  • "nodeExecutions": [
    ],
  • "createdAt": "2024-06-15T07:00:00+00:00",
  • "updatedAt": "2024-06-15T12:30:00+00:00"
}

List selectable optimization engines

Catalog of route-optimization engines available to the current tenant. Each entry carries its feature set, access tier, and whether the tenant may select it (accessible) and whether it is currently usable (available).

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Get an optimization run

Live status, phase, progress and — once ready — the staged proposal of an optimization run.

Authorizations:
Bearer
path Parameters
id
required
string

OptimizationRun identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "status": "awaiting_decision",
  • "phase": "solving",
  • "phaseLabel": "Optimizing",
  • "phaseDetail": "google",
  • "progressPercent": 45,
  • "engineKind": "in_house_greedy",
  • "requestedBy": "string",
  • "decidedBy": "string",
  • "proposal": {
    },
  • "failureReason": "string",
  • "decisionReason": "string",
  • "createdAt": "2026-07-14T09:00:00+00:00",
  • "updatedAt": "2026-07-14T09:00:12+00:00"
}

Accept an optimization run's proposal

Write the staged proposal onto the route (nodes renumbered to the optimized sequence, distance/duration/geometry recorded) and close the run as applied.

Authorizations:
Bearer
path Parameters
id
required
string

OptimizationRun identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "status": "awaiting_decision",
  • "phase": "solving",
  • "phaseLabel": "Optimizing",
  • "phaseDetail": "google",
  • "progressPercent": 45,
  • "engineKind": "in_house_greedy",
  • "requestedBy": "string",
  • "decidedBy": "string",
  • "proposal": {
    },
  • "failureReason": "string",
  • "decisionReason": "string",
  • "createdAt": "2026-07-14T09:00:00+00:00",
  • "updatedAt": "2026-07-14T09:00:12+00:00"
}

Reject an optimization run's proposal

Discard the staged proposal. The route is left exactly as it was — nothing was ever written to it.

Authorizations:
Bearer
path Parameters
id
required
string

OptimizationRun identifier

Request Body schema:
required

The new OptimizationRun resource

reason
string or null <= 500 characters

Why the operator rejected the proposal — recorded on the run for audit.

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "status": "awaiting_decision",
  • "phase": "solving",
  • "phaseLabel": "Optimizing",
  • "phaseDetail": "google",
  • "progressPercent": 45,
  • "engineKind": "in_house_greedy",
  • "requestedBy": "string",
  • "decidedBy": "string",
  • "proposal": {
    },
  • "failureReason": "string",
  • "decisionReason": "string",
  • "createdAt": "2026-07-14T09:00:00+00:00",
  • "updatedAt": "2026-07-14T09:00:12+00:00"
}

List all routes

Retrieve a paginated list of routes with optional filters. Supports filtering by status, team, and date range.

Authorizations:
Bearer
query Parameters
status
string
Enum: "draft" "confirmed" "in_progress" "completed" "cancelled"
Example: status=confirmed

Filter by route status

crewId
string <uuid>
Example: crewId=01912345-6789-7abc-def0-123456789abc

Filter by team UUID

date
string <date>
Example: date=2024-06-15

Filter routes for an exact date

dateFrom
string <date>
Example: dateFrom=2024-01-01

Filter routes from this date (inclusive)

dateTo
string <date>
Example: dateTo=2024-12-31

Filter routes up to this date (inclusive)

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 30
Example: itemsPerPage=30

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a route

Create a new route in draft status. The route can then have nodes and loads added before confirmation.

Authorizations:
Bearer
Request Body schema: application/json
required

Route creation data

code
required
string [ 2 .. 50 ] characters

Unique route code

date
required
string <date>

Scheduled date for the route

crewId
string or null <uuid>

Optional team UUID to assign

label
string or null <= 255 characters

Short label for the route

description
string or null

Detailed description of the route

defaultNodeDurationMinutes
integer >= 1
Default: 30

Default time allocated per stop in minutes

Responses

Request samples

Content type
application/json
{
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area and business district",
  • "defaultNodeDurationMinutes": 15
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "teamName": "Express Logistics",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area",
  • "status": "draft",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "isLocked": false,
  • "isOptimized": false,
  • "defaultNodeDurationMinutes": 15,
  • "distanceKm": 42.5,
  • "durationMinutes": 60,
  • "geometry": "ionF~vfe@k@fB{@hC",
  • "progressPercent": 75,
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "startAnchor": {
    },
  • "endAnchor": {
    },
  • "resources": [
    ]
}

Get a route by code

Retrieve a single route by its human-readable code. Useful when the UUID is not known.

Authorizations:
Bearer
path Parameters
code
required
string [ 2 .. 50 ] characters
Example: ROUTE-2024-001

Route code (human-readable identifier)

id
required
string

Route identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "teamName": "Express Logistics",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area",
  • "status": "draft",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "isLocked": false,
  • "isOptimized": false,
  • "defaultNodeDurationMinutes": 15,
  • "distanceKm": 42.5,
  • "durationMinutes": 60,
  • "geometry": "ionF~vfe@k@fB{@hC",
  • "progressPercent": 75,
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "startAnchor": {
    },
  • "endAnchor": {
    },
  • "resources": [
    ]
}

Get a route

Retrieve a single route by its UUID. Returns full route details including node and load counts.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "teamName": "Express Logistics",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area",
  • "status": "draft",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "isLocked": false,
  • "isOptimized": false,
  • "defaultNodeDurationMinutes": 15,
  • "distanceKm": 42.5,
  • "durationMinutes": 60,
  • "geometry": "ionF~vfe@k@fB{@hC",
  • "progressPercent": 75,
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "startAnchor": {
    },
  • "endAnchor": {
    },
  • "resources": [
    ]
}

Update a route

Update route details. Only draft routes can be modified. Provide only the fields you want to change.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Request Body schema: application/json
optional

Route update data (partial update supported)

crewId
string or null <uuid>

Team UUID to assign

label
string or null <= 255 characters

Short label for the route

description
string or null

Detailed description

defaultNodeDurationMinutes
integer >= 1

Default time per stop in minutes

Responses

Request samples

Content type
application/json
{
  • "crewId": "3bfb64a6-7eeb-4376-b155-bfb9c0405b76",
  • "label": "string",
  • "description": "string",
  • "defaultNodeDurationMinutes": 1
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "teamName": "Express Logistics",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area",
  • "status": "draft",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "isLocked": false,
  • "isOptimized": false,
  • "defaultNodeDurationMinutes": 15,
  • "distanceKm": 42.5,
  • "durationMinutes": 60,
  • "geometry": "ionF~vfe@k@fB{@hC",
  • "progressPercent": 75,
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "startAnchor": {
    },
  • "endAnchor": {
    },
  • "resources": [
    ]
}

Set a route's start/end anchors

Set or clear the route's start and end anchors. Each anchor carries an address with grouped coordinates and an optional depotId (bare Dispatch depot id). Anchors may be the same depot, different depots, or non-depot park spots. Omit or null an anchor to clear it.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Request Body schema: application/merge-patch+json
required

The updated Route resource

RouteAnchorInput (object) or null
RouteAnchorInput (object) or null

Responses

Request samples

Content type
application/merge-patch+json
{
  • "startAnchor": {
    },
  • "endAnchor": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "teamName": "Express Logistics",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area",
  • "status": "draft",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "isLocked": false,
  • "isOptimized": false,
  • "defaultNodeDurationMinutes": 15,
  • "distanceKm": 42.5,
  • "durationMinutes": 60,
  • "geometry": "ionF~vfe@k@fB{@hC",
  • "progressPercent": 75,
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "startAnchor": {
    },
  • "endAnchor": {
    },
  • "resources": [
    ]
}

Cancel a route

Cancel a route. Routes can be cancelled in draft or confirmed status. In-progress routes should be completed or failed through the execution endpoints.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "teamName": "Express Logistics",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area",
  • "status": "draft",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "isLocked": false,
  • "isOptimized": false,
  • "defaultNodeDurationMinutes": 15,
  • "distanceKm": 42.5,
  • "durationMinutes": 60,
  • "geometry": "ionF~vfe@k@fB{@hC",
  • "progressPercent": 75,
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "startAnchor": {
    },
  • "endAnchor": {
    },
  • "resources": [
    ]
}

Confirm a route

Confirm a draft route for execution. Once confirmed, the route is ready to be assigned to a driver and started. This action validates all nodes and loads.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "teamName": "Express Logistics",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area",
  • "status": "draft",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "isLocked": false,
  • "isOptimized": false,
  • "defaultNodeDurationMinutes": 15,
  • "distanceKm": 42.5,
  • "durationMinutes": 60,
  • "geometry": "ionF~vfe@k@fB{@hC",
  • "progressPercent": 75,
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "startAnchor": {
    },
  • "endAnchor": {
    },
  • "resources": [
    ]
}

Dispatch a route with human confirmation

Start a human-in-the-loop route dispatch: optimize the route (propose flow — nothing is written to the route yet), then ask the operator to Accept or Reject the optimized plan on the /api/operations feed before it is applied. Returns 202 with the route; the RouteDispatchSaga runs in the background.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "teamName": "Express Logistics",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area",
  • "status": "draft",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "isLocked": false,
  • "isOptimized": false,
  • "defaultNodeDurationMinutes": 15,
  • "distanceKm": 42.5,
  • "durationMinutes": 60,
  • "geometry": "ionF~vfe@k@fB{@hC",
  • "progressPercent": 75,
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "startAnchor": {
    },
  • "endAnchor": {
    },
  • "resources": [
    ]
}

Queue route manifest / run-sheet generation

Queue asynchronous rendering of the route as a manifest / run-sheet Document (default PDF) — driver run-sheet listing every stop in optimized sequence with addresses, time windows, pickup/delivery tasks and the assigned rig. Returns immediately (202) with a QueueJobResponse; track progress and download on the /api/operations feed (its JobItem shares the returned jobId).

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Request Body schema:
required

The new Route resource

format
string
Default: "pdf"
Enum: "pdf" "html"

Output format for the manifest.

includeLoads
boolean
Default: true

Whether to include detailed load information.

includeNodes
boolean
Default: true

Whether to include route node details.

Responses

Request samples

Content type
{
  • "format": "pdf",
  • "includeLoads": true,
  • "includeNodes": true
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "jobId": "",
  • "kind": "",
  • "title": "",
  • "status": "pending",
  • "subjectRef": "string"
}

Queue route optimization

Queue asynchronous optimization of the route's stop ordering to minimize travel time and distance. Returns immediately (202) with a QueueJobResponse; the optimized plan is written straight onto the route when the background run completes. Track progress and outcome on the /api/operations feed (its JobItem shares the returned jobId). All stops must have coordinates.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Request Body schema: application/json
optional

Optional optimization constraints plus an optional engine override. Omit everything to optimize with the route's persisted anchors/defaults and the registry's default engine.

maxDurationMinutes
integer

Max route duration in minutes

maxDistanceKm
integer

Max route distance in kilometers

engine
string or null

Optional optimization-engine key; omit to let the registry pick the default (in-house greedy).

Responses

Request samples

Content type
application/json
{
  • "maxDurationMinutes": 480,
  • "maxDistanceKm": 500,
  • "engine": "in_house_greedy"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "jobId": "",
  • "kind": "",
  • "title": "",
  • "status": "pending",
  • "subjectRef": "string"
}

Recover a route

Spawn a new draft route carrying only the incomplete stops of a failed or cancelled route. A stop is incomplete unless its execution reached the completed state — pending, skipped, and failed stops are all recovered, re-sequenced 1..N, with their package/shipment refs and task definitions. Returns the newly created route. Fails (409) when the source route has no incomplete stops.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

UUID of the source (failed/cancelled) route to recover from

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "teamName": "Express Logistics",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area",
  • "status": "draft",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "isLocked": false,
  • "isOptimized": false,
  • "defaultNodeDurationMinutes": 15,
  • "distanceKm": 42.5,
  • "durationMinutes": 60,
  • "geometry": "ionF~vfe@k@fB{@hC",
  • "progressPercent": 75,
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "startAnchor": {
    },
  • "endAnchor": {
    },
  • "resources": [
    ]
}

Reorder a route's nodes

Replace the sequence of a route's nodes with an operator-supplied order. The supplied list must contain every current node id exactly once; partial sequences, duplicates, or unknown ids are rejected.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Request Body schema: application/json
optional

Ordered list of node ULIDs

nodeSequence
required
Array of strings

Ordered node ULIDs, applied as positions 1..N.

Responses

Request samples

Content type
application/json
{
  • "nodeSequence": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "teamName": "Express Logistics",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area",
  • "status": "draft",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "isLocked": false,
  • "isOptimized": false,
  • "defaultNodeDurationMinutes": 15,
  • "distanceKm": 42.5,
  • "durationMinutes": 60,
  • "geometry": "ionF~vfe@k@fB{@hC",
  • "progressPercent": 75,
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "startAnchor": {
    },
  • "endAnchor": {
    },
  • "resources": [
    ]
}

List nodes for a route

Retrieve all nodes (stops) for a specific route, ordered by sequence.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Add a node to a route

Add a new stop/node to a route at a specific location.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Request Body schema:
required

The new RouteNode resource

type
required
string
Default: "stop"
Enum: "pickup" "delivery" "waypoint" "stop"
latitude
required
number [ -90 .. 90 ]
longitude
required
number [ -180 .. 180 ]
address
string or null <= 500 characters
street
string or null <= 255 characters
city
string or null <= 100 characters
postalCode
string or null <= 20 characters
countryCode
string or null <= 2 characters
province
string or null <= 100 characters
label
string or null <= 255 characters
timeWindowStart
string or null^(.*(^([01]\d|2[0-3]):[0-5]\d$).*)$
timeWindowEnd
string or null^(.*(^([01]\d|2[0-3]):[0-5]\d$).*)$
serviceDurationMinutes
integer or null > 0
contactName
string or null <= 255 characters
contactPhone
string or null <= 50 characters
instructions
string or null <= 1000 characters
sequence
integer or null >= 0
packageId
string or null

Responses

Request samples

Content type
{
  • "type": "pickup",
  • "latitude": -90,
  • "longitude": -180,
  • "address": "string",
  • "street": "string",
  • "city": "string",
  • "postalCode": "string",
  • "countryCode": "st",
  • "province": "string",
  • "label": "string",
  • "timeWindowStart": "string",
  • "timeWindowEnd": "string",
  • "serviceDurationMinutes": 0,
  • "contactName": "string",
  • "contactPhone": "string",
  • "instructions": "string",
  • "sequence": 0,
  • "packageId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "routeId": "string",
  • "sequence": 1,
  • "status": "pending",
  • "street": "string",
  • "streetLine2": "string",
  • "city": "string",
  • "postalCode": "string",
  • "countryCode": "string",
  • "province": "string",
  • "latitude": 50.8503,
  • "longitude": 4.3517,
  • "shipmentId": "string",
  • "serviceDurationMinutes": 15,
  • "timeWindowStart": "09:00",
  • "timeWindowEnd": "17:00",
  • "instructions": "Gate code 4821, leave with reception.",
  • "legDistanceKm": 12.4,
  • "legDurationMinutes": 25,
  • "arrivalTime": "string",
  • "departureTime": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "handlingRequirements": [
    ]
}

Remove a node from a route

Remove a stop/node from a route (e.g. dragging a stop back to the unscheduled pool).

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

nodeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789def

Node UUID

Responses

Update a stop's planning details

Update a node's arrival time window, service duration (time-at-stop) and delivery instructions.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

nodeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789def

Node UUID

Request Body schema: application/merge-patch+json
required

The updated RouteNode resource

timeWindowStart
string or null^(.*(^([01]\d|2[0-3]):[0-5]\d$).*)$
timeWindowEnd
string or null^(.*(^([01]\d|2[0-3]):[0-5]\d$).*)$
serviceDurationMinutes
integer > 0
instructions
string or null <= 1000 characters

Responses

Request samples

Content type
application/merge-patch+json
{
  • "timeWindowStart": "string",
  • "timeWindowEnd": "string",
  • "serviceDurationMinutes": 0,
  • "instructions": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "routeId": "string",
  • "sequence": 1,
  • "status": "pending",
  • "street": "string",
  • "streetLine2": "string",
  • "city": "string",
  • "postalCode": "string",
  • "countryCode": "string",
  • "province": "string",
  • "latitude": 50.8503,
  • "longitude": 4.3517,
  • "shipmentId": "string",
  • "serviceDurationMinutes": 15,
  • "timeWindowStart": "09:00",
  • "timeWindowEnd": "17:00",
  • "instructions": "Gate code 4821, leave with reception.",
  • "legDistanceKm": 12.4,
  • "legDurationMinutes": 25,
  • "arrivalTime": "string",
  • "departureTime": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "handlingRequirements": [
    ]
}

List tasks for a node

Retrieve all tasks (with their operations) for a specific route node.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>

Route UUID

nodeId
required
string <uuid>

Node UUID

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Add a task to a node

Add a per-stop task to a route node. Returns the created task.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>

Route UUID

nodeId
required
string <uuid>

Node UUID

Request Body schema:
required

The new RouteNodeTask resource

type
required
string
Default: "custom"
Enum: "delivery" "pickup" "service" "inspection" "signature" "photo" "payment" "transload" "pod" "custom"
title
required
string <= 255 characters
Default: ""
description
string or null <= 2000 characters
packageId
string or null
AddNodeTaskPayloadInput (object) or null

Responses

Request samples

Content type
{
  • "type": "delivery",
  • "title": "",
  • "description": "string",
  • "packageId": "string",
  • "payload": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "routeId": "string",
  • "nodeId": "string",
  • "type": "delivery",
  • "title": "string",
  • "description": "string",
  • "status": "pending",
  • "packageId": "string",
  • "completedAt": "string",
  • "failureReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "operations": [
    ],
  • "payload": {
    }
}

Complete a node task

Mark a node task as completed. For a POD task, submit the proof captured at the stop (recipient name, signature/photo Document refs, captured-at) to sign the Shipping Pod. Idempotent — completing an already-completed task, or replaying a POD completion, is a no-op.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>

Route UUID

nodeId
required
string <uuid>

Node UUID

taskId
required
string

Task ULID

Request Body schema:
required

The new RouteNodeTask resource

recipientName
string or null <= 255 characters
signatureDocumentRef
string or null

ResourceUri / Document id of the uploaded signature image.

capturedAt
string or null

ISO 8601 capture timestamp; required when proof is submitted.

photoDocumentRefs
Array of strings

ResourceUris / Document ids of uploaded delivery photos.

CoordinatesInput (object) or null
notes
string or null <= 2000 characters
outcome
string or null
Enum: "recipient" "third_party" "mailbox" "safe_place" "other"

Delivery outcome recorded at the stop (recipient/third_party/mailbox/safe_place/other).

Responses

Request samples

Content type
{
  • "recipientName": "string",
  • "signatureDocumentRef": "string",
  • "capturedAt": "string",
  • "photoDocumentRefs": [
    ],
  • "coordinates": {
    },
  • "notes": "string",
  • "outcome": "recipient"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "routeId": "string",
  • "nodeId": "string",
  • "type": "delivery",
  • "title": "string",
  • "description": "string",
  • "status": "pending",
  • "packageId": "string",
  • "completedAt": "string",
  • "failureReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "operations": [
    ],
  • "payload": {
    }
}

Fail a node task

Mark a node task as failed, optionally capturing a reason. A failed task is terminal and cannot subsequently be completed. Idempotent — failing an already-failed task is a no-op.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>

Route UUID

nodeId
required
string <uuid>

Node UUID

taskId
required
string

Task ULID

Request Body schema:
required

The new RouteNodeTask resource

reason
string or null <= 2000 characters

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "routeId": "string",
  • "nodeId": "string",
  • "type": "delivery",
  • "title": "string",
  • "description": "string",
  • "status": "pending",
  • "packageId": "string",
  • "completedAt": "string",
  • "failureReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "operations": [
    ],
  • "payload": {
    }
}

Add an operation to a task

Add an operation (atomic step) to a node task. Returns the updated task.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>

Route UUID

nodeId
required
string <uuid>

Node UUID

taskId
required
string

Task ULID

Request Body schema:
required

The new RouteNodeTask resource

type
required
string
Default: "note"
Enum: "barcode_scan" "signature_capture" "photo_capture" "payment_collection" "document_scan" "checklist" "note" "confirmation"
title
required
string <= 255 characters
Default: ""

Responses

Request samples

Content type
{
  • "type": "barcode_scan",
  • "title": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "routeId": "string",
  • "nodeId": "string",
  • "type": "delivery",
  • "title": "string",
  • "description": "string",
  • "status": "pending",
  • "packageId": "string",
  • "completedAt": "string",
  • "failureReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "operations": [
    ],
  • "payload": {
    }
}

Complete a task operation

Mark a task operation as completed, optionally capturing a result and notes. Idempotent.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>

Route UUID

nodeId
required
string <uuid>

Node UUID

taskId
required
string

Task ULID

operationId
required
string

Operation ULID

Request Body schema:
required

The new RouteNodeTask resource

result
string or null <= 2000 characters
notes
string or null <= 2000 characters

Responses

Request samples

Content type
{
  • "result": "string",
  • "notes": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "routeId": "string",
  • "nodeId": "string",
  • "type": "delivery",
  • "title": "string",
  • "description": "string",
  • "status": "pending",
  • "packageId": "string",
  • "completedAt": "string",
  • "failureReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "operations": [
    ],
  • "payload": {
    }
}

Fail a task operation

Mark a task operation as failed, optionally capturing a reason. A failed operation is terminal and cannot subsequently be completed. Idempotent.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>

Route UUID

nodeId
required
string <uuid>

Node UUID

taskId
required
string

Task ULID

operationId
required
string

Operation ULID

Request Body schema:
required

The new RouteNodeTask resource

reason
string or null <= 2000 characters

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "routeId": "string",
  • "nodeId": "string",
  • "type": "delivery",
  • "title": "string",
  • "description": "string",
  • "status": "pending",
  • "packageId": "string",
  • "completedAt": "string",
  • "failureReason": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "operations": [
    ],
  • "payload": {
    }
}

Start an asynchronous optimization run

Queue an optimization run for the route and return it immediately with status=running. The engine work happens in the background; poll GET /routing/optimization-runs/{id} (or subscribe to Mercure topic /routes/{routeId}) to follow the phases. When the run reaches awaiting_decision it carries a staged proposal — the route is NOT modified until the run is accepted. A route may only have ONE run in flight: requesting another while one is running or awaiting a decision is rejected with 409.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Request Body schema:
required

The new OptimizationRun resource

maxDurationMinutes
integer or null > 0
maxDistanceKm
integer or null > 0
OptimizationOverridesInput (object) or null

Responses

Request samples

Content type
{
  • "maxDurationMinutes": 0,
  • "maxDistanceKm": 0,
  • "overrides": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "status": "awaiting_decision",
  • "phase": "solving",
  • "phaseLabel": "Optimizing",
  • "phaseDetail": "google",
  • "progressPercent": 45,
  • "engineKind": "in_house_greedy",
  • "requestedBy": "string",
  • "decidedBy": "string",
  • "proposal": {
    },
  • "failureReason": "string",
  • "decisionReason": "string",
  • "createdAt": "2026-07-14T09:00:00+00:00",
  • "updatedAt": "2026-07-14T09:00:12+00:00"
}

Assign a fleet resource to a route

Assign an individual fleet resource (power unit, load carrier, driver, or rigid vehicle) directly to a route. A route may be operated by a team OR by individually-assigned resources (or both). Cardinality: at most one propulsion resource, at most one driver, any number of load carriers. The role is derived from the resource when omitted.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

id
required
string

Route identifier

Request Body schema: application/json
required

Resource assignment data

resourceRef
required
string

Opaque ResourceUri of the fleet unit or driver

role
string or null
Enum: "power_unit" "load_carrier" "driver" "rigid_vehicle"

Optional role override; derived from the resource kind when omitted

Responses

Request samples

Content type
application/json
{
  • "resourceRef": "glacia:///fleet/units/01912345-6789-7abc-def0-123456789abc",
  • "role": "power_unit"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "01912345-6789-7abc-def0-123456789abc",
  • "teamName": "Express Logistics",
  • "label": "Downtown Morning Route",
  • "description": "Morning deliveries covering downtown area",
  • "status": "draft",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "isLocked": false,
  • "isOptimized": false,
  • "defaultNodeDurationMinutes": 15,
  • "distanceKm": 42.5,
  • "durationMinutes": 60,
  • "geometry": "ionF~vfe@k@fB{@hC",
  • "progressPercent": 75,
  • "createdAt": "2024-06-14T10:30:00+00:00",
  • "updatedAt": "2024-06-14T14:45:00+00:00",
  • "startAnchor": {
    },
  • "endAnchor": {
    },
  • "resources": [
    ]
}

Unassign a fleet resource from a route

Remove an individually-assigned fleet resource from a route. The resourceRef path segment is the URL-encoded ResourceUri of the assigned resource. Unknown references are a no-op.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

resourceRef
required
string
Example: glacia:%2F%2F%2Ffleet%2Funits%2F01912345-6789-7abc-def0-123456789abc

URL-encoded ResourceUri of the assigned resource

Responses

Get the denormalised snapshot of a route

Returns a single payload combining the route's plan facets (status, code, date, team, node and load counts), optimization-saga facets (current optimization id/status/progress/goal, pending and applied counters, last applied timestamp), and execution facets (execution id, status, progress, started/completed timestamps). Backed by the route_snapshot_views projection — eventually consistent with the underlying aggregates.

Authorizations:
Bearer
path Parameters
routeId
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Route UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "routeId": "01J0AAAAAAAAAAAAAAAAAAAAAA",
  • "tenantId": "string",
  • "status": "draft",
  • "code": "ROUTE-2024-001",
  • "date": "2024-06-15",
  • "crewId": "string",
  • "nodeCount": 12,
  • "loadCount": 45,
  • "currentOptimizationId": "string",
  • "currentOptimizationStatus": "Running",
  • "currentOptimizationOutcome": "applied",
  • "currentOptimizationProgress": 57,
  • "currentOptimizationGoal": "fastest",
  • "pendingOptimizationCount": 0,
  • "appliedOptimizationCount": 3,
  • "lastOptimizationAppliedAt": "string",
  • "executionId": "string",
  • "executionStatus": "pending",
  • "executionProgress": 42,
  • "executionStartedAt": "string",
  • "executionCompletedAt": "string",
  • "updatedAt": "string"
}

Shipments & Loads

A resource that can be placed on a shipment line — the read surface behind the shipment "shippable picker".

Aggregated across every upstream provider (Inventory serial units/batches, Warehousing goods movements, Sales sales orders, Fulfilment orders…) by the {@see \Glacia\Shipping\Application\Shippable\ShippableCatalog}. Each shippable is addressed by an opaque ResourceUri ({@see $reference}); Shipping never leaks the providing module's typed IDs.

Get package audit timeline

Return the event-by-event lifecycle/audit timeline for a package, oldest first.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Parcel UUID

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

List lines packed in a package

Retrieve all shipment lines packed into a specific package.

Authorizations:
Bearer
path Parameters
packageId
required
string <uuid>

ParcelResource identifier

query Parameters
page
integer
Default: 1
itemsPerPage
integer
Default: 50

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

List parcels

Retrieve a paginated list of parcels with optional filters.

Authorizations:
Bearer
query Parameters
status
string
Enum: "pending" "manifested" "dispatched" "delivered" "failed" "returned" "damaged" "lost"
shipmentId
string
routeId
string

Filter to parcels whose shipment is scheduled on this route.

page
integer
Default: 1
itemsPerPage
integer
Default: 20

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a parcel

Create a parcel

Authorizations:
Bearer
Request Body schema:
required

The new Parcel resource

shipmentId
required
string <= 255 characters
barcode
required
string <= 128 characters
weightGrams
integer > 0
requiresSignature
boolean
Default: false
description
string or null <= 500 characters

Responses

Request samples

Content type
{
  • "shipmentId": "string",
  • "barcode": "string",
  • "weightGrams": 0,
  • "requiresSignature": false,
  • "description": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Resolve a parcel by barcode

Retrieve a single parcel by its barcode. Returns 404 when no parcel carries the barcode.

Authorizations:
Bearer
path Parameters
barcode
required
string

Parcel barcode

id
required
string

Parcel identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Get a parcel

Retrieve a single parcel by its ID.

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Report parcel as damaged

Report parcel as damaged

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Request Body schema:
required

The new Parcel resource

description
required
string <= 1000 characters

Responses

Request samples

Content type
{
  • "description": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Mark parcel as delivered

Mark parcel as delivered

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Request Body schema:
required

The new Parcel resource

deliveryMethod
required
string
Default: "delivered_to_recipient"
Enum: "delivered_to_recipient" "left_at_door" "left_with_neighbour" "delivery_box" "reception" "other"
recipientName
string or null <= 255 characters
note
string or null <= 1000 characters

Responses

Request samples

Content type
{
  • "deliveryMethod": "delivered_to_recipient",
  • "recipientName": "string",
  • "note": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Dispatch parcel onto vehicle

Dispatch parcel onto vehicle

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Request Body schema:
required

The new Parcel resource

dispatchedAt

Responses

Request samples

Content type
{
  • "dispatchedAt": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Mark parcel delivery as failed

Mark parcel delivery as failed

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Request Body schema:
required

The new Parcel resource

reason
required
string
Default: "other"
Enum: "recipient_absent" "refused" "address_not_found" "access_denied" "damaged" "other"
note
string or null <= 500 characters

Responses

Request samples

Content type
{
  • "reason": "recipient_absent",
  • "note": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Set parcel handling requirements

Replace the parcel handling: the data-carrying hazmat/temperature requirements plus the pure-marker set (fragile, keep_upright, oversized, signature_required).

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Request Body schema: application/merge-patch+json
required

The updated Parcel resource

HazmatInput (object) or null
TemperatureInput (object) or null
markers
Array of strings

Pure handling markers on the parcel.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "hazmat": {
    },
  • "temperature": {
    },
  • "markers": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Download the parcel label

Stream the rendered parcel label as an attachment. Use ?format=pdf (default) or ?format=zpl.

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

query Parameters
format
string
Default: "pdf"
Enum: "pdf" "zpl"

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Add a shipment line to a parcel

Add a shipment line to a parcel

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Request Body schema:
required

The new Parcel resource

lineId
required
string
Default: ""
quantity
integer > 0
Default: 1

Responses

Request samples

Content type
{
  • "lineId": "",
  • "quantity": 1
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Remove a shipment line from a parcel

Remove a shipment line from a parcel

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

lineId
required
string

Parcel identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Confirm parcel is lost

Confirm parcel is lost

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Request Body schema:
required

The new Parcel resource

reason
required
string <= 500 characters

Responses

Request samples

Content type
{
  • "reason": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Manifest parcel to route

Manifest parcel to route

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Request Body schema:
required

The new Parcel resource

routeId
required
string

Responses

Request samples

Content type
{
  • "routeId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Set parcel measurements

Replace the physical dimensions (L/W/H in mm) and weight (grams) of a parcel.

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Request Body schema: application/merge-patch+json
required

The updated Parcel resource

lengthMm
integer >= 0
Default: 0
widthMm
integer >= 0
Default: 0
heightMm
integer >= 0
Default: 0
weightGrams
integer >= 0
Default: 0

Responses

Request samples

Content type
application/merge-patch+json
{
  • "lengthMm": 0,
  • "widthMm": 0,
  • "heightMm": 0,
  • "weightGrams": 0
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Return parcel to depot

Return parcel to depot

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Request Body schema:
required

The new Parcel resource

reason
required
string <= 500 characters
Default: "Returned to depot"

Responses

Request samples

Content type
{
  • "reason": "Returned to depot"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

Remove parcel from route

Remove parcel from route

Authorizations:
Bearer
path Parameters
id
required
string

Parcel identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "shipmentId": "string",
  • "barcode": "string",
  • "status": "pending",
  • "routeId": "string",
  • "weightGrams": 0,
  • "dimensions": {
    },
  • "hazmat": {
    },
  • "temperature": {
    },
  • "handlingMarkers": "[\"fragile\", \"signature_required\"]",
  • "description": "string",
  • "dispatchedAt": "string",
  • "deliveredAt": "string",
  • "failedAt": "string",
  • "failureReason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "label": {
    }
}

List all shipments

Retrieve a paginated list of shipments with optional filters. Supports filtering by status, type, route, and date range.

Authorizations:
Bearer
query Parameters
status
string
Enum: "pending" "scheduled" "in_transit" "out_for_delivery" "delivered" "failed" "lost" "damaged" "refused" "cancelled"
Example: status=pending

Filter by shipment status

type
string
Enum: "ftl" "ltl"
Example: type=ftl

Filter by shipment type

direction
string
Enum: "outbound" "inbound" "transfer" "intra_warehouse"
Example: direction=inbound

Filter by direction-of-flow (outbound, inbound, transfer, intra_warehouse)

originalShipmentId
string <uuid>
Example: originalShipmentId=01912345-6789-7abc-def0-123456789abc

Filter returns by original shipment UUID

routeId
string <uuid>
Example: routeId=01912345-6789-7abc-def0-123456789abc

Filter by assigned route UUID

clientId
string <uuid>
Example: clientId=01912345-6789-7abc-def0-123456789abc

Filter by owning shipping client UUID

trackingNumber
string
Example: trackingNumber=TRK-2024

Search by tracking number (partial match)

scheduledDateFrom
string <date>
Example: scheduledDateFrom=2024-01-01

Filter shipments scheduled from this date

scheduledDateTo
string <date>
Example: scheduledDateTo=2024-12-31

Filter shipments scheduled up to this date

page
integer >= 1
Default: 1
Example: page=1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 30
Example: itemsPerPage=30

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a shipment

Create a new shipment in pending status. The shipment can then be scheduled to a route for delivery.

Authorizations:
Bearer
Request Body schema: application/json
required

Shipment creation data

clientId
required
string

Shipping Client UUID (the client to bill)

type
required
string
Enum: "ftl" "ltl"

Type of shipment

direction
string
Default: "outbound"
Enum: "outbound" "inbound" "transfer" "intra_warehouse"

Direction-of-flow (defaults to outbound)

reference
string or null <= 100 characters

External tracking/reference number

serviceLevel
string or null
Enum: "standard" "express" "same_day" "next_day"

Service level

handlingRequirements
Array of strings
Items Enum: "fragile" "refrigerated" "hazardous" "oversized"

Handling requirements

object or null
object or null
object or null

Pickup-location coordinates (grouped per Rule 21)

object or null
object or null
object or null

Delivery-location coordinates (grouped per Rule 21)

notes
string or null
billingSubject
string or null
Array of objects

Responses

Request samples

Content type
application/json
{
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ltl",
  • "direction": "outbound",
  • "reference": "string",
  • "serviceLevel": "standard",
  • "handlingRequirements": [
    ],
  • "pickupAddress": {
    },
  • "pickupContact": {
    },
  • "pickupCoordinates": {
    },
  • "deliveryAddress": {
    },
  • "deliveryContact": {
    },
  • "deliveryCoordinates": {
    },
  • "notes": "string",
  • "billingSubject": "string",
  • "lines": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

List shipments needing dispatcher attention

Returns the most-urgent open shipments bucketed by SLA urgency (overdue, at_risk, unassigned, scheduled_ahead) and ranked most → least urgent. Delivered/cancelled/terminal shipments are excluded.

Authorizations:
Bearer
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
Example: limit=50

Maximum number of shipments to return (top-N)

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "member": [
    ]
}

Get a shipment

Retrieve a single shipment by its UUID. Returns full shipment details including sender, recipient, and delivery information.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Shipment UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Update delivery address

Update delivery address

Authorizations:
Bearer
path Parameters
id
required
string

Shipment identifier

Request Body schema:
required

The new Shipment resource

required
ShipmentAddressInput (object) or null
ShipmentContactInput (object) or null
instructions
string or null

Responses

Request samples

Content type
{
  • "deliveryAddress": {
    },
  • "contact": {
    },
  • "instructions": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Cancel a shipment

Cancel a pending or scheduled shipment. Shipments that are in transit or delivered cannot be cancelled.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Shipment UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Set delivery availability window

Set delivery availability window

Authorizations:
Bearer
path Parameters
id
required
string

Shipment identifier

Request Body schema:
required

The new Shipment resource

required
Array of objects (AvailabilitySlotInput)

Responses

Request samples

Content type
{
  • "slots": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Clear delivery availability window

Clear delivery availability window

Authorizations:
Bearer
path Parameters
id
required
string

Shipment identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Dispatch a shipment to a carrier

Assign a shipment to a carrier and route it to fulfilment. INTERNAL (own-fleet) carriers schedule the shipment onto the supplied routeRef — this requires the Routing module enabled and an active internal carrier, otherwise a 409 is returned. EXTERNAL carriers hand the shipment off to the provider integration.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Shipment UUID

Request Body schema: application/json
required

Carrier and (for internal dispatch) routing information

carrierId
required
string <uuid>

Carrier UUID to dispatch to

routeRef
string or null

Route reference to schedule onto (required for internal carriers)

scheduledDate
string or null <date>

Scheduled date for internal dispatch (defaults to today)

Responses

Request samples

Content type
application/json
{
  • "carrierId": "01912345-6789-7abc-def0-123456789abc",
  • "routeRef": "string",
  • "scheduledDate": "2019-08-24"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Download the shipment label

Stream the rendered shipment label as an attachment. Use ?format=pdf (default) or ?format=zpl.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Shipment identifier

query Parameters
format
string
Default: "pdf"
Enum: "pdf" "zpl"

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Generate the shipment + parcel labels

Render and persist the in-house shipment label plus one parcel label per package. Idempotent — re-invoking leaves any live (non-voided) labels untouched.

Authorizations:
Bearer
path Parameters
id
required
string

Shipment identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Regenerate the shipment + parcel labels

Void any live shipment + parcel labels and render fresh ones.

Authorizations:
Bearer
path Parameters
id
required
string

Shipment identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Void the shipment + parcel labels

Void the live label on the shipment and each of its packages. The voided labels are retained for audit.

Authorizations:
Bearer
path Parameters
id
required
string

Shipment identifier

Request Body schema:
required

The new Shipment resource

reason
required
string <= 500 characters
Default: ""

Responses

Request samples

Content type
{
  • "reason": ""
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Add a line item to shipment

Add a line item to shipment

Authorizations:
Bearer
path Parameters
id
required
string

Shipment identifier

Request Body schema:
required

The new Shipment resource

shippableRef
string or null <= 500 characters

Opaque ResourceUri of the shippable this line references (managed line).

quantity
integer > 0
trackingMode
string
Default: "quantity"
Enum: "quantity" "lot" "serial"
weightGrams
integer or null >= 0
description
string or null

Responses

Request samples

Content type
{
  • "shippableRef": "string",
  • "quantity": 0,
  • "trackingMode": "quantity",
  • "weightGrams": 0,
  • "description": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Mark a shipment delivered with a captured Proof of Delivery

Preferred delivery endpoint — enforces that the caller has captured a POD (status signed or refused) before transitioning the shipment to delivered. Links the POD to the shipment for audit.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Shipment UUID

Request Body schema: application/json
required

Delivery data referencing the captured POD

podId
required
string <uuid>

UUID of a Pod with status "signed" or "refused"

deliveredAt
string or null <date-time>
outcome
string or null
Enum: "delivered" "refused"
deliveryMethod
string or null
Enum: "delivered_to_recipient" "delivered_to_third_party" "left_in_mailbox" "kept_in_safe_place" "other"
receiverName
string or null
note
string or null

Responses

Request samples

Content type
application/json
{
  • "podId": "8963ae67-4a9c-404a-b889-2c6d0c10530e",
  • "deliveredAt": "2019-08-24T14:15:22Z",
  • "outcome": "delivered",
  • "deliveryMethod": "delivered_to_recipient",
  • "receiverName": "string",
  • "note": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Queue packing-slip generation

Queue asynchronous rendering of the shipment as a packing-slip Document (default PDF). Returns immediately (202) with a QueueJobResponse; track progress and download on the /api/operations feed (its JobItem shares the returned jobId).

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Shipment identifier

Request Body schema:
required

The new Shipment resource

format
string
Default: "pdf"
Enum: "pdf" "html"

Output format for the packing slip.

Responses

Request samples

Content type
{
  • "format": "pdf"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "jobId": "",
  • "kind": "",
  • "title": "",
  • "status": "pending",
  • "subjectRef": "string"
}

Set pickup availability window

Set pickup availability window

Authorizations:
Bearer
path Parameters
id
required
string

Shipment identifier

Request Body schema:
required

The new Shipment resource

required
Array of objects (AvailabilitySlotInput)

Responses

Request samples

Content type
{
  • "slots": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Clear pickup availability window

Clear pickup availability window

Authorizations:
Bearer
path Parameters
id
required
string

Shipment identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Update the per-shipment POD capture policy

Toggle the requirePhoto flag — when true, the POD captured for this shipment must include at least one photo before the shipment can be marked delivered.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Shipment UUID

Request Body schema: application/json
required

POD policy update

requirePhoto
required
boolean

Whether the captured POD must include at least one photo

Responses

Request samples

Content type
application/json
{
  • "requirePhoto": true
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Schedule a shipment

Schedule a pending shipment to a route for delivery. The shipment will be assigned to a node on the specified route.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Shipment UUID

Request Body schema: application/json
required

Scheduling information

routeId
required
string <uuid>

Route UUID to assign the shipment to

nodeId
string or null <uuid>

Optional specific node UUID to assign to

Responses

Request samples

Content type
application/json
{
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "nodeId": "01912345-6789-7abc-def0-123456789abc"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Set or replace a shipment's SLA / delivery-date commitments

Last-write-wins: the supplied SLA dates fully replace any prior commitments. Omitting all dates clears the SLA. All dates are optional ISO-8601 datetime strings.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Shipment UUID

Request Body schema: application/json
required

SLA / delivery-date commitments

requestedDeliveryAt
string or null <date-time>
deliverByAt
string or null <date-time>
shipByAt
string or null <date-time>
expiresAt
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "requestedDeliveryAt": "2019-08-24T14:15:22Z",
  • "deliverByAt": "2019-08-24T14:15:22Z",
  • "shipByAt": "2019-08-24T14:15:22Z",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Update shipment status

Update shipment status

Authorizations:
Bearer
path Parameters
id
required
string

Shipment identifier

Request Body schema:
required

The new Shipment resource

status
required
string
Enum: "in_transit" "out_for_delivery" "delivered" "failed" "lost" "damaged" "refused" "cancelled"
reason
string or null
deliveryMethod
string or null
receiverName
string or null
deliveryNote
string or null

Responses

Request samples

Content type
{
  • "status": "in_transit",
  • "reason": "string",
  • "deliveryMethod": "string",
  • "receiverName": "string",
  • "deliveryNote": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

Unschedule a shipment

Remove a shipment from its assigned route. The shipment will return to pending status and can be scheduled to a different route.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Shipment UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}

List shipment line items

Retrieve all line items belonging to a specific shipment.

Authorizations:
Bearer
path Parameters
shipmentId
required
string <uuid>

ShipmentResource identifier

query Parameters
page
integer
Default: 1
itemsPerPage
integer
Default: 50

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Proof of Delivery

Proof of Delivery resource.

Captures digital proof (signature or refusal) for a shipment delivery attempt.

Capture a proof of delivery for a shipment

Capture a proof of delivery for a shipment

Authorizations:
Bearer
Request Body schema: application/json
required

Shipment to capture proof for

shipmentId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "shipmentId": "47efd5a2-af91-4417-950a-7f546cd1b5cf"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "shipmentId": "string",
  • "status": "pending",
  • "recipientName": "string",
  • "outcome": "recipient",
  • "proofDocumentRef": "string",
  • "proofUrl": "https://app.example.com/api/v1/document/files/access/eyJ...",
  • "capturedAt": "string",
  • "latitude": 0,
  • "longitude": 0,
  • "refusalReason": "string",
  • "notes": "string",
  • "photoDocumentRefs": [
    ],
  • "photoUrls": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get the proof of delivery for a shipment

Get the proof of delivery for a shipment

Authorizations:
Bearer
path Parameters
shipmentId
required
string <uuid>

Shipment UUID

id
required
string

Pod identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "shipmentId": "string",
  • "status": "pending",
  • "recipientName": "string",
  • "outcome": "recipient",
  • "proofDocumentRef": "string",
  • "proofUrl": "https://app.example.com/api/v1/document/files/access/eyJ...",
  • "capturedAt": "string",
  • "latitude": 0,
  • "longitude": 0,
  • "refusalReason": "string",
  • "notes": "string",
  • "photoDocumentRefs": [
    ],
  • "photoUrls": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a proof of delivery record

Get a proof of delivery record

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Pod UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "shipmentId": "string",
  • "status": "pending",
  • "recipientName": "string",
  • "outcome": "recipient",
  • "proofDocumentRef": "string",
  • "proofUrl": "https://app.example.com/api/v1/document/files/access/eyJ...",
  • "capturedAt": "string",
  • "latitude": 0,
  • "longitude": 0,
  • "refusalReason": "string",
  • "notes": "string",
  • "photoDocumentRefs": [
    ],
  • "photoUrls": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Attach a photo document to a pod

Attach a photo document to a pod

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Pod identifier

Request Body schema: application/json
required

Photo document reference

documentId
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "documentId": "4704590c-004e-410d-adf7-acb7ca0a7052"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "shipmentId": "string",
  • "status": "pending",
  • "recipientName": "string",
  • "outcome": "recipient",
  • "proofDocumentRef": "string",
  • "proofUrl": "https://app.example.com/api/v1/document/files/access/eyJ...",
  • "capturedAt": "string",
  • "latitude": 0,
  • "longitude": 0,
  • "refusalReason": "string",
  • "notes": "string",
  • "photoDocumentRefs": [
    ],
  • "photoUrls": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Record a delivery refusal

Record a delivery refusal

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Pod identifier

Request Body schema: application/json
required

Refusal data

reason
required
string
refusedAt
required
string <date-time>
latitude
number or null
longitude
number or null
notes
string or null

Responses

Request samples

Content type
application/json
{
  • "reason": "string",
  • "refusedAt": "2019-08-24T14:15:22Z",
  • "latitude": 0,
  • "longitude": 0,
  • "notes": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "shipmentId": "string",
  • "status": "pending",
  • "recipientName": "string",
  • "outcome": "recipient",
  • "proofDocumentRef": "string",
  • "proofUrl": "https://app.example.com/api/v1/document/files/access/eyJ...",
  • "capturedAt": "string",
  • "latitude": 0,
  • "longitude": 0,
  • "refusalReason": "string",
  • "notes": "string",
  • "photoDocumentRefs": [
    ],
  • "photoUrls": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Record a signed delivery proof

Record a signed delivery proof

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Pod identifier

Request Body schema: application/json
required

Signature data

recipientName
required
string
signatureData
required
string

Base64-encoded signature

capturedAt
required
string <date-time>
outcome
string or null
Enum: "recipient" "third_party" "mailbox" "safe_place" "other"

Delivery outcome

latitude
number or null
longitude
number or null
notes
string or null

Responses

Request samples

Content type
application/json
{
  • "recipientName": "string",
  • "signatureData": "string",
  • "capturedAt": "2019-08-24T14:15:22Z",
  • "outcome": "recipient",
  • "latitude": 0,
  • "longitude": 0,
  • "notes": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "shipmentId": "string",
  • "status": "pending",
  • "recipientName": "string",
  • "outcome": "recipient",
  • "proofDocumentRef": "string",
  • "proofUrl": "https://app.example.com/api/v1/document/files/access/eyJ...",
  • "capturedAt": "string",
  • "latitude": 0,
  • "longitude": 0,
  • "refusalReason": "string",
  • "notes": "string",
  • "photoDocumentRefs": [
    ],
  • "photoUrls": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Geocoding

Represents a geocoding result.

Geocoding converts addresses to coordinates (forward geocoding) or coordinates to addresses (reverse geocoding).

Geocode an address

Convert an address string to geographic coordinates (forward geocoding).

Authorizations:
Bearer
Request Body schema: application/json
required

Address to geocode

address
required
string

Full address to geocode

Responses

Request samples

Content type
application/json
{
  • "address": "Keizersgracht 123, 1015 CJ Amsterdam, Netherlands"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "address": "Keizersgracht 123, 1015 CJ Amsterdam, Netherlands",
  • "coordinates": {
    },
  • "confidence": 0.95
}

Reverse geocode coordinates

Convert geographic coordinates to an address (reverse geocoding).

Authorizations:
Bearer
Request Body schema: application/json
required

Coordinates to reverse geocode

latitude
required
number <float> [ -90 .. 90 ]

Latitude coordinate

longitude
required
number <float> [ -180 .. 180 ]

Longitude coordinate

Responses

Request samples

Content type
application/json
{
  • "latitude": 52.3676,
  • "longitude": 4.9041
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "address": "Keizersgracht 123, 1015 CJ Amsterdam, Netherlands",
  • "coordinates": {
    },
  • "confidence": 0.95
}

Routing - Number Generation

Resource 'Routing - Number Generation' operations.

Generate a customer reference

Generate a customer reference

Authorizations:
Bearer
Request Body schema:
required

The new CustomerReference resource

number
string

The generated customer reference

type
string

Resource type

barcode
string or null

GS1-128 barcode (if applicable)

generatedAt
string

Generation timestamp (ISO 8601)

Responses

Request samples

Content type
{
  • "number": "CRF000000001",
  • "type": "routing.customer_reference",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "CRF000000001",
  • "type": "routing.customer_reference",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Generate a load barcode

Generate a load barcode

Authorizations:
Bearer
Request Body schema:
required

The new LoadBarcode resource

number
string

The generated load barcode

type
string

Resource type

barcode
string or null

GS1-128 barcode (if applicable)

generatedAt
string

Generation timestamp (ISO 8601)

Responses

Request samples

Content type
{
  • "number": "LDB000000001",
  • "type": "routing.load_barcode",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "LDB000000001",
  • "type": "routing.load_barcode",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Preview the next load barcode

Preview the next load barcode

Authorizations:
Bearer
query Parameters
date
string <date>

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "LDB000000001",
  • "type": "routing.load_barcode",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Generate a route code

Generate a route code

Authorizations:
Bearer
Request Body schema:
required

The new RouteCode resource

number
string

The generated route code

type
string

Resource type

barcode
string or null

GS1-128 barcode (if applicable)

generatedAt
string

Generation timestamp (ISO 8601)

Responses

Request samples

Content type
{
  • "number": "RTE000000001",
  • "type": "routing.route_code",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "RTE000000001",
  • "type": "routing.route_code",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Preview the next route code

Preview the next route code

Authorizations:
Bearer
query Parameters
date
string <date>

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "RTE000000001",
  • "type": "routing.route_code",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Generate a shipment barcode

Generate a shipment barcode

Authorizations:
Bearer
Request Body schema:
required

The new ShipmentBarcode resource

number
string

The generated shipment barcode

type
string

Resource type

barcode
string or null

GS1-128 barcode (if applicable)

generatedAt
string

Generation timestamp (ISO 8601)

Responses

Request samples

Content type
{
  • "number": "SHP000000001",
  • "type": "routing.shipment_barcode",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "SHP000000001",
  • "type": "routing.shipment_barcode",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Generate a tracking number

Generate a tracking number

Authorizations:
Bearer
Request Body schema:
required

The new TrackingNumber resource

number
string

The generated tracking number

type
string

Resource type

barcode
string or null

GS1-128 barcode (if applicable)

generatedAt
string

Generation timestamp (ISO 8601)

Responses

Request samples

Content type
{
  • "number": "TRK000000001",
  • "type": "routing.tracking_number",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "TRK000000001",
  • "type": "routing.tracking_number",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Preview the next tracking number

Preview the next tracking number

Authorizations:
Bearer
query Parameters
date
string <date>

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "number": "TRK000000001",
  • "type": "routing.tracking_number",
  • "barcode": "string",
  • "generatedAt": "2026-02-15T10:30:00+00:00"
}

Load Plans

A load plan — where each handling unit (Shipping package) sits on a carrier (FleetUnit) for a trip, with live consumed-vs-capacity totals.

Served from the routing_load_plan_views / routing_load_placement_views read models. One plan exists per (carrier, route).

List load plans

Paginated list of load plans, optionally filtered by route, carrier, or status.

Authorizations:
Bearer
query Parameters
routeRef
string

Filter by route reference

carrierRef
string

Filter by carrier ResourceUri (glacia:///fleet/units/{id})

status
string
Enum: "draft" "planned" "sealed" "loading" "loaded" "in_transit" "unloading" "closed"

Filter by plan status

page
integer >= 1
Default: 1

Page number

itemsPerPage
integer [ 1 .. 100 ]
Default: 20

Items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Open a load plan

Open a load plan for a carrier (FleetUnit) on a route. The carrier must have load capacity.

Authorizations:
Bearer
Request Body schema:
required

The new LoadPlan resource

carrierId
required
string <ulid>
routeId
required
string <= 255 characters

Responses

Request samples

Content type
{
  • "carrierId": "string",
  • "routeId": "string"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "carrierRef": "string",
  • "routeRef": "string",
  • "status": "draft",
  • "maxWeightKg": 0,
  • "maxVolumeM3": 0,
  • "maxPallets": 0,
  • "consumedWeightKg": 0,
  • "consumedVolumeM3": 0,
  • "consumedPallets": 0,
  • "placementCount": 0,
  • "openedAt": "string",
  • "sealedAt": "string",
  • "closedAt": "string",
  • "updatedAt": "string",
  • "placements": [
    ]
}

Get a load plan

Retrieve a single load plan with its placements and consumed totals.

Authorizations:
Bearer
path Parameters
id
required
string

LoadPlan identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "carrierRef": "string",
  • "routeRef": "string",
  • "status": "draft",
  • "maxWeightKg": 0,
  • "maxVolumeM3": 0,
  • "maxPallets": 0,
  • "consumedWeightKg": 0,
  • "consumedVolumeM3": 0,
  • "consumedPallets": 0,
  • "placementCount": 0,
  • "openedAt": "string",
  • "sealedAt": "string",
  • "closedAt": "string",
  • "updatedAt": "string",
  • "placements": [
    ]
}

Close the load plan

Close the plan — trip done (carrier empty) or plan abandoned.

Authorizations:
Bearer
path Parameters
id
required
string

LoadPlan identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "carrierRef": "string",
  • "routeRef": "string",
  • "status": "draft",
  • "maxWeightKg": 0,
  • "maxVolumeM3": 0,
  • "maxPallets": 0,
  • "consumedWeightKg": 0,
  • "consumedVolumeM3": 0,
  • "consumedPallets": 0,
  • "placementCount": 0,
  • "openedAt": "string",
  • "sealedAt": "string",
  • "closedAt": "string",
  • "updatedAt": "string",
  • "placements": [
    ]
}

Place a unit on the plan

Place a handling unit (package) on the plan. Rejected if it would exceed carrier capacity or duplicates a unit already on the plan.

Authorizations:
Bearer
path Parameters
id
required
string

LoadPlan identifier

Request Body schema:
required

The new LoadPlan resource

packageId
required
string <ulid>
loadSequence
integer >= 0
Default: 0
LoadPositionPayload (object) or null

Responses

Request samples

Content type
{
  • "packageId": "string",
  • "loadSequence": 0,
  • "position": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "carrierRef": "string",
  • "routeRef": "string",
  • "status": "draft",
  • "maxWeightKg": 0,
  • "maxVolumeM3": 0,
  • "maxPallets": 0,
  • "consumedWeightKg": 0,
  • "consumedVolumeM3": 0,
  • "consumedPallets": 0,
  • "placementCount": 0,
  • "openedAt": "string",
  • "sealedAt": "string",
  • "closedAt": "string",
  • "updatedAt": "string",
  • "placements": [
    ]
}

Remove a unit from the plan

Remove a unit from the plan (before sealing).

Authorizations:
Bearer
path Parameters
id
required
string

LoadPlan identifier

packageId
required
string

LoadPlan identifier

Responses

Reposition a placed unit

Move a placed unit to a new slot / load sequence (before sealing).

Authorizations:
Bearer
path Parameters
id
required
string

LoadPlan identifier

packageId
required
string

LoadPlan identifier

Request Body schema: application/merge-patch+json
required

The updated LoadPlan resource

loadSequence
integer >= 0
Default: 0
LoadPositionPayload (object) or null

Responses

Request samples

Content type
application/merge-patch+json
{
  • "loadSequence": 0,
  • "position": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "carrierRef": "string",
  • "routeRef": "string",
  • "status": "draft",
  • "maxWeightKg": 0,
  • "maxVolumeM3": 0,
  • "maxPallets": 0,
  • "consumedWeightKg": 0,
  • "consumedVolumeM3": 0,
  • "consumedPallets": 0,
  • "placementCount": 0,
  • "openedAt": "string",
  • "sealedAt": "string",
  • "closedAt": "string",
  • "updatedAt": "string",
  • "placements": [
    ]
}

Load a unit onto the carrier

Mark a unit physically loaded onto the carrier at the dock.

Authorizations:
Bearer
path Parameters
id
required
string

LoadPlan identifier

packageId
required
string

LoadPlan identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "carrierRef": "string",
  • "routeRef": "string",
  • "status": "draft",
  • "maxWeightKg": 0,
  • "maxVolumeM3": 0,
  • "maxPallets": 0,
  • "consumedWeightKg": 0,
  • "consumedVolumeM3": 0,
  • "consumedPallets": 0,
  • "placementCount": 0,
  • "openedAt": "string",
  • "sealedAt": "string",
  • "closedAt": "string",
  • "updatedAt": "string",
  • "placements": [
    ]
}

Unload a unit from the carrier

Mark a unit unloaded from the carrier at a stop / delivery.

Authorizations:
Bearer
path Parameters
id
required
string

LoadPlan identifier

packageId
required
string

LoadPlan identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "carrierRef": "string",
  • "routeRef": "string",
  • "status": "draft",
  • "maxWeightKg": 0,
  • "maxVolumeM3": 0,
  • "maxPallets": 0,
  • "consumedWeightKg": 0,
  • "consumedVolumeM3": 0,
  • "consumedPallets": 0,
  • "placementCount": 0,
  • "openedAt": "string",
  • "sealedAt": "string",
  • "closedAt": "string",
  • "updatedAt": "string",
  • "placements": [
    ]
}

Seal the load plan

Freeze the manifest — placements can no longer be edited; the carrier is ready to load.

Authorizations:
Bearer
path Parameters
id
required
string

LoadPlan identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "carrierRef": "string",
  • "routeRef": "string",
  • "status": "draft",
  • "maxWeightKg": 0,
  • "maxVolumeM3": 0,
  • "maxPallets": 0,
  • "consumedWeightKg": 0,
  • "consumedVolumeM3": 0,
  • "consumedPallets": 0,
  • "placementCount": 0,
  • "openedAt": "string",
  • "sealedAt": "string",
  • "closedAt": "string",
  • "updatedAt": "string",
  • "placements": [
    ]
}

Rating

Represents a client-facing service rate card containing pricing rules for route and shipment charges.

List all rate cards

Retrieve a paginated list of rate cards with optional filters.

Authorizations:
Bearer
query Parameters
crewId
string <uuid>

Filter by partner UUID

status
string
Enum: "draft" "active" "expired" "superseded"

Filter by rate card status

page
integer >= 1
Default: 1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 25

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a rate card

Create a new rate card in draft status.

Authorizations:
Bearer
Request Body schema: application/json
required

Rate card creation data

crewId
string or null <uuid>

Partner UUID (null for tenant default)

currency
required
string = 3 characters

ISO 4217 currency code

effectiveFrom
required
string <date-time>

Start of effectiveness period

effectiveTo
required
string <date-time>

End of effectiveness period

Responses

Request samples

Content type
application/json
{
  • "crewId": "3bfb64a6-7eeb-4376-b155-bfb9c0405b76",
  • "currency": "USD",
  • "effectiveFrom": "2019-08-24T14:15:22Z",
  • "effectiveTo": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "currency": "USD",
  • "effectiveFrom": "string",
  • "effectiveTo": "string",
  • "status": "draft",
  • "rules": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a rate card

Retrieve a single rate card by its UUID, including all rules.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Rate card UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "currency": "USD",
  • "effectiveFrom": "string",
  • "effectiveTo": "string",
  • "status": "draft",
  • "rules": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Activate a rate card

Activate a draft rate card. The rate card must have at least one rule.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Rate card UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "currency": "USD",
  • "effectiveFrom": "string",
  • "effectiveTo": "string",
  • "status": "draft",
  • "rules": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Add a rule to a rate card

Add a pricing rule to a draft rate card.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Rate card UUID

Request Body schema:
required

The new RateCard resource

chargeType
required
string
scope
required
string
method
required
string
amountInCents
required
integer
percentage
number or null
percentageOf
string or null
priority
integer >= 0
Default: 0
object or null

Responses

Request samples

Content type
{
  • "chargeType": "string",
  • "scope": "string",
  • "method": "string",
  • "amountInCents": 0,
  • "percentage": 0,
  • "percentageOf": "string",
  • "priority": 0,
  • "condition": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "currency": "USD",
  • "effectiveFrom": "string",
  • "effectiveTo": "string",
  • "status": "draft",
  • "rules": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Remove a rule from a rate card

Remove a pricing rule from a draft rate card by its index.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Rate card UUID

index
required
integer >= 0

Rule index (0-based)

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "crewId": "string",
  • "teamName": "string",
  • "currency": "USD",
  • "effectiveFrom": "string",
  • "effectiveTo": "string",
  • "status": "draft",
  • "rules": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

List all service rate cards

Retrieve a paginated list of service rate cards with optional filters.

Authorizations:
Bearer
query Parameters
clientId
string <uuid>

Filter by client UUID

status
string
Enum: "draft" "active" "archived"

Filter by service rate card status

page
integer >= 1
Default: 1

Page number for pagination

itemsPerPage
integer [ 1 .. 100 ]
Default: 25

Number of items per page

Responses

Response samples

Content type
{
  • "totalItems": 0,
  • "search": {
    },
  • "view": {
    },
  • "member": [
    ]
}

Create a service rate card

Create a new service rate card in draft status.

Authorizations:
Bearer
Request Body schema: application/json
required

Service rate card creation data

clientId
string or null <uuid>

Client UUID (null for tenant default)

currency
required
string = 3 characters

ISO 4217 currency code

effectiveFrom
required
string <date-time>

Start of effectiveness period

effectiveTo
required
string <date-time>

End of effectiveness period

Responses

Request samples

Content type
application/json
{
  • "clientId": "5e505642-9024-474d-9434-e5a44f505cc5",
  • "currency": "USD",
  • "effectiveFrom": "2019-08-24T14:15:22Z",
  • "effectiveTo": "2019-08-24T14:15:22Z"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "clientId": "string",
  • "clientName": "string",
  • "currency": "USD",
  • "effectiveFrom": "string",
  • "effectiveTo": "string",
  • "status": "draft",
  • "rules": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a service rate card

Retrieve a single service rate card by its UUID, including all rules.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Service rate card UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "clientId": "string",
  • "clientName": "string",
  • "currency": "USD",
  • "effectiveFrom": "string",
  • "effectiveTo": "string",
  • "status": "draft",
  • "rules": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Activate a service rate card

Activate a draft service rate card. The service rate card must have at least one rule.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Service rate card UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "clientId": "string",
  • "clientName": "string",
  • "currency": "USD",
  • "effectiveFrom": "string",
  • "effectiveTo": "string",
  • "status": "draft",
  • "rules": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Add a rule to a service rate card

Add a pricing rule to a draft service rate card.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Service rate card UUID

Request Body schema:
required

The new ServiceRateCard resource

chargeType
required
string
scope
required
string
method
required
string
amountInCents
required
integer
percentage
number or null
percentageOf
string or null
priority
integer >= 0
Default: 0
object or null

Responses

Request samples

Content type
{
  • "chargeType": "string",
  • "scope": "string",
  • "method": "string",
  • "amountInCents": 0,
  • "percentage": 0,
  • "percentageOf": "string",
  • "priority": 0,
  • "condition": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "clientId": "string",
  • "clientName": "string",
  • "currency": "USD",
  • "effectiveFrom": "string",
  • "effectiveTo": "string",
  • "status": "draft",
  • "rules": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Remove a rule from a service rate card

Remove a pricing rule from a draft service rate card by its index.

Authorizations:
Bearer
path Parameters
id
required
string <uuid>

Service rate card UUID

index
required
integer >= 0

Rule index (0-based)

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "clientId": "string",
  • "clientName": "string",
  • "currency": "USD",
  • "effectiveFrom": "string",
  • "effectiveTo": "string",
  • "status": "draft",
  • "rules": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Driver Tracking

Resource for real-time driver location tracking.

Drivers send their location updates to this endpoint during route execution. Updates are published via Mercure for real-time tracking on the dashboard.

Update driver location

Submit current driver location for real-time tracking.

Rate limiting: This endpoint is rate-limited to 1 request every 10 seconds per driver.

Real-time updates: Location updates are published via Mercure SSE to the /tracking/{driverId} topic.

Expected usage:

  • Mobile driver app sends location updates every 10-30 seconds
  • Include heading and speed when available for better tracking visualization
  • Battery level helps monitor device health during long routes
Authorizations:
Bearer
Request Body schema: application/json
optional

Driver location data

lat
required
number <float>

Latitude coordinate

lng
required
number <float>

Longitude coordinate

routeId
required
string <ulid>

Route ID being executed

timestamp
string <date-time>

When location was recorded (ISO 8601)

heading
number <float> [ 0 .. 360 ]

Compass heading in degrees

speed
number <float> >= 0

Speed in km/h

accuracy
number <float> >= 0

GPS accuracy in meters

batteryLevel
integer [ 0 .. 100 ]

Device battery percentage

Responses

Request samples

Content type
application/json
{
  • "lat": 50.8503,
  • "lng": 4.3517,
  • "routeId": "01HXY9Z8A7B6C5D4E3F2G1H0J",
  • "timestamp": "2024-01-15T10:30:00+01:00",
  • "heading": 45.5,
  • "speed": 50,
  • "accuracy": 5,
  • "batteryLevel": 85
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "driverId": "string",
  • "routeId": "string",
  • "latitude": 0,
  • "longitude": 0,
  • "heading": 0,
  • "speed": 0,
  • "accuracy": 0,
  • "batteryLevel": 0,
  • "recordedAt": "string"
}

Routing

Per-zone operational policy (config store). Keyed by the zone's opaque id. GET returns the current config or a default empty shape when none is set; PUT upserts the whole config and is gated by the routing zone-policy manage scope.

Get the operational policy for a zone

Returns the configured policy, or a default empty shape when the zone has no policy yet.

Authorizations:
Bearer
path Parameters
zoneId
required
string

ZonePolicy identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "zoneId": "string",
  • "policyId": "string",
  • "defaultTeamRef": "string",
  • "defaultCarrierRef": "string",
  • "servingDepotId": "string",
  • "overlapPriority": 0,
  • "autoAssign": false,
  • "overflowZoneRef": "string",
  • "deliveryDays": [
    ],
  • "orderCutoffs": {
    },
  • "deliveryWindows": [
    ],
  • "maxStopsPerDay": 0,
  • "maxVehicles": 0,
  • "allowedServiceLevels": [
    ],
  • "serviceLevelSlas": {
    },
  • "surcharge": {
    },
  • "rateCardRef": "string",
  • "minOrderValue": {
    },
  • "allowedVehicleTypes": [
    ],
  • "accessRestrictions": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Set or update the operational policy for a zone

Upserts the whole policy (get-or-create by tenant + zone). Requires the routing:zone-policy:manage scope.

Authorizations:
Bearer
path Parameters
zoneId
required
string

ZonePolicy identifier

Request Body schema:
required

The updated ZonePolicy resource

DispatchAssignmentInput (object) or null
ScheduleCapacityInput (object) or null
ServiceSlaInput (object) or null
CommercialAccessInput (object) or null

Responses

Request samples

Content type
{
  • "dispatch": {
    },
  • "schedule": {
    },
  • "service": {
    },
  • "commercial": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "zoneId": "string",
  • "policyId": "string",
  • "defaultTeamRef": "string",
  • "defaultCarrierRef": "string",
  • "servingDepotId": "string",
  • "overlapPriority": 0,
  • "autoAssign": false,
  • "overflowZoneRef": "string",
  • "deliveryDays": [
    ],
  • "orderCutoffs": {
    },
  • "deliveryWindows": [
    ],
  • "maxStopsPerDay": 0,
  • "maxVehicles": 0,
  • "allowedServiceLevels": [
    ],
  • "serviceLevelSlas": {
    },
  • "surcharge": {
    },
  • "rateCardRef": "string",
  • "minOrderValue": {
    },
  • "allowedVehicleTypes": [
    ],
  • "accessRestrictions": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Shipping Carriers

Represents a shipment moving through the logistics pipeline.

Shipments are assigned to routes for delivery and track the full lifecycle from creation to delivery.

Types:

  • ftl: Full Truckload — client contracts for exclusive vehicle use
  • ltl: Less Than Truckload — shared space with other shipments

Cancel a shipment's carrier label

Cancel a dispatched shipment's carrier label with the provider and void it on the shipment (clears the provider parcel id, tracking number, and label).

Authorizations:
Bearer
path Parameters
id
required
string <uuid>
Example: 01912345-6789-7abc-def0-123456789abc

Shipment UUID

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "01912345-6789-7abc-def0-123456789abc",
  • "type": "ftl",
  • "direction": "outbound",
  • "clientId": "01912345-6789-7abc-def0-123456789abc",
  • "clientName": "Riverside Retail Ltd",
  • "status": "pending",
  • "routeId": "01912345-6789-7abc-def0-123456789abc",
  • "routeCode": "ROUTE-2024-001",
  • "trackingNumber": "TRK-2024-001234",
  • "senderName": "Acme Corporation",
  • "senderAddress": "123 Business Ave, Suite 100, New York, NY 10001",
  • "recipientName": "John Smith",
  • "recipientAddress": "456 Main Street, Apt 2B, Brooklyn, NY 11201",
  • "scheduledDate": "2024-06-15",
  • "serviceLevel": "standard",
  • "carrierName": "UPS",
  • "carrierType": "ups",
  • "packageCount": 3,
  • "grossWeightGrams": 12500,
  • "declaredHandlingRequirements": "[\"fragile\", \"refrigerated\"]",
  • "effectiveHandlingRequirements": "[\"fragile\", \"refrigerated\", \"hazardous\"]",
  • "requestedDeliveryAt": "2024-06-15T17:00:00+00:00",
  • "deliverByAt": "2024-06-16T17:00:00+00:00",
  • "shipByAt": "2024-06-14T12:00:00+00:00",
  • "slaExpiresAt": "2024-06-20T00:00:00+00:00",
  • "notes": "Handle with care",
  • "billingSubject": "INV-2024-001",
  • "subject": "glacia:///sales/orders/01912345-6789-7abc-def0-123456789abc",
  • "controlMode": "unassigned",
  • "compositionMode": "standalone",
  • "deliveredAt": "2024-06-15T14:30:00+00:00",
  • "createdAt": "2024-06-10T09:00:00+00:00",
  • "updatedAt": "2024-06-15T14:30:00+00:00",
  • "returnDetails": {
    },
  • "originalShipmentId": "01912345-6789-7abc-def0-123456789abc",
  • "originalShipmentNumber": "string",
  • "podId": "01912345-6789-7abc-def0-123456789abc",
  • "requirePhoto": false,
  • "providerParcelId": "parcel_01HXYZ",
  • "labelUrl": "https://app.example.com/api/v1/storage/files/access/eyJ...",
  • "providerStatus": "in_transit",
  • "pickupCoordinates": {
    },
  • "deliveryCoordinates": {
    },
  • "label": {
    }
}