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.

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

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

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"
}

Routing - Number Generation

Resource 'Routing - Number Generation' operations.

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"
}

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

List supported carrier providers

Returns the carrier provider registry that drives the carrier-creation picker.

Authorizations:
Bearer

Responses

Response samples

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

Check whether a provider has platform-shared credentials configured

Returns only whether a shared account is configured. The secret config is never returned.

Authorizations:
Bearer
path Parameters
type
required
string

CarrierPlatformCredential identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "type": "ups",
  • "configured": true
}

Configure a provider's platform-shared credentials

Validates the supplied credentials against the provider's credential-field schema and stores them encrypted. Write-only — the secret is never echoed back.

Authorizations:
Bearer
path Parameters
type
required
string

CarrierPlatformCredential identifier

Request Body schema:
required

The updated CarrierPlatformCredential resource

object

Provider credential config/secrets keyed by the provider's declared credential-field keys. Write-only — never returned.

Responses

Request samples

Content type
{
  • "credentials": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "type": "ups",
  • "configured": true
}

List external carriers

Retrieve a paginated list of external shipping providers.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Register an external carrier

Register an external carrier

Authorizations:
Bearer
Request Body schema:
required

The new Carrier resource

code
required
string [ 2 .. 64 ] characters
type
required
string
Default: "custom"
Enum: "ups" "dhl" "fedex" "usps" "sendcloud" "custom" "internal"
credentialScope
string or null
Value: "tenant"

Credential model — tenant (bring-your-own account) for external providers, or null for the internal/self carrier. The platform scope is excluded here on purpose (finding H4); platform carriers are provisioned out-of-band, never minted on demand through this tenant endpoint.

environment
string
Default: "sandbox"
Enum: "sandbox" "production"

Provider environment — "sandbox" (test upstream, the default) or "production" (live upstream). Opting into production is deliberate.

object

BYO provider keys/secrets/config — required only for tenant scope.

name
string or null <= 255 characters

Display name — required for the custom provider, inherited otherwise.

capabilities
Array of strings

Capabilities — custom provider only.

coverage
Array of strings

Coverage as ISO 3166-1 alpha-2 country codes — custom provider only.

Responses

Request samples

Content type
{
  • "code": "string",
  • "type": "ups",
  • "credentialScope": "tenant",
  • "environment": "sandbox",
  • "credentials": {
    },
  • "name": "string",
  • "capabilities": [
    ],
  • "coverage": [
    ]
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "UPS-PRIMARY",
  • "name": "UPS",
  • "type": "ups",
  • "isInternal": false,
  • "credentialScope": "platform",
  • "environment": "sandbox",
  • "status": "active",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get an external carrier

Get an external carrier

Authorizations:
Bearer
path Parameters
id
required
string

Carrier identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "UPS-PRIMARY",
  • "name": "UPS",
  • "type": "ups",
  • "isInternal": false,
  • "credentialScope": "platform",
  • "environment": "sandbox",
  • "status": "active",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Update an external carrier

Update an external carrier

Authorizations:
Bearer
path Parameters
id
required
string

Carrier identifier

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

The updated Carrier resource

name
string [ 2 .. 255 ] characters
type
string
Default: "custom"
Enum: "ups" "dhl" "fedex" "usps" "custom" "internal"
capabilities
Array of strings
serviceLevels
Array of strings
coverage
Array of strings
environment
string or null
Enum: "sandbox" "production"

Provider environment — "sandbox" or "production". Omit to leave unchanged.

Responses

Request samples

Content type
application/merge-patch+json
{
  • "name": "string",
  • "type": "ups",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "environment": "sandbox"
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "UPS-PRIMARY",
  • "name": "UPS",
  • "type": "ups",
  • "isInternal": false,
  • "credentialScope": "platform",
  • "environment": "sandbox",
  • "status": "active",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Activate an external carrier

Activate an external carrier

Authorizations:
Bearer
path Parameters
id
required
string

Carrier identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "UPS-PRIMARY",
  • "name": "UPS",
  • "type": "ups",
  • "isInternal": false,
  • "credentialScope": "platform",
  • "environment": "sandbox",
  • "status": "active",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

Deactivate an external carrier

Deactivate an external carrier

Authorizations:
Bearer
path Parameters
id
required
string

Carrier identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "code": "UPS-PRIMARY",
  • "name": "UPS",
  • "type": "ups",
  • "isInternal": false,
  • "credentialScope": "platform",
  • "environment": "sandbox",
  • "status": "active",
  • "capabilities": [
    ],
  • "serviceLevels": [
    ],
  • "coverage": [
    ],
  • "createdAt": "string",
  • "updatedAt": "string"
}

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": {
    }
}

