Versioning
This is version 1 of the API. Within v1 we only add things, so code that works today keeps working.
What can change within v1
- New endpoints, and new optional fields in requests.
- New fields in answers and in webhook payloads.
- New values in open lists: shipment statuses, tracking event types.
- New webhook event types.
So: ignore fields you don't know, ignore event types you don't handle, and treat an unknown status as "in progress" and show its status_detail. Webhook payloads carry api_version: "v1".
Shipment statuses today
| Status | Meaning |
|---|---|
booking | EviPostal is confirming the booking with the carrier. A shipment.booked or shipment.booking_failed event follows. |
booked | The carrier has the booking. The label is ready or being prepared. |
failed | The booking did not happen. Nothing was charged. Book a fresh rate to try again. |
picked_up | The carrier has collected the package. |
in_transit | The package is on its way. |
out_for_delivery | The package is out for delivery. |
delivered | The package was delivered. Final. |
delayed | The carrier reported a delay. |
delivery_issue | The carrier reported a problem (failed pickup, failed delivery, address issue). |
cancelled | The shipment was cancelled before pickup. Production charges were refunded to the wallet. Final. |
Breaking changes
A change that could break working code ships as a new version at a new address (/v2). v1 then answers with Deprecation and Sunset headers, every owner with a v1 key is told, and v1 keeps working for at least six months after v2 is available.