EasyParcel API
The EasyParcel API prices and buys shipments, returns waybills and tracking, and gives your network of customers a way to manage credit. This reference is generated from the OpenAPI contract and is published ahead of the implementation.
Every operation on these pages is marked coming soon: the contract is published ahead of the implementation so you can plan your integration. Shapes may still change until an operation is released.
Base URL
Send every request over HTTPS. The path after the base URL is the same everywhere: GET /shipments/{shipment_id} is always GET /shipments/{shipment_id} below the base URL.
Base URL
https://api.parcelabs.com/easyparcelContract 321c71e (321c71e)
Authentication
Send your API key in the X-API-Key header on every call, whichever base URL you use. It is the only credential: there is no access token and no Authorization header. The key is never accepted in the path or in the query string. What a key may do is a property of the key: GET /account lists the functions enabled for it. Keys can be limited to allowed IP addresses: a call from another address is answered with 403 IP_NOT_ALLOWED. Keep the key on your server.
Send your API key
curl "https://api.parcelabs.com/easyparcel/account" \
-H "X-API-Key: $API_KEY"Versioning
The version is chosen with a request header, never with the path.
- Send the optional header
ParceLabs-Version: 2026-10-23. The value is a date. Without it you get the oldest supported version, which today is2026-10-23. A request never moves to a newer version on its own. - Every response, including errors, echoes the resolved version in the
ParceLabs-Versionheader. - An unknown date is answered with
400 UNSUPPORTED_VERSION, a retired one with410 VERSION_RETIRED; the errordetailslist the supported versions. - A version being phased out answers normally and adds
DeprecationandSunsetheaders. - A new version is cut only for a breaking change. New fields, new optional parameters, new operations and new values in a response never need one: ignore keys you do not know and tolerate new enum values.
- An old version stays available for at least 12 months after a newer one ships.
Language
Two independent choices, both per request:
| What | Header | Default |
|---|---|---|
| Language of the JSON keys of the response | ParceLabs-Key-Locale: en or it | en |
Language of human-readable messages (error.message, descriptions) | Accept-Language: en or it | en |
Every key of a request body and every query parameter also has an Italian alias, shown next to the English name in the reference. Aliases are always accepted, whatever ParceLabs-Key-Locale says; when both the English key and its alias are present, the English one wins. Italian mode renames keys only: enum values (DOMESTIC), currency, error codes and header names stay English, and so do the envelope keys (error, data, meta, total, page, per_page) and webhook payloads.
Conventions
| Topic | Rule |
|---|---|
| Format | JSON, UTF-8, snake_case keys. A single item is returned at the root, without a wrapper. |
| Lists | { "data": [], "meta": { "total", "page", "per_page" } }, newest first. Page with page (from 1) and per_page (default 15, at most 100). |
| Filters | Plain query parameters named like the field. Several values are comma-separated (status=IN_STORAGE,REQUESTED). Date ranges use *_from and *_to, inclusive, YYYY-MM-DD. |
| Nulls | A key with no value is present with null. Unknown keys in a request are rejected with VALIDATION_ERROR. |
| Timestamps | ISO 8601 with offset, in UTC. Dates are YYYY-MM-DD; pickup times are HH:MM in Europe/Rome. |
| Money | Responses: { "amount": "6.90", "currency": "EUR" }, the amount a decimal string with two decimals. Requests: a JSON number. EUR only. |
| Enums | UPPER_SNAKE words (DOMESTIC, OUT_FOR_DELIVERY). |
| Countries | ISO 3166-1 alpha-2, upper case. |
| Identifiers | Opaque strings: never parse them. |
| Names and emails | Trimmed and normalised before they are stored. Emails are lower-cased. |
HTTP status is the single source of truth: 2xx succeeded, 4xx is your request (do not retry as is), 5xx and 429 are worth a retry. A resource that belongs to someone else answers 404, never 403. Errors are described on the Errors page.
Idempotency and correlation
- Idempotency. Writes that spend money or create records carry an
Idempotency-Keyheader (a UUID is a good choice, 255 characters at most). It is required onPOST /shipments,POST /customers,POST /credit-transfersand the release of a held shipment; optional onPOST /quotations,POST /refund-requestsandPOST /proofs-of-delivery. A retry with the same key and the same body returns the first response withIdempotent-Replayed: true, for 24 hours. The same key with another body is422 IDEMPOTENCY_KEY_REUSED; a call still running is409 IDEMPOTENCY_KEY_IN_USE. - Correlation. Send
X-Correlation-Id(64 characters at most,A-Za-z0-9._-) to follow a call across systems. It is generated when you omit it, and echoed on every response. Quote it when you contact support about a5xx.
Rate limits
Quotations have a daily limit per key, and every endpoint a burst limit. When one is exceeded the answer is 429 with DAILY_LIMIT_EXCEEDED or RATE_LIMIT_EXCEEDED, a Retry-After header and the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset fields. Wait for Retry-After before you try again.
Operations
All operations of the public reference, with their status. Features reserved to enabled customers (Order-Direct, Order-Faster, held-shipment release and refund requests) have their own pages in the menu.
GET /accountGet account and key informationComing soonPOST /quotationsCreate a quotationComing soonGET /quotations/{quotation_id}Get a quotationComing soonPOST /coupon-checksCheck a discount couponComing soonPOST /shipmentsCreate a shipmentComing soonGET /shipmentsList shipmentsComing soonGET /shipments/{shipment_id}Get a shipmentComing soonGET /shipments/{shipment_id}/waybillGet the waybill of a shipmentComing soonGET /tracking/{tracking_number}Get tracking by waybillComing soonGET /tracking/lookupFind tracking by waybill, reference or offer codeComing soonGET /trackingTrack several shipmentsComing soonGET /shipments/{shipment_id}/trackingGet tracking of a shipmentComing soonGET /service-pointsSearch service points (PUDO)Coming soonGET /tariff-codesSearch TARIC codes by descriptionComing soonPOST /customersCreate a customer in your networkComing soonPOST /customers/{customer_id}/invitationsSend a customer invitation againComing soonGET /balanceGet your prepaid balanceComing soonGET /customers/{customer_id}/balanceGet the balance of a customerComing soonPOST /credit-transfersMove credit to a customerComing soonWEBHOOK shipment.waybill_readyWaybill readyComing soon