Developers

A simple REST API for shipments.

Generate tracking numbers when you create a shipment, then push delivery events as your parcels move. JSON in, JSON out.

Authentication

Write endpoints require an API key sent in the x-api-key header. Configure it via the COURIER_API_KEY environment variable. The public tracking endpoint needs no key.

POST/api/v1/shipmentsAPI key required

Creates a shipment and returns a generated tracking number in the form EU########XX.

curl -X POST https://foxypost.sbs/api/v1/shipments \
  -H "x-api-key: demo-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "service": "express",
    "senderName": "ACME GmbH",
    "originCity": "Berlin",
    "originCountry": "DE",
    "recipientName": "Jane Doe",
    "destinationCity": "Amsterdam",
    "destinationCountry": "NL",
    "weightKg": 2.5,
    "estimatedDelivery": "2026-02-01"
  }'

201 Created

{
  "data": {
    "trackingNumber": "EU48213907KP",
    "status": "created",
    "service": "express",
    "events": [
      { "status": "created", "location": "Berlin, DE", "description": "..." }
    ]
  }
}
POST/api/v1/shipments/:trackingNumber/eventsAPI key required

Appends a delivery event and updates the shipment's current status. Valid statuses: picked_up, in_transit, customs, out_for_delivery, delivered, exception.

curl -X POST \
  https://foxypost.sbs/api/v1/shipments/EU48213907KP/events \
  -H "x-api-key: demo-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_transit",
    "location": "Frankfurt, DE",
    "description": "Departed sorting center",
    "timestamp": "2026-01-30T09:15:00Z"
  }'
GET/api/v1/track/:trackingNumberPublic

Returns a shipment with its full tracking history. Used by the public tracking page.

curl https://foxypost.sbs/api/v1/track/EU48213907KP

Base URL & format

All endpoints live under /api/v1. Requests and responses are JSON (UTF-8). Successful responses wrap the payload in a data field; errors return an error string.

Rate limits

The public tracking endpoint is limited to 60 requests per minute per IP. Authenticated endpoints allow 600 requests per minute per API key. Exceeding the limit returns 429 with a Retry-After header.

Status codes

200 OKRequest succeeded.
201 CreatedShipment created.
400 Bad RequestMissing or invalid fields in the body.
401 UnauthorizedMissing or invalid x-api-key header.
404 Not FoundNo shipment matches the tracking number.

Webhooks

Instead of polling, register a webhook URL and we'll POST every tracking event to your endpoint as it happens. Each delivery is signed with an X-Foxypost-Signature header you can verify with your webhook secret.

POST https://your-app.example/webhooks/foxypost
X-Foxypost-Signature: t=1706600000,v1=9f86d0818...

{
  "trackingNumber": "EU48213907KP",
  "event": {
    "status": "out_for_delivery",
    "location": "Amsterdam, NL",
    "timestamp": "2026-01-31T07:12:00Z"
  }
}

Official libraries

Thin wrappers around the REST API for the most common stacks.

Node.js

npm i @foxypost/sdk

Python

pip install foxypost

PHP

composer require foxypost/sdk

Build with the Foxypost API

Create shipments, generate tracking numbers and receive delivery events in minutes.

Request API accessTry tracking