Quote carrier rates for a shipment

Fetch live rate quotes for a shipment from a carrier (carrierId query parameter, required).

Authorizations:
Bearer
path Parameters
serviceLevel
required
string

CarrierRate identifier

query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Shipping Clients

A shipping client — a first-class customer that LINKS to an existing Partner (billing/contact entity) and layers shipping-specific defaults on top: preferred pickup/delivery addresses, billing terms, service level, and handling requirements.

Tenant-managed reference data. The linked partner is immutable once set.

List shipping clients

Retrieve a paginated list of shipping clients.

Authorizations:
Bearer
query Parameters
page
integer
Default: 1

The collection page number

Responses

Response samples

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

Register a shipping client for an existing partner

Register a shipping client for an existing partner

Authorizations:
Bearer
Request Body schema:
required

The new Client resource

partnerId
required
string <= 100 characters

The existing Partner this client wraps.

accountReference
string or null <= 128 characters
defaultServiceLevel
string or null
Enum: "standard" "express" "same_day" "next_day"
defaultHandlingRequirements
Array of strings
ShipmentAddressInput (object) or null
ShipmentContactInput (object) or null
ShipmentCoordinatesInput (object) or null
ShipmentAddressInput (object) or null
ShipmentContactInput (object) or null
ShipmentCoordinatesInput (object) or null
ClientBillingTermsInput (object) or null

Responses

Request samples

Content type
{
  • "partnerId": "string",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "pickupAddress": {
    },
  • "pickupContact": {
    },
  • "pickupCoordinates": {
    },
  • "deliveryAddress": {
    },
  • "deliveryContact": {
    },
  • "deliveryCoordinates": {
    },
  • "billingTerms": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "status": "active",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "defaultPickupAddress": {
    },
  • "defaultDeliveryAddress": {
    },
  • "billingTerms": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Get a shipping client

Get a shipping client

Authorizations:
Bearer
path Parameters
id
required
string

Client identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "status": "active",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "defaultPickupAddress": {
    },
  • "defaultDeliveryAddress": {
    },
  • "billingTerms": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Update a shipping client profile

Update a shipping client profile

Authorizations:
Bearer
path Parameters
id
required
string

Client identifier

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

The updated Client resource

accountReference
string or null <= 128 characters
defaultServiceLevel
string or null
Enum: "standard" "express" "same_day" "next_day"
defaultHandlingRequirements
Array of strings
ShipmentAddressInput (object) or null
ShipmentContactInput (object) or null
ShipmentCoordinatesInput (object) or null
ShipmentAddressInput (object) or null
ShipmentContactInput (object) or null
ShipmentCoordinatesInput (object) or null
ClientBillingTermsInput (object) or null

Responses

Request samples

Content type
application/merge-patch+json
{
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "pickupAddress": {
    },
  • "pickupContact": {
    },
  • "pickupCoordinates": {
    },
  • "deliveryAddress": {
    },
  • "deliveryContact": {
    },
  • "deliveryCoordinates": {
    },
  • "billingTerms": {
    }
}

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "status": "active",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "defaultPickupAddress": {
    },
  • "defaultDeliveryAddress": {
    },
  • "billingTerms": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Activate a shipping client

Activate a shipping client

Authorizations:
Bearer
path Parameters
id
required
string

Client identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "status": "active",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "defaultPickupAddress": {
    },
  • "defaultDeliveryAddress": {
    },
  • "billingTerms": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}

Deactivate a shipping client

Deactivate a shipping client

Authorizations:
Bearer
path Parameters
id
required
string

Client identifier

Responses

Response samples

Content type
{
  • "@context": "string",
  • "@id": "string",
  • "@type": "string",
  • "id": "string",
  • "partnerId": "string",
  • "partnerName": "Acme Corp",
  • "status": "active",
  • "accountReference": "string",
  • "defaultServiceLevel": "standard",
  • "defaultHandlingRequirements": [
    ],
  • "defaultPickupAddress": {
    },
  • "defaultDeliveryAddress": {
    },
  • "billingTerms": {
    },
  • "createdAt": "string",
  • "updatedAt": "string"
}