Twyft Developer API

Published surface

The only accepted service slugs are iom-nextday and iom-uk-standard. iom-nextday is IM→IM; iom-uk-standard is IM→ordinary GB. Northern Ireland, Channel Islands, IM-as-GB and other international creation are unavailable.

• Quotes return an available price in integer GBP pence or a truthful unavailable outcome, without creating effects.
• Lists use limit 1–100 (default 50) and zero-based offset, with optional status and clientRef.
• Creation requires Idempotency-Key. Omitted/false confirm creates a draft. True requests prepaid or separately approved account-credit confirmation and may return confirmed, credit hold, insufficient balance, or confirmation unavailable.
• Replay the identical validated request and key to receive the same result without duplicate shipment, financial, provider, or operational effects. Different input with that key returns 409.
• Poll owned shipment detail for status. Download a PDF only when labelAvailable is true; otherwise label retrieval returns 409 label_not_ready.

Requests and constraints

POST /quotes

POST /shipments

If collectionDate is omitted, Twyft resolves the next eligible Isle of Man collection date. A supplied date must be a real calendar date; an unavailable date produces the documented unavailable/validation outcome rather than an unexplained substitution.

Before using confirm: true, choose Prepay Balance on Account → API Keys → Payment Method and fund the balance, or have Twyft approve account credit and select it there. Insufficient prepay returns 402; no usable approved funding returns 409. A credit hold is not a confirmed shipment. Saved-card execution is not supported.

GET /shipments

GET detail and label

Responses and vocabulary

Shipment statuses: draft · credit_hold · pending · confirmed · collected · at_depot · in_transit · out_for_delivery · delivered · failed · cancelled · written_off

Quote responses distinguish available prices from unavailable reasons. Creation returns draft, confirmed with prepaid or account_credit funding, or credit hold. Representative contract responses:

{
  "quoteAvailable": {
    "outcome": "available",
    "service": "iom-nextday",
    "price": {
      "currency": "GBP",
      "amountPence": 1295
    }
  },
  "quoteUnavailable": {
    "outcome": "unavailable",
    "reasonCode": "route_unavailable",
    "message": "The selected route is unavailable."
  },
  "draft": {
    "outcome": "draft",
    "shipment": {
      "ref": "shp_demo_0001",
      "clientRef": "ORDER-DEMO-1",
      "service": "iom-nextday",
      "status": "draft",
      "createdAt": "2026-01-15T10:00:00Z",
      "sender": {
        "name": "Example Sender",
        "email": "sender@example.invalid",
        "addressLine1": "1 Example Street",
        "town": "Douglas",
        "postcode": "IM1 1AA",
        "country": "IM"
      },
      "recipient": {
        "name": "Example Recipient",
        "addressLine1": "2 Sample Road",
        "town": "Douglas",
        "postcode": "IM2 2BB",
        "country": "IM"
      },
      "parcel": {
        "weightKg": 1,
        "lengthCm": 20,
        "widthCm": 15,
        "heightCm": 10
      },
      "price": null,
      "tracking": [
        {
          "status": "pending",
          "occurredAt": "2026-01-15T10:00:00Z",
          "description": "Draft created"
        }
      ],
      "labelAvailable": false,
      "carrierRef": null
    }
  },
  "confirmedPrepaid": {
    "outcome": "confirmed",
    "funding": "prepaid",
    "shipment": {
      "ref": "shp_demo_0002",
      "clientRef": "ORDER-DEMO-2",
      "service": "iom-nextday",
      "status": "confirmed",
      "createdAt": "2026-01-15T10:05:00Z",
      "sender": {
        "name": "Example Sender",
        "email": "sender@example.invalid",
        "addressLine1": "1 Example Street",
        "town": "Douglas",
        "postcode": "IM1 1AA",
        "country": "IM"
      },
      "recipient": {
        "name": "Example Recipient",
        "addressLine1": "2 Sample Road",
        "town": "Douglas",
        "postcode": "IM2 2BB",
        "country": "IM"
      },
      "parcel": {
        "weightKg": 1,
        "lengthCm": 20,
        "widthCm": 15,
        "heightCm": 10
      },
      "price": {
        "currency": "GBP",
        "amountPence": 1295
      },
      "tracking": [
        {
          "status": "confirmed",
          "occurredAt": "2026-01-15T10:05:00Z",
          "description": "Booking confirmed"
        }
      ],
      "labelAvailable": false,
      "carrierRef": null
    }
  },
  "confirmedAccountCredit": {
    "outcome": "confirmed",
    "funding": "account_credit",
    "shipment": {
      "ref": "shp_demo_0002",
      "clientRef": "ORDER-DEMO-2",
      "service": "iom-nextday",
      "status": "confirmed",
      "createdAt": "2026-01-15T10:05:00Z",
      "sender": {
        "name": "Example Sender",
        "email": "sender@example.invalid",
        "addressLine1": "1 Example Street",
        "town": "Douglas",
        "postcode": "IM1 1AA",
        "country": "IM"
      },
      "recipient": {
        "name": "Example Recipient",
        "addressLine1": "2 Sample Road",
        "town": "Douglas",
        "postcode": "IM2 2BB",
        "country": "IM"
      },
      "parcel": {
        "weightKg": 1,
        "lengthCm": 20,
        "widthCm": 15,
        "heightCm": 10
      },
      "price": {
        "currency": "GBP",
        "amountPence": 1295
      },
      "tracking": [
        {
          "status": "confirmed",
          "occurredAt": "2026-01-15T10:05:00Z",
          "description": "Booking confirmed"
        }
      ],
      "labelAvailable": false,
      "carrierRef": null
    }
  },
  "creditHold": {
    "outcome": "credit_hold",
    "shipment": {
      "ref": "shp_demo_0003",
      "clientRef": "ORDER-DEMO-3",
      "service": "iom-nextday",
      "status": "credit_hold",
      "createdAt": "2026-01-15T10:10:00Z",
      "sender": {
        "name": "Example Sender",
        "email": "sender@example.invalid",
        "addressLine1": "1 Example Street",
        "town": "Douglas",
        "postcode": "IM1 1AA",
        "country": "IM"
      },
      "recipient": {
        "name": "Example Recipient",
        "addressLine1": "2 Sample Road",
        "town": "Douglas",
        "postcode": "IM2 2BB",
        "country": "IM"
      },
      "parcel": {
        "weightKg": 1,
        "lengthCm": 20,
        "widthCm": 15,
        "heightCm": 10
      },
      "price": null,
      "tracking": [],
      "labelAvailable": false,
      "carrierRef": null
    }
  }
}

