Ecoparcel API (1.0.7)

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.

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.

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

Order Statuses

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.

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).

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.

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.

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