Skip to content

The Hopla API

Create orders, attach parcels, append tracking events. Everything a Hopla tracking page shows comes from these endpoints.

Base URLhttps://hopla.delivery
JSON/v1Bearer

From zero to a tracking page in three calls

The examples use two shell variables. Set them once:

shell
API=https://hopla.delivery
KEY=hopla_dev_key
  1. Create an order with its items and parcels

    One call writes the order, its items and its parcels. Leave the carrier out and it is detected from the tracking number.

    POST /v1/orders
    curl -X POST "$API/v1/orders" \
      -H "Authorization: Bearer $KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: demo-2001" \
      -d '{
        "orderNumber": "HP-2001",
        "store": { "name": "Atelier Nord" },
        "customer": { "name": "Camille Durand", "email": "camille.durand@example.com" },
        "destination": { "city": "Lyon", "postalCode": "69002", "country": "FR" },
        "items": [
          {
            "ref": "a",
            "title": "Linen overshirt",
            "variant": "Sand / M",
            "quantity": 1,
            "unitPriceCents": 8900,
            "imageUrl": "https://cdn.example/overshirt.jpg"
          }
        ],
        "shipments": [
          {
            "trackingNumber": "6A20001118001",
            "carrier": "la-poste",
            "origin": { "city": "Lille", "country": "FR" },
            "items": [ "a" ],
            "simulate": { "scenario": "domestic_home", "autoStart": true }
          }
        ]
      }'
  2. Append a checkpoint

    Send a code, a place and, if you have it, the carrier’s own message. The parcel’s status follows its latest event.

    POST /v1/shipments/:id/events
    curl -X POST "$API/v1/shipments/6A20001118001/events" \
      -H "Authorization: Bearer $KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "substatus": "out_for_delivery",
        "location": { "place": "LYS" },
        "message": "Votre colis est en cours de livraison.",
        "messageLang": "fr",
        "details": { "window": "14:00-18:00" }
      }'
  3. Open the page

    The order page and a page per parcel are live at once, in four languages. Give your customer the link.

    See a demo order page/en/order/HP-1042

Authentication

Write endpoints need an API key in the Authorization header. Lookups are public.

header
Authorization: Bearer hopla_dev_key

X-Api-Key is accepted too. A missing or wrong key answers 401 unauthorized. Order and shipment reads return personal data, so they need the key as well.

Public endpoints
Public endpointsDescription
GET /v1/track/:refLook up a parcel by tracking number, or a whole order by order number or order id. This is the answer every tracking page is drawn from.
POST /v1/track/batchLook up as many as 40 references in one call. Each one gets its own result, found or not.
POST /v1/detectPull references out of free text and rank the carriers each one could belong to.
GET /v1/carriersThe carrier directory, with the patterns used to recognise numbers.
GET /v1/carriers/:slugOne carrier by its slug.
GET /v1/statusesThe status model with labels and descriptions in one language, or in all four.
GET /v1/placesThe places events can point to: localised names, coordinates and time zones.
GET /healthLiveness and row counts.
GET /v1/simulator/scenariosThe journeys the simulator can play.

The status model

Nine statuses for filters and colours, 52 sub-statuses for wording.

StatusCodeWhat it means
Awaiting shipmentpendingThe sender has registered this parcel, but the carrier doesn't have it yet.
In transitin_transitThe parcel is moving through the carrier's network toward its destination.
Out for deliveryout_for_deliveryThe parcel is with the courier and should be delivered today.
Ready for pickupavailable_for_pickupThe parcel is waiting at a pickup point or locker. Bring an ID or your pickup code.
DelivereddeliveredfinalThe parcel has been delivered.
Delivery attemptedfailed_attemptThe courier tried to deliver the parcel but couldn't. Another attempt or a pickup option usually follows.
Delivery issueexceptionSomething is holding this parcel up. Check the latest update for what happens next.
Return to senderreturnedThe parcel is going back, or has gone back, to the sender.
No recent updatesexpiredThe carrier hasn't reported anything for a long time. Contact the sender if the parcel hasn't arrived.
At the store · 3 codes
  • order_placedOrder placed → pending
  • order_processingBeing prepared → pending
  • order_readyReady to ship → pending
First mile · 5 codes
  • info_receivedLabel created → pending
  • awaiting_carrier_pickupWaiting for carrier pickup → pending
  • picked_upPicked up by carrier → in_transit
  • dropped_offDropped off → in_transit
  • accepted_originAccepted at origin facility → in_transit