Executable end-to-end example

The creation response supplies SHIPMENT_REF for every later command. A confirmed request requires a funded prepay balance or separately approved account credit.

#!/usr/bin/env bash
set -euo pipefail
export BASE_URL="https://twyft.im/api/v1" # use https://shadow.twyft.im/api/v1 for acceptance
export API_KEY="twft_replace_with_the_once_displayed_secret"

curl --fail-with-body -sS "$BASE_URL/quotes" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"service":"iom-nextday","origin":{"country":"IM","postcode":"IM1 1AA"},"destination":{"country":"IM","postcode":"IM2 2BB"},"parcel":{"weightKg":1,"lengthCm":20,"widthCm":15,"heightCm":10}}' | jq .
curl --fail-with-body -sS "$BASE_URL/quotes" \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"service":"iom-uk-standard","origin":{"country":"IM","postcode":"IM1 1AA"},"destination":{"country":"GB","postcode":"M1 1AE"},"parcel":{"weightKg":1,"lengthCm":20,"widthCm":15,"heightCm":10}}' | jq .

export IDEMPOTENCY_KEY="order-demo-001"
export CREATE_BODY='{"service":"iom-nextday","sender":{"name":"Example Sender","email":"sender@example.com","addressLine1":"1 Example Street","town":"Douglas","postcode":"IM1 1AA","country":"IM"},"recipient":{"name":"Example Recipient","addressLine1":"2 Sample Road","town":"Douglas","postcode":"IM2 2BB","country":"IM"},"parcel":{"weightKg":1,"lengthCm":20,"widthCm":15,"heightCm":10,"contents":"Documents"},"clientRef":"ORDER-DEMO-001","confirm":true}'
CREATE_RESPONSE=$(curl --fail-with-body -sS "$BASE_URL/shipments" \
  -H "Authorization: Bearer $API_KEY" -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" -d "$CREATE_BODY")
printf '%s\n' "$CREATE_RESPONSE" | jq .
SHIPMENT_REF=$(printf '%s' "$CREATE_RESPONSE" | jq -er '.shipment.ref | select(type == "string" and length > 0)')
export SHIPMENT_REF

# Identical replay preserves the exact body and key.
curl --fail-with-body -sS "$BASE_URL/shipments" \
  -H "Authorization: Bearer $API_KEY" -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" -d "$CREATE_BODY" | jq .
curl --fail-with-body -sS "$BASE_URL/shipments?limit=50&offset=0" -H "Authorization: Bearer $API_KEY" | jq .
DETAIL_RESPONSE=$(curl --fail-with-body -sS "$BASE_URL/shipments/$SHIPMENT_REF" -H "Authorization: Bearer $API_KEY")
printf '%s\n' "$DETAIL_RESPONSE" | jq .

LABEL_AVAILABLE=$(printf '%s' "$DETAIL_RESPONSE" | jq -r 'if (.labelAvailable | type) == "boolean" then .labelAvailable else error("labelAvailable must be a boolean") end')
if [[ "$LABEL_AVAILABLE" == "true" ]]; then
  curl --fail-with-body -sS "$BASE_URL/shipments/$SHIPMENT_REF/label" \
    -H "Authorization: Bearer $API_KEY" -o "$SHIPMENT_REF.pdf"
else
  printf 'PENDING: label is not yet available for %s\n' "$SHIPMENT_REF" >&2
fi