[Parcelly] Shipping API: Reference
API version | [v1 (current)] |
Production base URL | [https://api.parcelly.example/v1] |
Sandbox base URL | [https://sandbox.api.parcelly.example/v1] |
Format | [JSON over HTTPS; UTF-8] |
Support | [developers@parcelly.example; status page: status.parcelly.example] |
Last updated | [1 December 2026] |
1. Overview
[The Parcelly API lets you get shipping rates, create shipments and labels, track parcels and receive status updates by webhook. All requests must use HTTPS. Timestamps are ISO 8601 in UTC; amounts are in minor units (cents) with an ISO 4217 currency code.]
2. Quick start
[Create a sandbox account and copy your test API key from Dashboard > Developers.]
[Call GET /rates with a test origin and destination to check your key works.]
[Create a test shipment with POST /shipments and download the label from the label_url in the response.]
[Register a webhook endpoint to receive tracking updates.]
[When ready, switch to your live key and the production base URL.]
3. Authentication
[Authenticate with an API key sent as a bearer token in the Authorization header. Keys starting "sk_test_" work only in the sandbox; keys starting "sk_live_" work only in production. Keep keys secret and server-side; never embed them in mobile apps or browser code.]
Header | Value | Required |
|---|---|---|
Authorization | [Bearer sk_live_51Hx...] | [Yes] |
Content-Type | [application/json] | [For POST and PATCH] |
Idempotency-Key | [A unique value per create request, e.g. a UUID] | [Recommended for POST] |
Parcelly-Version | [2026-10-01] | [Optional: pins behaviour to a dated version] |
4. Conventions
4.1 Versioning
[The major version is in the URL (/v1). Backward-compatible changes (new endpoints, new optional fields, new enum values) can be added at any time; build clients to ignore unknown fields. Breaking changes ship in a new major version with at least 12 months’ notice.]
4.2 Rate limits
[Each key may make 100 requests per second in production and 25 in the sandbox. Every response includes the headers X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Exceeding the limit returns 429; retry after the number of seconds in the Retry-After header.]
4.3 Pagination
[List endpoints use cursor pagination. Pass limit (1–100, default 25) and starting_after (the ID of the last item you received). The response includes has_more.]
4.4 Idempotency
[Send an Idempotency-Key header with every POST that creates a resource. Keys are kept for 24 hours; repeating a request with the same key returns the original response with the header Idempotent-Replayed: true.]
5. Endpoint summary
Method | Path | Description |
|---|---|---|
GET | /rates | [Get available services and prices for a parcel] |
POST | /shipments | [Create a shipment and purchase a label] |
GET | /shipments/{shipment_id} | [Retrieve a shipment] |
GET | /shipments | [List shipments, filtered by status or date] |
POST | /shipments/{shipment_id}/cancel | [Cancel a shipment and refund the label] |
GET | /tracking/{tracking_number} | [Get tracking events for a parcel] |
POST | /webhook_endpoints | [Register a webhook endpoint] |
6. Endpoint reference
6.1 Create a shipment
POST /shipments
[Creates a shipment, purchases a label for the chosen service and returns the label URL and tracking number.]
Body parameters
Field | Type | Required | Description |
|---|---|---|---|
service | string | Yes | [Service code from GET /rates, e.g. "next_day"] |
from_address | object | Yes | [Sender address: name, line1, line2, city, postal_code, country (ISO 3166-1 alpha-2), phone] |
to_address | object | Yes | [Recipient address, same fields; email optional for delivery notifications] |
parcel | object | Yes | [weight_grams (integer), length_cm, width_cm, height_cm] |
reference | string | No | [Your order reference, max 50 characters; shown on the label] |
label_format | string | No | ["pdf" (default), "png" or "zpl"] |
Example request
POST https://api.parcelly.example/v1/shipments with headers Authorization: Bearer sk_test_4eC39Hq, Idempotency-Key: 7f1c2d9e-0b4a-4f61-9a55-2c8e3b6d1f20
{"service": "next_day", "reference": "ORD-104822", "from_address": {"name": "Fernhill Outdoor Gear", "line1": "Unit 4, Riverside Park", "city": "Leeds", "postal_code": "LS10 1AB", "country": "GB"}, "to_address": {"name": "Sam Carter", "line1": "12 Elm Road", "city": "York", "postal_code": "YO10 3DD", "country": "GB", "email": "sam@example.com"}, "parcel": {"weight_grams": 1850, "length_cm": 40, "width_cm": 30, "height_cm": 12}}
Example response (201 Created)
{"id": "shp_9QwX2kLm", "status": "label_created", "service": "next_day", "tracking_number": "PC7730918842GB", "label_url": "https://files.parcelly.example/labels/shp_9QwX2kLm.pdf", "price": {"amount": 645, "currency": "GBP"}, "reference": "ORD-104822", "created_at": "2026-12-01T09:42:17Z"}
6.2 Retrieve a shipment
GET /shipments/{shipment_id}
Parameter | In | Type | Required | Description |
|---|---|---|---|---|
shipment_id | path | string | Yes | [The shipment ID, e.g. shp_9QwX2kLm] |
Example response (200 OK)
{"id": "shp_9QwX2kLm", "status": "in_transit", "tracking_number": "PC7730918842GB", "estimated_delivery": "2026-12-02", "last_event": {"code": "arrived_at_hub", "description": "Arrived at York delivery hub", "occurred_at": "2026-12-02T04:12:09Z"}}
Shipment status values: [label_created, picked_up, in_transit, out_for_delivery, delivered, exception, returned, cancelled.]
6.3 List shipments
GET /shipments
Parameter | In | Type | Required | Description |
|---|---|---|---|---|
status | query | string | No | [Filter by status] |
created_after | query | string | No | [ISO 8601 date-time] |
limit | query | integer | No | [1–100, default 25] |
starting_after | query | string | No | [Cursor: ID of the last shipment from the previous page] |
Example response (200 OK)
{"object": "list", "has_more": true, "data": "(array of shipment objects as in 6.2)"}
6.4 Cancel a shipment
POST /shipments/{shipment_id}/cancel
[Cancels a shipment that has not been picked up and refunds the label price to your account balance within 24 hours. Returns 409 if the parcel has already been collected.]
Example response (200 OK)
{"id": "shp_9QwX2kLm", "status": "cancelled", "refund": {"amount": 645, "currency": "GBP", "status": "pending"}}
7. Errors
[Errors use standard HTTP status codes and a consistent JSON body with a machine-readable code, a human-readable message, the field at fault where relevant, and a request ID to quote to support.]
{"error": {"type": "invalid_request", "code": "postal_code_invalid", "message": "to_address.postal_code is not a valid postal code for country GB.", "field": "to_address.postal_code", "request_id": "req_3kT9aZ1"}}
Status | Type | Common codes | What to do |
|---|---|---|---|
400 | invalid_request | [missing_field, postal_code_invalid, parcel_too_heavy] | [Fix the request; do not retry unchanged] |
401 | authentication_error | [api_key_missing, api_key_invalid] | [Check the key and environment] |
403 | permission_error | [service_not_enabled] | [Ask your account manager to enable the service] |
404 | not_found | [shipment_not_found] | [Check the ID and environment] |
409 | conflict | [already_collected, idempotency_key_reused] | [Do not retry; check the resource state] |
422 | unprocessable | [address_undeliverable] | [Correct the address or choose another service] |
429 | rate_limited | [too_many_requests] | [Retry after the Retry-After seconds, with back-off] |
500, 502, 503 | api_error | [internal_error, carrier_unavailable] | [Retry with exponential back-off using the same Idempotency-Key] |
8. Webhooks
[Register an HTTPS endpoint to receive events. Parcelly sends a POST with a JSON event body and expects a 2xx response within 10 seconds. Failed deliveries are retried with exponential back-off for up to 3 days. Events may arrive more than once or out of order: de-duplicate on the event ID and use occurred_at for ordering.]
Event type | Sent when |
|---|---|
shipment.picked_up | [The carrier collects the parcel] |
shipment.out_for_delivery | [The parcel is on the vehicle for delivery today] |
shipment.delivered | [Delivery is confirmed] |
shipment.exception | [A delivery problem occurs, e.g. address not found] |
Example event
{"id": "evt_1Lm8Qa", "type": "shipment.delivered", "occurred_at": "2026-12-02T13:27:44Z", "data": {"shipment_id": "shp_9QwX2kLm", "tracking_number": "PC7730918842GB", "signed_by": "S. Carter"}}
Verifying signatures: [Each request includes a Parcelly-Signature header containing a timestamp and an HMAC-SHA256 signature of the timestamp and raw body, using your endpoint’s signing secret. Compute the signature and compare in constant time; reject requests older than 5 minutes.]
9. SDKs and tools
[Official libraries: Node.js, Python, PHP, Java]
[OpenAPI specification: https://api.parcelly.example/v1/openapi.json]
[Postman collection: [link]]
10. Changelog
Date | Change | Type |
|---|---|---|
[2026-12-01] | [Added label_format "zpl" for thermal printers] | [Additive] |
[2026-10-01] | [Added estimated_delivery to shipment objects] | [Additive] |
[2026-07-15] | [Deprecated field "weight_kg"; use weight_grams. Removal on 2027-07-15] | [Deprecation] |