POSTX Shipping API

Base URL

All API requests are made to the following base URL. Resource paths shown throughout this document (for example /consignments) are relative to it.

https://api.postx.ai/v1/shipping

Getting started

Three steps to make your first consignment booking.

1. 1

   Get your credentials

   Contact POSTX to receive your Client ID and Client Secret. Keep these private — they grant full API access to your account.

2. 2

   Obtain an access token

   Exchange your credentials for a JWT token using the token endpoint below.

3. 3

   Create your first consignment

   Use the token in the Authorization header to POST a consignment. You will receive a reference ID and a Base64 shipping label.

Integration workflow

End to end, an integration touches five things: your credentials, a created consignment, its shipping label, its tracking link, and the POSTX platform for anything after booking.

1. 1

   Authenticate

   Exchange your Client ID and Client Secret for a Bearer token. See Authentication.

2. 2

   Create a consignment

   POST the booking. The response includes a reference ID and a Base64 shipping label. See Create Consignment.

3. 3

   Retrieve the label

   Decode the label from the create response and print it. There is currently no separate endpoint to fetch it again later, so persist it on receipt.

4. 4

   Track the delivery

   Call Tracking with the reference to get a tracking URL once the driver has been dispatched.

5. 5

   Manage on the POSTX platform

   For anything after booking — shipment history, label printing, delivery progress, billing and support — use the POSTX platform. See POSTX platform.

Authentication

The POSTX API uses a Basic credential exchange. You Base64-encode your Client ID and Client Secret and pass them as a Basic Authorization header; the response is a JWT access token, which you then pass on every subsequent request as a Bearer token.

1 — Get an Access Token

Encode your clientId:clientSecret in Base64 and pass it as a Basic Authorization header:

curl -X POST https://api.postx.ai/v1/shipping/oauth/token \
  -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
  -H "Content-Type: application/json"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400
}

expires_in is in seconds. 86400 seconds = 24 hours — access tokens are valid for 24 hours.

2 — Use the Token

Include the token in every subsequent API request:

curl -X POST https://api.postx.ai/v1/shipping/consignments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Consignments

A consignment is a complete shipping job — it includes pickup location, delivery location, timing, and one or more physical items (shipments). Upon creation, you receive a unique reference ID and a printable shipping label.

Create Consignment

Request body

Address object

Shipment object

Pricing for this request

Price is determined by two things: the rate card attached to your account, and the service type you book. The rate card determines which service types are available to your account; the service type determines the price. All amounts on this page are in pence, GBP, net of VAT.

Four price fields are sent on every request: productPrice and productOverweightPrice per shipment, plus collectionServicePrice and deliveryServicePrice at the consignment level.

Two pricing modes exist, and they can be mixed within a single consignment:

• POSTX rate card — leave the line for POSTX to price from your agreed rate card. A price you send as a POSTX-rated line is checked against the rate card and corrected if it does not match.
• Customer external price — send your own hard-coded price for external comparison. This is recorded as given and is not corrected.

Worked example — a two-unit line at 7500 pence per unit, plus service leg prices:

productPrice:               7500   (pence, per unit)
quantity:                       2
────────────────────────────────
Line total:                 15000   (7500 × 2)

+ collectionServicePrice:     500
+ deliveryServicePrice:       800
────────────────────────────────
Consignment total:          16300   (pence, net of VAT)

collectionServicePrice and deliveryServicePrice live on the consignment, not on each shipment — they are charged once per consignment no matter how many entries are in shipments. A second shipment adds only its own line total:

Shipment 1 — productPrice 7500 × quantity 2:      15000
Shipment 2 — productPrice 3200 × quantity 1:       3200
────────────────────────────────────────────────────────
Shipment lines total:                              18200

+ collectionServicePrice (once, not per shipment):   500
+ deliveryServicePrice (once, not per shipment):     800
────────────────────────────────────────────────────────
Consignment total:                                 19500   (pence, net of VAT)

Example request

