Horeca24 Partner API › Orders

Create an order

POSThttps://management.horeca-24.de/api/partner/v1/orders

Checked in this order; the first problem is answered:

Key (401/403), rate limit (429).
JSON (400 MALFORMED_REQUEST), schema (422 INVALID_FIELD with path).
Known externalId: the same payload answers 200 with duplicate: true; another payload 409 ORDER_CONFLICT.
Store offline (409 STORE_OFFLINE), no webhook URL (409 WEBHOOK_NOT_CONFIGURED).
Currency not the restaurant's (422 CURRENCY_MISMATCH); not checked before the restaurant's first menu sync.
Sums with your prices (422 INVALID_AMOUNTS): line total = quantity × (unitPrice + Σ modifier.unitPrice × modifier.quantity); itemsSubtotal = Σ line totals; 0 ≤ discount ≤ itemsSubtotal; total = itemsSubtotal − discount + deliveryFee + serviceFee + tip; deliveryFee = 0 for a pickup.
Payment: cash/unpaid/amountPaid 0, or online/paid/amountPaid = total with a reference (422 INVALID_FIELD, a wrong amountPaid 422 INVALID_AMOUNTS).

Names, prices and tax rates are taken as sent. Prices are not compared with the menu, and availability is not checked: a product switched off since your copy of the menu is matched and accepted, and a line that cannot be matched (deleted since) reaches the till with your name, price and taxRate.

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.

Request

application/jsonRequired

schemaVersionstringRequiredValue: 1

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

Your order id, unique per connection

currencystringRequiredpattern: ^[A-Z]{3}$

ISO 4217; the menu file's currency

typestringRequiredpickupdelivery

createdAtstringRequiredformat: date-time

ISO 8601 with Z or an offset

fulfillmentobjectRequired

Show child attributesHide child attributes

modestringRequiredasapscheduled

requestedAtstringOptionalformat: date-time

Pickup time for a pickup, arrival time for a delivery

courierstringOptionalstorepartner

store: the restaurant delivers; partner: your courier (enables courier updates)

customerobjectRequired

Show child attributesHide child attributes

namestringRequired1-200 chars

phonestringRequired1-50 chars

emailstringOptional0-254 charsformat: email

addressobjectAddressOptional

Show child attributesHide child attributes

streetstringRequired1-200 chars

streetNumberstringRequired1-50 chars

zipCodestringRequired1-20 chars

citystringRequired1-100 chars

countryCodestringRequiredpattern: ^[A-Z]{2}$

ISO 3166-1 alpha-2

extraAddressInfostringOptional0-500 chars

latnumberOptional-90-90

lngnumberOptional-180-180

Without lat/lng the till shows no map or distance

itemsarray of objectOrderItemRequired1-200 items

Show child attributesHide child attributes

lineIdstringRequired1-128 chars

Unique within the order

productIdstringRequired1-128 chars

The menu file's products[].id

namestringRequired1-200 chars

As the customer saw it

quantityintegerRequired1-999

unitPriceintegerRequired0-10000000

Gross

taxRatenumberRequired0-100

The line's tax rate (the menu file's taxRate); it applies to the line's modifiers too

notestringOptional0-500 chars

modifiersarray of objectOrderModifierRequired0-100 items

[] for none

Show child attributesHide child attributes

modifierGroupIdstringRequired1-128 chars

The menu file's modifierGroups[].id

modifierOptionIdstringRequired1-128 chars

The menu file's options[].id

namestringRequired1-200 chars

As the customer saw it

quantityintegerRequired1-999

Per piece of the line

unitPriceintegerRequired0-10000000

Gross

amountsobjectRequired

total = itemsSubtotal − discount + deliveryFee + serviceFee + tip

Show child attributesHide child attributes

itemsSubtotalintegerRequired0-10000000

Minor units (cents)

discountintegerRequired0-10000000

Minor units (cents)

deliveryFeeintegerRequired0-10000000

Minor units (cents)

serviceFeeintegerRequired0-10000000

Minor units (cents)

tipintegerRequired0-10000000

Minor units (cents)

totalintegerRequired0-10000000

Minor units (cents)

paymentobjectRequired

cash / unpaid / amountPaid 0 (the restaurant collects), or online / paid / amountPaid = total with a reference

Show child attributesHide child attributes

methodstringRequiredcashonline

statusstringRequiredunpaidpaid

amountPaidintegerRequired0-10000000

Minor units (cents)

referencestringOptional1-200 chars

Required for online

notestringOptional0-1000 chars

deliveryInstructionsstringOptional0-1000 chars

Response

200The same order again (same externalId, identical payload); duplicate is true

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

Our order id

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

Your order id, unique per connection

statusstringRequiredValue: inProgress

Always inProgress; read the current status with GET /orders/{externalId}

receivedAtstringRequiredformat: date-time

duplicatebooleanRequired

201Received

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

Our order id

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

Your order id, unique per connection

statusstringRequiredValue: inProgress