On the way · 4 codes
  • arrived_hubArrived at sorting facility → in_transit
  • sortedSorted → in_transit
  • departed_hubDeparted sorting facility → in_transit
  • in_transitIn transit → in_transit
Export · 4 codes
  • export_hub_arrivedArrived at export hub → in_transit
  • export_customsExport customs clearance → in_transit
  • departed_origin_countryDeparted country of origin → in_transit
  • transit_countryArrived in transit country → in_transit
Customs and import · 7 codes
  • arrived_destination_countryArrived in destination country → in_transit
  • customs_processingCustoms clearance in progress → in_transit
  • customs_clearedCleared customs → in_transit
  • customs_heldHeld at customs → exception
  • customs_duties_dueDuties and taxes to pay → exception
  • customs_info_requiredCustoms needs more information → exception
  • handed_to_local_carrierHanded to local carrier → in_transit
Last mile · 8 codes
  • arrived_delivery_depotArrived at delivery depot → in_transit
  • out_for_deliveryOut for delivery → out_for_delivery
  • delivery_rescheduledDelivery rescheduled → in_transit
  • deliveredDelivered → delivered
  • delivered_mailboxDelivered to mailbox → delivered
  • delivered_signedDelivered and signed for → delivered
  • delivered_third_partyDelivered to neighbor or reception → delivered
  • delivered_safe_placeLeft in a safe place → delivered
Pickup points · 4 codes
  • arrived_pickup_pointArrived at pickup point → available_for_pickup
  • pickup_reminderPickup reminder → available_for_pickup
  • picked_up_by_recipientCollected → delivered
  • pickup_expiredNot collected → returned
Delivery attempts · 6 codes
  • attempt_absentNobody home → failed_attempt
  • attempt_closedPremises closed → failed_attempt
  • address_issueAddress problem → exception
  • recipient_refusedRefused by recipient → exception
  • recipient_unreachableRecipient unreachable → exception
  • awaiting_recipient_actionWaiting for the recipient → exception
Problems · 9 codes
  • delayedDelayed → exception
  • misroutedSent to the wrong facility → exception
  • damagedDamaged → exception
  • lostLost → exception
  • on_holdOn hold → exception
  • security_checkHeld for inspection → exception
  • redirectedRedirected → in_transit
  • cancelledShipment cancelled → exception
  • no_updatesNo updates → expired
Returns · 2 codes
  • return_in_transitBeing returned to sender → returned
  • return_deliveredReturned to sender → returned
Send codes, not sentences: Hopla writes the sentence in the reader’s language.

Reference

Every answer is { "data": … }, plus meta on lists, or { "error": … }. Field names are camelCase, timestamps are ISO 8601 with an offset.

Orders

POST/v1/ordersAPI key

Create an order with its items and parcels in one transaction. If any part is invalid, nothing is written.

NameTypeDescription
Idempotency-KeyheaderstringMakes a retry safe: the same key with the same body returns the first answer.
orderNumberbodyrequiredstringYour own number, 1 to 40 characters, unique.
storebodyrequiredobjectname is required; url and supportEmail are optional.
customerbodyrequiredobjectname is required. Public pages show it masked.
destinationbodyrequiredobjectcity and country are required. Street lines never appear on public pages.
itemsbodyrequiredItem[]1 to 100 items: title, quantity, and optionally variant, unitPriceCents, imageUrl. ref ties an item to a parcel.
shipmentsbodyShipment[]0 to 20 parcels. An order can be created before anything ships.
localebodyen | fr | zh | ruThe customer’s language.
POST /v1/orders
curl -X POST "$API/v1/orders" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-2001" \
  -d '{
    "orderNumber": "HP-2001",
    "store": { "name": "Atelier Nord" },
    "customer": { "name": "Camille Durand", "email": "camille.durand@example.com" },
    "destination": { "city": "Lyon", "postalCode": "69002", "country": "FR" },
    "items": [
      {
        "ref": "a",
        "title": "Linen overshirt",
        "variant": "Sand / M",
        "quantity": 1,
        "unitPriceCents": 8900,
        "imageUrl": "https://cdn.example/overshirt.jpg"
      }
    ],
    "shipments": [
      {
        "trackingNumber": "6A20001118001",
        "carrier": "la-poste",
        "origin": { "city": "Lille", "country": "FR" },
        "items": [ "a" ],
        "simulate": { "scenario": "domestic_home", "autoStart": true }
      }
    ]
  }'

GET/v1/ordersAPI key

List orders, newest first, with filters and cursor pagination.