{
  "collectionDateTime": "2026-09-01T09:00:00",
  "collectionAddress": {
    "addressLine1": "10 Industrial Park",
    "addressLine2": "Unit 4",
    "town": "Birmingham",
    "country": "United Kingdom",
    "countryCode": "UK",
    "postcode": "B1 1AA"
  },
  "collectionContact": {
    "name": "Jane Smith",
    "email": "jane@acme.com",
    "contactNumber": "07700900000",
    "company": "Acme Ltd"
  },
  "collectionInstructions": "Ring bell on arrival",
  "collectionServiceType": "PALLET_NEXT_DAY_COLLECTION_STANDARD_ETA",
  "collectionServicePrice": 500,
  "deliveryDateTime": "2026-09-02T10:00:00",
  "deliveryAddress": {
    "addressLine1": "5 High Street",
    "addressLine2": "",
    "town": "London",
    "country": "United Kingdom",
    "countryCode": "UK",
    "postcode": "EC1A 1BB"
  },
  "deliveryContact": {
    "name": "John Doe",
    "email": "john@recipient.com",
    "contactNumber": "07700911111",
    "company": "Recipient Co"
  },
  "deliveryInstructions": "Pump truck required",
  "deliveryServiceType": "PALLET_NEXT_DAY_DELIVERY_AM",
  "deliveryServicePrice": 800,
  "shipments": [
    {
      "reference": 1032964,
      "product": "PALLET_NEXT_DAY_NATIONAL",
      "quantity": 2,
      "weightPerProduct": 221,
      "description": "Industrial equipment",
      "adr": false,
      "valuePerProduct": 350000,
      "productPrice": 7500,
      "productOverweightPrice": 0,
      "heightPerProduct": 1.2,
      "widthPerProduct": 1.0,
      "lengthPerProduct": 1.0
    }
  ]
}

Response

{
  "id": "AB12-XY34",
  "label": "JVBERi0xLjMKJeLjz9MKNSAwIG9iagol..."
}

Update Consignment

The request body is identical to Create Consignment. The original consignment is automatically cancelled (no cancellation charge is applied) and a new consignment is created. A new shipping label is returned.

Response

{
  "id": "CD34-ZA56",
  "label": "JVBERi0xLjMKJeLjz9MKNSAwIG9iagol..."
}

Cancel Consignment

Pass the consignment reference in the URL path:

curl -X DELETE https://api.postx.ai/v1/shipping/consignments/AB12-XY34 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "cancelled": "2026-09-01T08:45:00.000Z",
  "status": "CANCELLED"
}

Tracking

This endpoint is publicly accessible — no auth token is required. It returns a tracking URL that can be shared directly with recipients.

curl https://api.postx.ai/v1/shipping/tracking/AB12-XY34

Response

{
  "trackingUrl": "https://tracking.kosmo.delivery/tracking/KSM-ABC123"
}

Capacity

Query parameters

curl "https://api.postx.ai/v1/shipping/capacity?date=2026-09-02&type=pallets" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response

{
  "data": [
    { "slot": "AM", "available": 12, "total": 20 },
    { "slot": "PM", "available": 3,  "total": 20 }
  ]
}

Service Types

Service types control the collection and delivery time windows. All values below are next-day. Same-day service types do not exist yet — see Additional functionality.

Collection service types

Delivery service types

Products & Pallets

The product field on each shipment specifies the type of item being transported. Weight brackets for parcels are automatically resolved server-side. Next-day products only — same-day products do not exist yet, see Additional functionality.

Pricing

Price is determined by the rate card and the service type. The rate card sets which service types are available to your account; the service type sets the price. See the full explanation, field breakdown and worked example in Create Consignment → Pricing for this request.

Business Rules

The API enforces the following rules on every consignment:

Errors and recovery

All errors follow a consistent JSON structure:

{
  "statusCode": 400,
  "message": "collectionDateTime must not be in the past.",
  "error": "Bad Request"
}

POSTX platform

This document covers the Shipping API only. Booking through the API is one way in — your team can also use the separate POSTX operations platform for day-to-day work on shipments already created, including shipment history, label printing, delivery progress, managing shipments, billing information and support.

Additional functionality

This is functionality the POSTX Shipping API will have. Each item below is tagged with its current availability so you can plan your integration around it without building against something before it ships.