Order API

1. Connection and authorisation

Publish TrackParcel before connecting an external shop. Use TrackParcel's published HTTPS domain as WSL_BASE_URL and store the same random key of at least 32 characters as WSL_API_KEY on both servers. You can generate one with a password manager. Never include it in public code, links, logs or browser variables.

POST /api/public/shipments
Content-Type: application/json
X-API-Key: [key stored on your server]

Direct access from external browsers is not enabled. Your shop must call TrackParcel from its server after the order is placed. Maximum size: 16 KiB per request. Only one order is accepted per request.

2. Order details

Additional fields are not accepted. The order date is for information only: the simulation starts when the parcel is created in TrackParcel and is not backdated.

{
  "trackingCode": "WSL123456789GB",
  "orderDate": "2026-10-07T14:30:00+01:00",
  "customer": {
    "name": "Emma Clarke",
    "email": "emma@example.com",
    "phone": "+44 20 7946 0958"
  },
  "address": {
    "line1": "12 Example Street",
    "line2": "Flat 2B",
    "city": "Leeds",
    "postalCode": "LS1 4AP",
    "country": "GB"
  }
}

3. Sending from another site

curl example

curl --request POST "$WSL_BASE_URL/api/public/shipments" \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $WSL_API_KEY" \
  --data '{
  "trackingCode": "WSL123456789GB",
  "orderDate": "2026-10-07T14:30:00+01:00",
  "customer": {
    "name": "Emma Clarke",
    "email": "emma@example.com",
    "phone": "+44 20 7946 0958"
  },
  "address": {
    "line1": "12 Example Street",
    "line2": "Flat 2B",
    "city": "Leeds",
    "postalCode": "LS1 4AP",
    "country": "GB"
  }
}'

JavaScript · on your shop's server only

const baseUrl = process.env.WSL_BASE_URL;
const apiKey = process.env.WSL_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Set up the TrackParcel integration");

const response = await fetch(new URL("/api/public/shipments", baseUrl), {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": apiKey },
  body: JSON.stringify(order), // object in the format above
});
const result = await response.json();
if (!response.ok) {
  // Handle result.error; never log personal data or the key.
  throw new Error("Could not register the order with TrackParcel");
}
const trackingUrl = new URL(result.trackingPath, baseUrl).href;
// Include trackingUrl in your customer's order confirmation.

If the connection fails or you receive a 500 error, retry with the same code and exactly the same details, using exponential back-off. An identical retry returns 200 and keeps the original expiry. If the code already holds different details, you'll get a 409 and the recipient is not overwritten.

4. Responses

{
  "trackingCode": "WSL123456789GB",
  "created": true,
  "expiresAt": "2026-10-28T12:00:00.000Z",
  "trackingPath": "/seguimiento/WSL123456789GB",
  "simulated": true
}

Illustrative example: expiresAt is always 20 days after the order was actually received.

201 · Created

The order and its details were saved successfully.

200 · Identical retry

Already exists; retention is not extended and the journey is not restarted.

400 · Invalid data

Malformed JSON or invalid fields. Validation errors include fields with path and message, without echoing the data received.

401 · Unauthorised

The key is missing or invalid.

409 · Code in use

Different details already exist for the same code. Nothing is changed.

413 / 415

Request too large or incorrect Content-Type.

500 / 503

Temporary failure or integration not set up. A 503 also appears if the stored key is shorter than 32 characters.

5. Privacy and tracking

• Full name, email address, mobile number, delivery address and order date are kept for 20 days from first receipt, after which they are deleted automatically by a daily job.
• Expired details stop being available on tracking immediately, even before they are physically deleted. Deletion applies to live records; it does not guarantee immediate removal from hosting backups.
• The public page shows the full name, the start of the email address with its domain, the last four digits of the mobile number, town/city, postcode and order date. Anyone with the code can see these details, so avoid sharing it publicly. The street address and house or flat number are never returned on public tracking.
• The final stages of the simulation use the customer's town/city. They do not represent a real delivery or a delivery guarantee.
• Once the period ends, basic simulated tracking remains without customer details and returns to the generic route. Do not reuse codes across different orders.
• Your shop must tell the customer about this transfer and have a lawful basis under UK GDPR. Test with dummy data first and confirm TrackParcel's legal and contact details before sending real data.