Always inProgress; read the current status with GET /orders/{externalId}

receivedAtstringRequiredformat: date-time

duplicatebooleanRequired

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

409

STORE_OFFLINE, WEBHOOK_NOT_CONFIGURED, ORDER_CONFLICT, INVALID_TRANSITION or REQUEST_IN_PROGRESS. REQUEST_IN_PROGRESS carries Retry-After (seconds); retry with the same body.

Headers

Retry-AfterintegerOptional

Seconds to wait (REQUEST_IN_PROGRESS only)

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

500

An error; see ErrorCode

503

An error; see ErrorCode

POST/orders

cURL

curl -X POST https://management.horeca-24.de/api/partner/v1/orders \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "schemaVersion": "1",
  "externalId": "A-1001",
  "currency": "EUR",
  "type": "delivery",
  "createdAt": "2026-10-15T10:00:00Z",
  "fulfillment": {
    "mode": "scheduled",
    "requestedAt": "2026-10-15T12:30:00+02:00",
    "courier": "store"
  },
  "customer": {
    "name": "Kim Meyer",
    "phone": "+49 40 123456",
    "email": "kim@example.com",
    "address": {
      "street": "Hauptstraße",
      "streetNumber": "1",
      "zipCode": "20095",
      "city": "Hamburg",
      "countryCode": "DE",
      "extraAddressInfo": "2nd floor",
      "lat": 53.55,
      "lng": 10.0
    }
  },
  "items": [
    {
      "lineId": "l1",
      "productId": "p1",
      "name": "Margherita",
      "quantity": 2,
      "unitPrice": 1200,
      "taxRate": 7,
      "note": "well done",
      "modifiers": [
        {
          "modifierGroupId": "g1",
          "modifierOptionId": "o1",
          "name": "Cheese",
          "quantity": 1,
          "unitPrice": 150
        }
      ]
    }
  ],
  "amounts": {
    "itemsSubtotal": 2700,
    "discount": 200,
    "deliveryFee": 300,
    "serviceFee": 0,
    "tip": 0,
    "total": 2800
  },
  "payment": {
    "method": "online",
    "status": "paid",
    "amountPaid": 2800,
    "reference": "pay_8d2f"
  },
  "note": "Please ring twice",
  "deliveryInstructions": "Back building"
}'

Python

import os
import requests

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

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

payload = {
    "schemaVersion": "1",
    "externalId": "A-1001",
    "currency": "EUR",
    "type": "delivery",
    "createdAt": "2026-10-15T10:00:00Z",
    "fulfillment": {
        "mode": "scheduled",
        "requestedAt": "2026-10-15T12:30:00+02:00",
        "courier": "store",
    },
    "customer": {
        "name": "Kim Meyer",
        "phone": "+49 40 123456",
        "email": "kim@example.com",
        "address": {
            "street": "Hauptstraße",
            "streetNumber": "1",
            "zipCode": "20095",
            "city": "Hamburg",
            "countryCode": "DE",
            "extraAddressInfo": "2nd floor",
            "lat": 53.55,
            "lng": 10.0,
        },
    },
    "items": [
        {
            "lineId": "l1",
            "productId": "p1",
            "name": "Margherita",
            "quantity": 2,
            "unitPrice": 1200,
            "taxRate": 7,
            "note": "well done",
            "modifiers": [
                {
                    "modifierGroupId": "g1",
                    "modifierOptionId": "o1",
                    "name": "Cheese",
                    "quantity": 1,
                    "unitPrice": 150,
                },
            ],
        },
    ],
    "amounts": {
        "itemsSubtotal": 2700,
        "discount": 200,
        "deliveryFee": 300,
        "serviceFee": 0,
        "tip": 0,
        "total": 2800,
    },
    "payment": {
        "method": "online",
        "status": "paid",
        "amountPaid": 2800,
        "reference": "pay_8d2f",
    },
    "note": "Please ring twice",
    "deliveryInstructions": "Back building",
}

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", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.PARTNER_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "schemaVersion": "1",
    "externalId": "A-1001",
    "currency": "EUR",
    "type": "delivery",
    "createdAt": "2026-10-15T10:00:00Z",
    "fulfillment": {
      "mode": "scheduled",
      "requestedAt": "2026-10-15T12:30:00+02:00",
      "courier": "store"
    },
    "customer": {
      "name": "Kim Meyer",
      "phone": "+49 40 123456",
      "email": "kim@example.com",
      "address": {
        "street": "Hauptstraße",
        "streetNumber": "1",
        "zipCode": "20095",
        "city": "Hamburg",
        "countryCode": "DE",
        "extraAddressInfo": "2nd floor",
        "lat": 53.55,
        "lng": 10.0
      }
    },
    "items": [
      {
        "lineId": "l1",
        "productId": "p1",
        "name": "Margherita",
        "quantity": 2,
        "unitPrice": 1200,
        "taxRate": 7,
        "note": "well done",
        "modifiers": [
          {
            "modifierGroupId": "g1",
            "modifierOptionId": "o1",
            "name": "Cheese",
            "quantity": 1,
            "unitPrice": 150
          }
        ]
      }
    ],
    "amounts": {
      "itemsSubtotal": 2700,
      "discount": 200,
      "deliveryFee": 300,
      "serviceFee": 0,
      "tip": 0,
      "total": 2800
    },
    "payment": {
      "method": "online",
      "status": "paid",
      "amountPaid": 2800,
      "reference": "pay_8d2f"
    },
    "note": "Please ring twice",
    "deliveryInstructions": "Back building"
  }),
});

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',
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PARTNER_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'schemaVersion' => '1',
        'externalId' => 'A-1001',
        'currency' => 'EUR',
        'type' => 'delivery',
        'createdAt' => '2026-10-15T10:00:00Z',
        'fulfillment' => [
            'mode' => 'scheduled',
            'requestedAt' => '2026-10-15T12:30:00+02:00',
            'courier' => 'store',
        ],
        'customer' => [
            'name' => 'Kim Meyer',
            'phone' => '+49 40 123456',
            'email' => 'kim@example.com',
            'address' => [
                'street' => 'Hauptstraße',
                'streetNumber' => '1',
                'zipCode' => '20095',
                'city' => 'Hamburg',
                'countryCode' => 'DE',
                'extraAddressInfo' => '2nd floor',
                'lat' => 53.55,
                'lng' => 10.0,
            ],
        ],
        'items' => [
            [
                'lineId' => 'l1',
                'productId' => 'p1',
                'name' => 'Margherita',
                'quantity' => 2,
                'unitPrice' => 1200,
                'taxRate' => 7,
                'note' => 'well done',
                'modifiers' => [
                    [
                        'modifierGroupId' => 'g1',
                        'modifierOptionId' => 'o1',
                        'name' => 'Cheese',
                        'quantity' => 1,
                        'unitPrice' => 150,
                    ],
                ],
            ],
        ],
        'amounts' => [
            'itemsSubtotal' => 2700,
            'discount' => 200,
            'deliveryFee' => 300,
            'serviceFee' => 0,
            'tip' => 0,
            'total' => 2800,
        ],
        'payment' => [
            'method' => 'online',
            'status' => 'paid',
            'amountPaid' => 2800,
            'reference' => 'pay_8d2f',
        ],
        'note' => 'Please ring twice',
        'deliveryInstructions' => 'Back building',
    ]),
]);

