Parcelpoint is one API for sending parcels with any of the carriers we support. You describe the parcel and where it is going; we buy the label, hand you a PDF, and tell you where the parcel is until it arrives.
Almost everything you do is one of three things:
Every request goes to one host. The version is part of the path, so an old integration keeps working when we release a new one.
https://api.parcelpoint.example/v3
Version 3 is current. Version 2 keeps working until 31 March 2027, and every response from it carries a Parcelpoint-Sunset header with that date.
Your account has two sets of keys. Test keys create real-looking shipments that never reach a carrier, so you can build and run your tests without buying labels.
| Feature | Test mode | Live mode |
|---|---|---|
| Key starts with | pp_test_ | pp_live_ |
| Labels | Marked "SAMPLE", not valid for posting | Real, charged to your account |
| Tracking events | Simulated over 10 minutes | From the carrier, as it scans |
| Rate limit | 25 requests a second | 100 requests a second |
New here? The quickstart takes you from a test key to a printed sample label in about ten minutes.
Create your first shipment in test mode, download its label and watch it move. You need a Parcelpoint account and a terminal; the examples use cURL, Node.js 20 or Python 3.11.
In the dashboard, open Developers, then API keys, and copy the key that starts with pp_test_. Put it in an environment variable so it stays out of your code:
export PARCELPOINT_KEY="pp_test_4f9a2c71e8b3d605"
Send where the parcel is going and what it weighs. Pick your language; the choice follows you to every example on the site.
curl https://api.parcelpoint.example/v3/shipments \
-H "Authorization: Bearer $PARCELPOINT_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": { "name": "Ada Okafor", "line1": "12 Harbour Row", "city": "Portwell", "postcode": "PW1 4RT", "country": "GB" },
"parcel": { "weight_g": 850, "length_cm": 30, "width_cm": 20, "height_cm": 8 },
"service": "cheapest"
}'
const res = await fetch("https://api.parcelpoint.example/v3/shipments", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PARCELPOINT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
to: { name: "Ada Okafor", line1: "12 Harbour Row", city: "Portwell", postcode: "PW1 4RT", country: "GB" },
parcel: { weight_g: 850, length_cm: 30, width_cm: 20, height_cm: 8 },
service: "cheapest"
})
});
const shipment = await res.json();
console.log(shipment.id, shipment.label_url);
import os
import requests
res = requests.post(
"https://api.parcelpoint.example/v3/shipments",
headers={"Authorization": f"Bearer {os.environ['PARCELPOINT_KEY']}"},
json={
"to": {"name": "Ada Okafor", "line1": "12 Harbour Row", "city": "Portwell", "postcode": "PW1 4RT", "country": "GB"},
"parcel": {"weight_g": 850, "length_cm": 30, "width_cm": 20, "height_cm": 8},
"service": "cheapest",
},
)
shipment = res.json()
print(shipment["id"], shipment["label_url"])
The sender address comes from your account settings unless you pass from. The response is the new shipment:
{
"id": "shp_7Hq2Lk9Xw3",
"status": "label_ready",
"carrier": "Swiftpost",
"service": "Swiftpost 48",
"price": { "amount": 412, "currency": "GBP" },
"tracking_number": "SP204811937GB",
"label_url": "https://files.parcelpoint.example/labels/shp_7Hq2Lk9Xw3.pdf",
"test": true
}
Open label_url. In test mode the label says "SAMPLE" across it, so a carrier will not accept it. Labels are kept for 90 days.
To get A4 instead of 4 by 6 inch, add "label_format": "a4" when you create the shipment.
In test mode the parcel is scanned in, sent out and delivered over ten minutes. Fetch it again to see the latest status, or set up a webhook to be told as it happens.
curl https://api.parcelpoint.example/v3/shipments/shp_7Hq2Lk9Xw3 \
-H "Authorization: Bearer $PARCELPOINT_KEY"
const res = await fetch("https://api.parcelpoint.example/v3/shipments/shp_7Hq2Lk9Xw3", {
headers: { Authorization: `Bearer ${process.env.PARCELPOINT_KEY}` }
});
console.log((await res.json()).status);
res = requests.get(
"https://api.parcelpoint.example/v3/shipments/shp_7Hq2Lk9Xw3",
headers={"Authorization": f"Bearer {os.environ['PARCELPOINT_KEY']}"},
)
print(res.json()["status"])
Going live is a change of key. Swap pp_test_ for pp_live_, and labels become real and charged.
Every request carries a secret key in the Authorization header. The key says which account the request is for and whether it is a test.
Find them in the dashboard under Developers, then API keys. Each account has one test key and one live key to begin with, and you can add up to ten more of each, named after what uses them.
Authorization: Bearer pp_live_9c1e7b40a2f6d853
Never use a secret key in a browser or a mobile app. Anyone can read it there and buy labels on your account. Call Parcelpoint from your own server instead.
Roll a key from the dashboard when someone who knew it leaves, or once a year. The old key keeps working for 24 hours so you can deploy the new one without downtime.
A missing, malformed or revoked key gets a 401 with the code unauthorized. A live key used on a test-only feature gets a 403. See error codes.
A webhook is a URL on your server that Parcelpoint calls when something happens to a shipment. It saves you asking again and again whether a parcel has moved.
Register the URL and the events you want. You can have up to 16 endpoints, each with its own events.
curl https://api.parcelpoint.example/v3/webhooks \
-H "Authorization: Bearer $PARCELPOINT_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://shop.example/hooks/parcelpoint", "events": ["parcel.delivered", "parcel.exception"] }'
await fetch("https://api.parcelpoint.example/v3/webhooks", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.PARCELPOINT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
url: "https://shop.example/hooks/parcelpoint",
events: ["parcel.delivered", "parcel.exception"]
})
});
requests.post(
"https://api.parcelpoint.example/v3/webhooks",
headers={"Authorization": f"Bearer {os.environ['PARCELPOINT_KEY']}"},
json={
"url": "https://shop.example/hooks/parcelpoint",
"events": ["parcel.delivered", "parcel.exception"],
},
)
The response includes a secret starting whsec_. It is shown once; store it with your other secrets.
| Event | Sent when |
|---|---|
shipment.created | A shipment is created, before the label is ready. |
label.ready | The label PDF can be downloaded. |
parcel.in_transit | The carrier has scanned the parcel in. |
parcel.out_for_delivery | The parcel is on the van for delivery today. |
parcel.delivered | The carrier has recorded a delivery, with a photo if it took one. |
parcel.exception | Something needs attention: a failed delivery, damage, or a bad address. |
Every call carries a Parcelpoint-Signature header: a timestamp and an HMAC-SHA256 of the timestamp and the raw body, signed with your endpoint's secret. Reject the call if the signature does not match or the timestamp is more than five minutes old.
# The header looks like this. Verify it in your server code.
Parcelpoint-Signature: t=1789207384,v1=5f0c2a9e41b7d3...
import crypto from "node:crypto";
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const age = Date.now() / 1000 - Number(parts.t);
if (age > 300) return false; // older than five minutes
const expected = crypto
.createHmac("sha256", secret)
.update(`${parts.t}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
import hashlib, hmac, time
def verify(raw_body, header, secret):
parts = dict(p.split("=", 1) for p in header.split(","))
if time.time() - int(parts["t"]) > 300: # older than five minutes
return False
signed = f"{parts['t']}.{raw_body}".encode()
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
Use the raw body. If your framework parses the JSON first and you sign the re-serialised text, the signature will not match.
Answer with any 2xx status within ten seconds. Anything else counts as a failure, and we try again after 1 minute, 10 minutes, 1 hour, 6 hours and 24 hours. After the fifth failure the endpoint is paused and we email your developer contacts.
The same event can arrive twice. Each one has an id starting evt_; skip any you have already handled.
A shipment is one parcel going from one address to another. Creating it buys the label.
POST/v3/shipments
Returns 201 and the shipment. In live mode your account is charged when the label is ready.
| Field | Type | Description |
|---|---|---|
to Required | address | Where the parcel is going. name, line1, city, postcode and a two-letter country. |
parcel Required | object | Weight in grams, and length, width and height in centimetres. |
from | address | Where it is collected. Defaults to the address on your account. |
service | string | cheapest, fastest, or a service code from the rates list. Defaults to cheapest. |
deliver_by | date | The latest acceptable delivery date. Services that cannot make it are skipped. |
label_format | string | 4x6 or a4. Defaults to 4x6. |
reference | string | Your order number, up to 40 characters. Printed on the label. |
{
"id": "shp_7Hq2Lk9Xw3",
"status": "label_ready",
"carrier": "Swiftpost",
"service": "Swiftpost 48",
"deliver_by": "2026-09-24",
"price": { "amount": 412, "currency": "GBP" },
"tracking_number": "SP204811937GB",
"label_url": "https://files.parcelpoint.example/labels/shp_7Hq2Lk9Xw3.pdf",
"reference": "ORD-10492",
"created_at": "2026-09-22T09:41:07Z",
"test": false
}
Prices are in the smallest unit of the currency: 412 is £4.12.
GET/v3/shipments/{id}
Returns the shipment with its latest status and an events list, newest first.
| Status | Meaning |
|---|---|
created | Accepted, label not ready yet. Usually lasts under two seconds. |
label_ready | The label can be printed. The carrier has not seen the parcel. |
in_transit | Scanned by the carrier at least once. |
delivered | Delivered. Final. |
exception | Stopped; see the latest event for why. |
cancelled | Cancelled before the first scan and refunded. Final. |
POST/v3/shipments/{id}/cancel
Works until the carrier's first scan. The label stops being valid and the price is refunded to your balance within a day. After the first scan you get a 409 with the code already_in_transit.
Errors use ordinary HTTP status codes, and the body always says what went wrong in the same shape, so your code can handle them in one place.
{
"error": {
"code": "address_unverified",
"message": "We could not find PW1 9ZZ in Portwell.",
"field": "to.postcode",
"request_id": "req_3Nf8Qa1Vt6"
}
}
Show message to people if it helps them fix their input; it is written to be read. Branch on code, never on the message text. Quote request_id when you contact support.
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_request | A field is missing or the wrong type. field says which. |
| 401 | unauthorized | Check the key is present, whole and not revoked. |
| 404 | not_found | The id does not exist, or belongs to the other mode. |
| 409 | already_in_transit | Too late to cancel. Arrange a return instead. |
| 422 | address_unverified | Ask the customer to check the address. |
| 429 | rate_limited | Wait for Retry-After seconds, then try again. |
| 500 | server_error | Our fault. Retry with the same idempotency key. |
Live keys can make 100 requests a second and test keys 25. Every response tells you where you stand:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 37
Retry-After: 2
Retry-After only appears on a 429. Spread large batches out rather than sending them at once; the limit is per account, not per key.
Send an Idempotency-Key header with any POST. If the same key arrives again within 24 hours, you get the first response back instead of a second label. Use your order number, or a random UUID stored with the order.
Back off. Wait 1, 2, then 4 seconds between retries, with a little randomness, and give up after five tries.
Changes to the API, newest first. Nothing here breaks version 3; breaking changes wait for version 4.
deliver_by on shipments. Services that cannot make the date are skipped.parcel.delivered, where the carrier takes one.field on errors, pointing at the input that failed.parcel.exception was sometimes sent twice for one scan.Parcelpoint-Sunset header.