NameTypeDescription
qquerystringMatches the order number, the customer’s name or email, or a tracking number.
statusquerystringOne or several status codes, separated by commas.
demoquery0 | 1Only demo orders, or only your own.
expandqueryshipments | eventsInclude each parcel’s events.
limitqueryintegerPage size. Default 20, at most 100.
cursorquerystringmeta.nextCursor of the previous page.
GET /v1/orders
curl "$API/v1/orders?status=exception,failed_attempt&limit=10" \
  -H "Authorization: Bearer $KEY"

GET/v1/orders/:refAPI key

Read one order in full, personal data included.

NameTypeDescription
refpathrequiredstringThe order id or the order number.
expandqueryeventsInclude each parcel’s events.
GET /v1/orders/:ref
curl "$API/v1/orders/HP-1042?expand=events" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/orders/:refAPI key

Update an order: store stages, a notice for the customer, items. The order number never changes.

NameTypeDescription
refpathrequiredstringThe order id or the order number.
processingAt · readyAt · cancelledAtbodyISO 8601When the store started preparing, finished packing, or cancelled.
noticebodystring | nullA short message from the store, shown on the order page.
itemsbody{ add, update, remove }Items to add, update or remove.
PATCH /v1/orders/:ref
curl -X PATCH "$API/v1/orders/HP-2001" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "processingAt": "2026-11-18T11:00:00+01:00",
    "notice": "Packed with care — ships tomorrow."
  }'

DELETE/v1/orders/:refAPI key

Delete an order with its parcels, items and events.

NameTypeDescription
refpathrequiredstringThe order id or the order number.
DELETE /v1/orders/:ref
curl -X DELETE "$API/v1/orders/HP-2001" \
  -H "Authorization: Bearer $KEY"

Events

POST/v1/shipments/:id/eventsAPI key

Append one checkpoint, or as many as 50 in an events array. Events may arrive in any order: the status is always that of the latest one.

NameTypeDescription
idpathrequiredstringThe shipment id or its tracking number.
substatusbodyrequiredstringWhat happened, as a code from the status model.
occurredAtbodyISO 8601When it happened, with the local offset. Default: now.
locationbody{ place } | { city, country, … }A place code, or free fields with optional coordinates.
message · messageLangbodystringThe carrier’s own text and its language. Returned untouched.
detailsbodyobjectExtras for some codes: signedBy, window, deadline, reason.
externalIdbodystringYour own id for the event: sending it twice inserts it once.
POST /v1/shipments/:id/events
curl -X POST "$API/v1/shipments/6A20001118001/events" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "substatus": "out_for_delivery",
    "location": { "place": "LYS" },
    "message": "Votre colis est en cours de livraison.",
    "messageLang": "fr",
    "details": { "window": "14:00-18:00" }
  }'

DELETE/v1/shipments/:id/events/:eventIdAPI key

Remove a wrong checkpoint. The status is recomputed.

NameTypeDescription
idpathrequiredstringThe shipment id or its tracking number.
eventIdpathrequiredstringThe event to remove.
DELETE /v1/shipments/:id/events/:eventId
curl -X DELETE "$API/v1/shipments/6A20001118001/events/evt_9t4r6y1n8zc2" \
  -H "Authorization: Bearer $KEY"

Shipments

POST/v1/shipmentsAPI key

Create a parcel on its own or attach it to an existing order. Only the tracking number is required.

NameTypeDescription
Idempotency-KeyheaderstringMakes a retry safe: the same key with the same body returns the first answer.
trackingNumberbodyrequiredstringStored upper-case, without spaces. Unique.
carrierbodyslugOptional when the number’s shape names exactly one carrier.
lastMilebody{ trackingNumber, carrier }The carrier that takes over in the destination country, and its number.
origin · destinationbodyobjectCity and country, or a place code. The destination defaults to the order’s.
deliveryTypebodyhome | pickup_point | locker | mailboxWhere the parcel is handed over.
etabody{ from, to, window, source }Estimated arrival: one date or a range, and who says so.
orderId · orderNumberbodystringAttach the parcel to an existing order.
simulatebody{ scenario, autoStart }Attach a simulator scenario; autoStart plays its first step at once.
POST /v1/shipments
curl -X POST "$API/v1/shipments" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "1Z999AA10123456784",
    "label": "Desk lamp",
    "origin": { "city": "Chicago", "country": "US" },
    "destination": { "city": "Austin", "region": "TX", "country": "US" },
    "simulate": { "scenario": "us_domestic" }
  }'

GET/v1/shipmentsAPI key

List parcels, newest first, with filters and cursor pagination.

