Ecoparcel API (2.0.0)

The API follows Semantic Versioning: MAJOR.MINOR.PATCH. Backwards-incompatible changes bump MAJOR, additive (backwards-compatible) features bump MINOR, and bug fixes / non-breaking improvements bump PATCH.

2.0.0 — 2026-08-19

• Breaking: GET /api/tracking/{order_id}/ no longer returns tracking for a code alone. Authenticated callers get their own orders unchanged; every other lookup — unauthenticated, or an account asking about an order it did not place — must pass the order's collection or delivery postcode as ?postcode=. A request with no postcode returns 400 postcode_required naming the field to add; a wrong postcode returns 404 tracking_not_found. Both answers are identical for codes that do not exist, so neither can be used to discover valid codes. This matches the postcode gate the web tracker has always had, and stops order codes from being enumerable.
• Rate limits now apply to authenticated tracking requests too (30/min per account), and repeated failed lookups return 429 too_many_invalid_lookups.

1.0.7 — 2026-05-07

• Added event_code field to each tracking event in GET /api/tracking/{order_id}/. The code is a stable 4-digit identifier (see the Tracking Event Codes section below) that integrators can map to their own status taxonomy without parsing the localized event_description.

1.0.6 — 2026-05-02

• Enforced minimum parcel weight of 1.00 kg on order create. Parcels with weight < 1.00 are bumped to 1.00 before pricing.
• Added a per-order warning listing the affected Parcel IDs, e.g. Parcel weight below minimum (1 kg) — bumped to 1 kg for parcel(s): EPDQRZ01, EPDQRZ03.

1.0.5 — 2026-04-23

• Shipping price calculation now applies user-specific VAT and business pricing.
• The /api/shipping-price/ endpoint returns prices tailored to the authenticated account.

1.0.4 — 2026-04-12

• Added optional label_format override on order create/update to force a specific label format (e.g. A4, A6) regardless of the carrier default.
• /api/order/{order_id}/labels/ honours the per-order format override.

1.0.3 — 2026-03-27

• New GET /api/order/ — list orders with filtering and pagination.
• New GET /api/order/{order_id}/ — retrieve a single order.
• New GET /api/order/{order_id}/labels/ — fetch shipping labels for an existing order.

1.0.2 — Initial public release

• POST /api/order/ — create draft or pay-on-create orders.
• PUT /api/order/{order_id}/ — update / confirm and pay drafts.
• DELETE /api/order/{order_id}/ — delete draft orders.
• GET /api/pudo/ — search PUDO points (lockers).
• GET /api/tracking/ — public tracking endpoint.
• JWT (Bearer) authentication via /api/access/ and /api/access/refresh/.

The API uses Bearer (JWT) authentication.

You can find your API Token in Integrations.

Obtain a JWT token pair by exchanging your existing API Token at the /api/access/ endpoint.

Step 1 — Exchange your Token for a JWT

POST /api/access/
Authorization: Token your-api-token-here

Response:

{
  "access": "eyJhbGciOiJIUzI1NiIs...",
  "refresh": "BZssDasdfjJkd1NiIs..."
}

Step 2 — Use the Bearer token for all API requests

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

The access token is valid for 30 minutes.

Step 3 — Refresh when the access token expires

POST /api/access/refresh/
Content-Type: application/json

{"refresh": "BZssDasdfjJkd1NiIs..."}

Response:

{
  "access": "eyJhbGciOiJIUzI1NiIs...new..."
}

The refresh token is valid for 7 days and rotates on each use.

Examples

cURL:

# Get JWT tokens
curl -X POST https://www.ecoparcel.eu/api/access/ \
  -H "Authorization: Token abc123def456"

# Use Bearer token
curl -X POST https://www.ecoparcel.eu/api/order/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"orders": [...]}'

Python (requests):

import requests

# Exchange Token for JWT
token_response = requests.post(
    "https://www.ecoparcel.eu/api/access/",
    headers={"Authorization": "Token abc123def456"},
)
access_token = token_response.json()["access"]

# Use Bearer token
response = requests.post(
    "https://www.ecoparcel.eu/api/order/",
    headers={"Authorization": f"Bearer {access_token}"},
    json={"orders": [...]},
)

JavaScript (fetch):

// Exchange Token for JWT
const tokenRes = await fetch("https://www.ecoparcel.eu/api/access/", {
  method: "POST",
  headers: { "Authorization": "Token abc123def456" },
});
const { access } = await tokenRes.json();

// Use Bearer token
const res = await fetch("https://www.ecoparcel.eu/api/order/", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${access}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ orders: [...] }),
});

Public endpoints

The Tracking endpoint is publicly accessible without authentication. Anonymous requests are rate-limited to 10 requests per minute.

Client Type	Limit
Anonymous	10 requests/min
Authenticated	30 requests/min

Orders go through a simple lifecycle. Understanding the statuses and the available actions at each stage will help you integrate smoothly.

Order Statuses

Status	Meaning
TEMP	Draft order — not yet paid or submitted to a carrier. Can be edited, confirmed, or deleted.
NEW	Paid and queued for processing. The carrier will receive the shipment shortly.
IN_PROGRESS	Handed over to the carrier. Tracking events will start appearing.
DELIVERED	Successfully delivered to the recipient.
CANCELLED	Cancelled due to collection failure or request.
REFUNDED	Cancelled and refunded.

Typical Flows