$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.Body

{
  "schemaVersion": "1",
  "externalId": "A-1001",
  "currency": "EUR",
  "type": "delivery",
  "createdAt": "2026-10-15T10:00:00Z",
  "fulfillment": {
    "mode": "scheduled",
    "requestedAt": "2026-10-15T12:30:00+02:00",
    "courier": "store"
  },
  "customer": {
    "name": "Kim Meyer",
    "phone": "+49 40 123456",
    "email": "kim@example.com",
    "address": {
      "street": "Hauptstraße",
      "streetNumber": "1",
      "zipCode": "20095",
      "city": "Hamburg",
      "countryCode": "DE",
      "extraAddressInfo": "2nd floor",
      "lat": 53.55,
      "lng": 10.0
    }
  },
  "items": [
    {
      "lineId": "l1",
      "productId": "p1",
      "name": "Margherita",
      "quantity": 2,
      "unitPrice": 1200,
      "taxRate": 7,
      "note": "well done",
      "modifiers": [
        {
          "modifierGroupId": "g1",
          "modifierOptionId": "o1",
          "name": "Cheese",
          "quantity": 1,
          "unitPrice": 150
        }
      ]
    }
  ],
  "amounts": {
    "itemsSubtotal": 2700,
    "discount": 200,
    "deliveryFee": 300,
    "serviceFee": 0,
    "tip": 0,
    "total": 2800
  },
  "payment": {
    "method": "online",
    "status": "paid",
    "amountPaid": 2800,
    "reference": "pay_8d2f"
  },
  "note": "Please ring twice",
  "deliveryInstructions": "Back building"
}

Response

200

200The same order again (same externalId, identical payload); duplicate is true

{
  "orderId": "oo_0000000000000000000000000000000000000000000000000000000000000000",
  "externalId": "A",
  "status": "inProgress",
  "receivedAt": "2026-01-15T10:00:00Z",
  "duplicate": true
}

201

201Received

{
  "orderId": "oo_5c1e2d3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d",
  "externalId": "A-1001",
  "status": "inProgress",
  "receivedAt": "2026-10-15T10:00:01.214Z",
  "duplicate": false
}

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"
  }
}

409

409STORE_OFFLINE, WEBHOOK_NOT_CONFIGURED, ORDER_CONFLICT, INVALID_TRANSITION or REQUEST_IN_PROGRESS.

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

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"
  }
}

500

500An error; see ErrorCode

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

503

503An error; see ErrorCode

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