NameTypeDescription
qquerystringMatches the tracking number, the label or the order number.
status · substatus · carrierquerystringFilter by status, sub-status or carrier slug.
expandqueryeventsInclude each parcel’s events.
limitqueryintegerPage size. Default 20, at most 100.
cursorquerystringmeta.nextCursor of the previous page.
GET /v1/shipments
curl "$API/v1/shipments?status=in_transit&carrier=china-post" \
  -H "Authorization: Bearer $KEY"

GET/v1/shipments/:idAPI key

Read one parcel with all its events, newest first. The tracking number works in place of the id.

NameTypeDescription
idpathrequiredstringThe shipment id or its tracking number.
GET /v1/shipments/:id
curl "$API/v1/shipments/6A20001118001" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/shipments/:idAPI key

Change the estimate, the carrier, the last-mile leg, the pickup point or the simulator scenario. The status only changes through events.

NameTypeDescription
idpathrequiredstringThe shipment id or its tracking number.
etabodyobject | nullEstimated arrival: one date or a range, and who says so.
carrier · lastMilebodyslug · objectThe carrier that takes over in the destination country, and its number.
simulatebody{ scenario } | nullAttach a simulator scenario; autoStart plays its first step at once.
PATCH /v1/shipments/:id
curl -X PATCH "$API/v1/shipments/6A20001118001" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eta": { "from": "2026-11-20", "to": "2026-11-21", "source": "carrier" }
  }'

DELETE/v1/shipments/:idAPI key

Delete a parcel and its events.

NameTypeDescription
idpathrequiredstringThe shipment id or its tracking number.
DELETE /v1/shipments/:id
curl -X DELETE "$API/v1/shipments/6A20001118001" \
  -H "Authorization: Bearer $KEY"

Tracking (public)

GET/v1/track/:refPublic

Look up a parcel by tracking number, or a whole order by order number or order id. This is the answer every tracking page is drawn from.

NameTypeDescription
refpathrequiredstringA tracking number, a last-mile number, an order number, an order id or a shipment id.
langqueryen | fr | zh | ruLanguage of labels, descriptions and place names. Default en.
eventsqueryall | latestlatest returns only the newest event of each parcel (for lists).
verifyquerystringCustomer email or postal code, when the server asks to confirm order lookups.
GET /v1/track/:ref
curl "$API/v1/track/LV202611181CN?lang=fr"
GET /v1/track/LV202611181CN?lang=en&events=latest

POST/v1/track/batchPublic

Look up as many as 40 references in one call. Each one gets its own result, found or not.

NameTypeDescription
refsbodyrequiredstring[]1 to 40 references. Duplicates are merged.
langbodyen | fr | zh | ruLanguage of labels, descriptions and place names. Default en.
eventsbodylatest | alllatest returns only the newest event of each parcel (for lists).
POST /v1/track/batch
curl -X POST "$API/v1/track/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "refs": [ "LV202611181CN", "1ZVAD0DEMO00000001", "HP-1042", "ABC" ],
    "lang": "en"
  }'

Carriers and detection

POST/v1/detectPublic

Pull references out of free text and rank the carriers each one could belong to.

NameTypeDescription
inputbodyrequiredstringFree text, at most 5,000 characters.
langbodyen | fr | zh | ruLanguage of labels, descriptions and place names. Default en.
POST /v1/detect
curl -X POST "$API/v1/detect" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hi! your parcels: 1ZVAD0DEMO00000001 and rr123456785gb, order HP-1042"
  }'

GET/v1/carriersPublic

The carrier directory, with the patterns used to recognise numbers.

NameTypeDescription
qquerystringMatches the name, the local name or the slug.
countryqueryISO 3166-1 alpha-2Two-letter country code.
kindquerypostal | express | ecommerce | regionalType of carrier.
popularquery1Only the carriers shown first.
langqueryen | fr | zh | ruLanguage of labels, descriptions and place names. Default en.
GET /v1/carriers
curl "$API/v1/carriers?popular=1&lang=ru"
GET /v1/carriers?popular=1&lang=en

GET/v1/carriers/:slugPublic

One carrier by its slug.

NameTypeDescription
slugpathrequiredstringThe carrier’s slug, such as la-poste.
langqueryen | fr | zh | ruLanguage of labels, descriptions and place names. Default en.
GET /v1/carriers/:slug
curl "$API/v1/carriers/la-poste"
GET /v1/carriers/la-poste?lang=en

GET/v1/statusesPublic

The status model with labels and descriptions in one language, or in all four.

NameTypeDescription
langqueryen | fr | zh | ru | allall returns the four languages side by side.
GET /v1/statuses
curl "$API/v1/statuses?lang=zh"
GET /v1/statuses?lang=en