1. Quick order (create + pay in one call)

The simplest integration — create an order and pay for it in a single request.

POST /api/order/
{ "orders": [...], "confirm_and_pay": true }

The order is created, priced, paid, and submitted to the carrier immediately. The response includes a base64-encoded shipping label PDF in the labels field.

Recommended for: production integrations where the sender and receiver addresses are known upfront and no PUDO selection is needed (door-to-door shipments).

2. Two-step order (create draft, then confirm)

Create the order first as a draft, then confirm and pay separately. Useful when you need to review pricing or make adjustments before committing.

Step 1 — Create a draft order:

POST /api/order/
{ "orders": [...], "confirm_and_pay": false }

The order is saved with status TEMP. No charge is made.

Step 2 — Confirm and pay:

PUT /api/order/{order_id}/
{ "confirm_and_pay": true }

The order is paid and submitted. Labels are returned in the response.

Recommended for: testing, or when you want to inspect the calculated price before paying.

3. PUDO point selection flow

When using locker-based transportation types (door_to_locker, locker_to_door, locker_to_locker) and you want the user to choose a specific locker, follow this flow:

Step 1 — Create a draft order without a PUDO point:

POST /api/order/
{
  "orders": [{
    ...,
    "transportation_type": "door_to_locker"
  }],
  "confirm_and_pay": false
}

The system auto-selects the nearest locker. The order is saved as TEMP.

Step 2 — Search for nearby PUDO points:

GET /api/pudo/?order_id={order_id}&for_consignee=true

Returns a list of available lockers near the consignee address, filtered by the carrier assigned to the order.

Step 3 — Update the order with the chosen PUDO and confirm:

PUT /api/order/{order_id}/
{
  "consignee_details": { "pudo_point": "87" },
  "confirm_and_pay": true
}

Note: You can also provide pudo_point directly in the POST /api/order/ call if you already know the PUDO ID, skipping the search step entirely.

4. Editing a draft order

Any TEMP order can be updated — change addresses, parcel dimensions, transportation type, or anything else.

PUT /api/order/{order_id}/
{
  "consignee_details": { "address": "New Street 5", "city": "Tallinn", "postcode": "10115" },
  "parcels": [{ "description": "Updated", "width": 25, "height": 15, "length": 35, "weight": 3, "value": 80 }]
}

The service card and price are recalculated on every update. Only provided fields are changed — omitted fields keep their current values.

5. Cancelling an order

Draft orders (TEMP) can be deleted outright:

DELETE /api/order/{order_id}/

Orders that have already been paid (NEW, IN_PROGRESS) cannot be cancelled via the API. Use the Ecoparcel dashboard or contact support.

Payment

When confirm_and_pay is set to true (either on create or update), the system charges your account in this order:

1. Account balance is used first.
2. If the balance is insufficient, your saved payment card is charged for the remaining amount.

If neither balance nor card can cover the cost, the order stays in TEMP status with a warning in the response.

Value	Description
door_to_door	Door to Door
door_to_locker	Door to Locker
locker_to_door	Locker to Door
locker_to_locker	Locker to Locker

PUDO points (lockers)

For locker-based transportation types, a pudo_point field can be included inside shipper_details and/or consignee_details to specify an exact drop-off/pick-up locker (by ID).

Transportation Type	shipper_details.pudo_point	consignee_details.pudo_point
door_to_door	Not allowed	Not allowed
door_to_locker	Not allowed	Optional (auto-selected if omitted)
locker_to_door	Optional (auto-selected if omitted)	Not allowed
locker_to_locker	Optional (auto-selected if omitted)	Optional (auto-selected if omitted)

When pudo_point is omitted for a locker side, the system automatically selects the nearest locker based on the provided address.

Important: sending pudo_point for a side that does not require a locker (e.g. shipper side on door_to_locker) will return a 400 validation error.

Value	Description
parcel	Standard parcel shipment
pallet	Pallet shipment

Each entry in tracking_events[] returned by GET /api/tracking/{order_id}/ includes a stable 4-digit event_code. Use the code (not the human-readable event_description) to drive your own logic — descriptions are localized and may change wording, but codes are stable.

Code	Description
0002	Prepared for collection
0101	Out for collection
0102	Collection successful (includes parcel locker / shop drop-off by shipper)
0103	Collection problem
0105	Collection problem — Wrong address
0107	Collection cancelled — Wrong address
0108	Collection cancelled — Shipper was absent
0109	Cancelled
0110	Collection cancelled — Insufficient customs declaration
0111	Refunded to the balance
0112	Contacted
0201	Inbound
0202	Outbound
0204	Return
0205	Non-conveyable
0301	Out for delivery
0302	Delivery successful — Consignee
0303	Delivery successful — Parcelshop / Locker (consignee-side)
0304	Delivery successful — Post Office
0305	Delivery successful — Neighbour
0306	Delivery problem — Consignee was absent
0307	Delivery problem — Wrong address
0308	Delivery problem — Consignee refused
0309	Delivery problem — Not out for delivery
0310	Delivery problem
0311	Delivery problem — Consignee refused
0501	Parcel stored in warehouse
0502	Additional information
0503	Customs
0505	Changed collection date

Failure / problem codes

The following subset indicates the parcel hit a problem state and may need attention (failed collection, failed delivery, return):

0103, 0105, 0107, 0108, 0204, 0306, 0307, 0308, 0309, 0310