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

Quickstart

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.

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

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: pricePerProduct and overweightPricePerProduct 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:

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

+ collectionServicePrice:     500
+ deliveryServicePrice:       800
────────────────────────────────
Consignment total:          16300   (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,
      "pricePerProduct": 7500,
      "overweightPricePerProduct": 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/consignments/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 Coming soon.

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 Coming soon.

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.

Business Rules

The API enforces the following rules on every consignment:

Error Reference

All errors follow a consistent JSON structure:

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

Coming Soon

None of the items below exist in the API today. They are listed here — not left as a silent gap — so integrators can plan around them instead of assuming the API is unfinished or hunting for something that has not been built yet.

Same-day

Same-day is not yet implemented as a service type, despite appearing on older versions of this page. When it ships, it will be booked by service type (not a separate product SKU) and the SAME_DAY collection and delivery enum values will mirror the next-day ones shown in Service Types — the only differences will be price, and collection and delivery falling on the same day.