Horeca24 Partner API › Orders

Courier update, for orders with your own courier

POSThttps://management.horeca-24.de/api/partner/v1/orders/{externalId}/delivery

Only for orders with fulfillment.courier: partner; any other order answers 409 INVALID_TRANSITION.

picked_up: delivery status "on the way" in the till.
delivered: delivery status "delivered"; the restaurant can complete the order.
assigned, arriving: no change of the delivery status; the other fields still apply.
failed: nothing changes in the till; our support is alerted. Cancel the order separately if needed.

etaPickupAt / etaDropOffAt set the pickup and drop-off times, courier the driver (the latest counts), trackingUrl the tracking link. The order's status never changes by a courier update. An update that changes nothing answers changed: false, so retries are safe.

Headers

AuthorizationstringRequired

Bearer pk_<connectionId>.<keyId>.<secret>

The connection's API key, from the restaurant's till. Treat it as one opaque string. 401 UNAUTHORIZED for a missing, wrong, expired or revoked key; 403 CONNECTION_REVOKED for the key of a deleted connection. After a rotation by the restaurant, the previous key keeps working for 24 hours.

Path parameters

externalIdstringRequiredpattern: ^[A-Za-z0-9._~-]{1,64}$

Your order id, as sent in POST /orders.

Request

application/jsonRequired

statusstringRequiredassignedarrivingpicked_updeliveredfailed

etaPickupAtstringOptionalformat: date-time

ISO 8601 with Z or an offset

etaDropOffAtstringOptionalformat: date-time

ISO 8601 with Z or an offset

courierobjectOptional

Show child attributesHide child attributes

namestringRequired1-200 chars

phonestringRequired1-50 chars

trackingUrlstringOptional0-2048 charsformat: uri

Response

200Taken

orderIdstringRequiredpattern: ^oo_[0-9a-f]{64}$

Our order id

externalIdstringRequiredpattern: ^[A-Za-z0-9._~-]{1,64}$

Your order id, unique per connection

changedbooleanRequired

false when the update changed nothing

Errors

objectErrorBody

400

An error; see ErrorCode

401

UNAUTHORIZED: the key is missing, malformed, unknown, wrong, expired or revoked

403

CONNECTION_REVOKED: the restaurant deleted the connection; stop sending

404

An error; see ErrorCode

409

An error; see ErrorCode

422

An error; see ErrorCode

429

RATE_LIMITED: 60 per minute and connection, shared by orders, cancel and delivery

Headers

Retry-AfterintegerOptional

Seconds until the window ends

POST/orders/{externalId}/delivery

cURL

curl -X POST https://management.horeca-24.de/api/partner/v1/orders/A/delivery \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "status": "picked_up",
  "etaPickupAt": "2026-10-15T12:10:00Z",
  "etaDropOffAt": "2026-10-15T12:30:00Z",
  "courier": {
    "name": "Ali",
    "phone": "+49 151 000000"
  },
  "trackingUrl": "https://track.example/x"
}'

Python

import os
import requests

url = "https://management.horeca-24.de/api/partner/v1/orders/A/delivery"

headers = {
    "Authorization": "Bearer " + os.environ["PARTNER_API_KEY"],
}

payload = {
    "status": "picked_up",
    "etaPickupAt": "2026-10-15T12:10:00Z",
    "etaDropOffAt": "2026-10-15T12:30:00Z",
    "courier": {
        "name": "Ali",
        "phone": "+49 151 000000",
    },
    "trackingUrl": "https://track.example/x",
}

response = requests.post(url, headers=headers, json=payload)

print(response.status_code)
print(response.text)

JavaScript

const response = await fetch("https://management.horeca-24.de/api/partner/v1/orders/A/delivery", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.PARTNER_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "status": "picked_up",
    "etaPickupAt": "2026-10-15T12:10:00Z",
    "etaDropOffAt": "2026-10-15T12:30:00Z",
    "courier": {
      "name": "Ali",
      "phone": "+49 151 000000"
    },
    "trackingUrl": "https://track.example/x"
  }),
});

const data = await response.text();
console.log(response.status, data);

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://management.horeca-24.de/api/partner/v1/orders/A/delivery',
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PARTNER_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'status' => 'picked_up',
        'etaPickupAt' => '2026-10-15T12:10:00Z',
        'etaDropOffAt' => '2026-10-15T12:30:00Z',
        'courier' => [
            'name' => 'Ali',
            'phone' => '+49 151 000000',
        ],
        'trackingUrl' => 'https://track.example/x',
    ]),
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Try it

Sends a real request to https://management.horeca-24.de/api/partner/v1

ServerAuthorizationNever stored, never sent to us.externalIdBody

Response

200

200Taken

{
  "orderId": "oo_5c1e2d3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d",
  "externalId": "A-1001",
  "changed": true
}

400

400An error; see ErrorCode

{
  "error": {
    "code": "INVALID_AMOUNTS",
    "message": "itemsSubtotal must be 2700",
    "path": "amounts.itemsSubtotal",
    "requestId": "6b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
  }
}

401

401UNAUTHORIZED: the key is missing, malformed, unknown, wrong, expired or revoked

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "string",
    "path": "string",
    "details": null,
    "requestId": "string"
  }
}

403

403CONNECTION_REVOKED: the restaurant deleted the connection; stop sending

{
  "error": {
    "code": "CONNECTION_REVOKED",
    "message": "string",
    "path": "string",
    "details": null,
    "requestId": "string"
  }
}

404

404An error; see ErrorCode

{
  "error": {
    "code": "INVALID_AMOUNTS",
    "message": "itemsSubtotal must be 2700",
    "path": "amounts.itemsSubtotal",
    "requestId": "6b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
  }
}

409

409An error; see ErrorCode

{
  "error": {
    "code": "INVALID_AMOUNTS",
    "message": "itemsSubtotal must be 2700",
    "path": "amounts.itemsSubtotal",
    "requestId": "6b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
  }
}

422

422An error; see ErrorCode

{
  "error": {
    "code": "INVALID_AMOUNTS",
    "message": "itemsSubtotal must be 2700",
    "path": "amounts.itemsSubtotal",
    "requestId": "6b1f2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
  }
}

429

429RATE_LIMITED: 60 per minute and connection, shared by orders, cancel and delivery

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "string",
    "path": "string",
    "details": null,
    "requestId": "string"
  }
}