GET/v1/placesPublic

The places events can point to: localised names, coordinates and time zones.

NameTypeDescription
countryqueryISO 3166-1 alpha-2Two-letter country code.
langqueryen | fr | zh | ruLanguage of labels, descriptions and place names. Default en.
GET /v1/places
curl "$API/v1/places?lang=en&country=FR"
GET /v1/places?lang=en&country=FR

GET/healthPublic

Liveness and row counts.

GET /health
curl "$API/health"
GET /health

Simulator

GET/v1/simulator/scenariosPublic

The journeys the simulator can play.

GET /v1/simulator/scenarios
curl "$API/v1/simulator/scenarios"
GET /v1/simulator/scenarios

POST/v1/simulator/shipments/:id/advanceAPI key

Append the next planned events of a simulated parcel.

NameTypeDescription
idpathrequiredstringThe shipment id or its tracking number.
stepsbody1–20How many planned events to append. Default 1.
tobodysubstatus | "end"Advance until this code has been emitted, or to the end.
atbodynow | spacedspaced back-dates the events with realistic gaps so the last one is now.
POST /v1/simulator/shipments/:id/advance
curl -X POST "$API/v1/simulator/shipments/6A20001118001/advance" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "steps": 1 }'

POST/v1/simulator/resetAPI key

Delete the demo orders and create them again with fresh dates. Orders you created yourself are kept.

NameTypeDescription
allbodybooleanAlso delete the orders created by hand.
POST /v1/simulator/reset
curl -X POST "$API/v1/simulator/reset" \
  -H "Authorization: Bearer $KEY"

Errors

Errors share one envelope: a stable code, a message for developers and, when it helps, details.

HTTPCodeWhen
400bad_requestThe JSON is malformed or the content type is wrong.
401unauthorizedThe API key is missing or wrong.
403verification_requiredThe server asks to confirm an order lookup and verify is missing or wrong.
404not_foundNo such id or reference. For lookups, details says what the number looks like.
409order_existsThe order number is already taken. details.existingId names the order.
409tracking_existsThe tracking number is already registered.
409idempotency_conflictThe same idempotency key came with a different body.
413too_manyMore than 40 references, 50 events or 100 items in one call.
422validation_errorThe body failed validation. details lists each path and its problem.
429rate_limitedToo many public calls from one address. Wait for Retry-After.
500internalAnything else. The message is generic; the cause is in the server log.
422
{
  "error": {
    "code": "validation_error",
    "message": "Request body is invalid.",
    "details": [ { "path": "items[0].quantity", "message": "Must be an integer ≥ 1" } ]
  }
}

Idempotency

  1. Send an Idempotency-Key header of up to 100 characters when you create an order or a shipment.
  2. The first successful answer is kept for 24 hours and replayed for the same key and body, with the header Idempotent-Replay: true.
  3. The same key with a different body answers 409 idempotency_conflict.
  4. Even without the header, an order number is unique: posting it again answers 409 order_exists.
header
Idempotency-Key: demo-2001

Languages

?lang=en|fr|zh|ru changes labels, descriptions, place and country names. Raw carrier messages are returned untouched.

GET /v1/track/:ref
curl "$API/v1/track/LV202611181CN?lang=fr"
curl "$API/v1/track/LV202611181CN?lang=zh"
curl "$API/v1/track/LV202611181CN?lang=ru"

Demo data

Fourteen demo parcels cover every status. A simulator moves them, so the status column shows where each one is right now.

Tracking numberCarrierRouteStatus
LV 2026 1118 1CNChina PostShenzhen → LyonIn transit
LP 0042 0000 0000 17CainiaoShenzhen → LyonAwaiting shipment
1ZVA D0DE MO00 0000 01UPSChicago → AustinOut for delivery
6A10 0000 00011La Poste (Colissimo)Lille → BordeauxDelivered
XW 1234 5678 5FRChronopostParis → MarseilleDelivery attempted
24680135Mondial RelayNantes → ToulouseReady for pickup
RV 1042 0001 9CNChina PostYiwu → KazanDelivery issue
1500 0420 17CDEKMoscow → NovosibirskIn transit
YT 2611 1800 0000 0042YunExpressYiwu → PortlandDelivered
7700 1111 8888FedExNew York → DenverDelivery issue
4810 0020 26DHL ExpressHong Kong → LondonReturn to sender
SF 1000 0000 02026SF ExpressShenzhen → HangzhouDelivered
H00V AD00 0000 0001EvriManchester → LondonNo recent updates
2500 0000 0020 26DPD FranceParis → LilleAwaiting shipment