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.

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/easyparcel

Contract 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 is 2026-10-23. A request never moves to a newer version on its own.
  • Every response, including errors, echoes the resolved version in the ParceLabs-Version header.
  • An unknown date is answered with 400 UNSUPPORTED_VERSION, a retired one with 410 VERSION_RETIRED; the error details list the supported versions.
  • A version being phased out answers normally and adds Deprecation and Sunset headers.
  • 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:

WhatHeaderDefault
Language of the JSON keys of the responseParceLabs-Key-Locale: en or iten
Language of human-readable messages (error.message, descriptions)Accept-Language: en or iten

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

TopicRule
FormatJSON, 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).
FiltersPlain 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.
NullsA key with no value is present with null. Unknown keys in a request are rejected with VALIDATION_ERROR.
TimestampsISO 8601 with offset, in UTC. Dates are YYYY-MM-DD; pickup times are HH:MM in Europe/Rome.
MoneyResponses: { "amount": "6.90", "currency": "EUR" }, the amount a decimal string with two decimals. Requests: a JSON number. EUR only.
EnumsUPPER_SNAKE words (DOMESTIC, OUT_FOR_DELIVERY).
CountriesISO 3166-1 alpha-2, upper case.
IdentifiersOpaque strings: never parse them.
Names and emailsTrimmed 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-Key header (a UUID is a good choice, 255 characters at most). It is required on POST /shipments, POST /customers, POST /credit-transfers and the release of a held shipment; optional on POST /quotations, POST /refund-requests and POST /proofs-of-delivery. A retry with the same key and the same body returns the first response with Idempotent-Replayed: true, for 24 hours. The same key with another body is 422 IDEMPOTENCY_KEY_REUSED; a call still running is 409 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 a 5xx.

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.

Was this page helpful?

Was this page helpful?