Sending Orders

Send orders to Pickpad through the generic webhook endpoint. Once an order comes in, it's validated, distributed to an available Pickpad device, and shown on the kitchen screen.

Endpoint

POST /distribution/webhook/generic

Authentication: API Key via x-api-key header

Request Body

{
  "id": "order-123",
  "status": 10,
  "locationId": "loc-001",
  "user": {
    "name": "John",
    "fullName": "John Doe",
    "phone": "+1234567890",
    "email": "john@example.com",
    "id": "customer-456"
  },
  "dishes": [
    {
      "id": "dish-1",
      "name": "Classic Burger",
      "count": 2,
      "price": 12.99,
      "categoryId": "cat-burgers",
      "variation": "Large",
      "weight": 350,
      "modifiers": [
        {
          "id": "mod-1",
          "name": "Extra Cheese",
          "count": 1,
          "price": 1.50
        }
      ]
    }
  ],
  "isPickup": true,
  "isDelivery": false,
  "isAsap": true,
  "inPlace": false,
  "shortNumber": "A123",
  "basePrice": 27.48,
  "weight": 700,
  "expectedPickupTime": 1712678400,
  "autoComplete": true,
  "autoPickpad": true,
  "stationId": "station-001",
  "pickpadsRequired": 1
}

Field Reference

Order Fields

Field	Type	Required	Description
id	string	Yes	Unique order identifier
status	number	Yes	Order status (see Status Values)
locationId	string	Yes	Location/station identifier
user	object	Yes	Customer information
dishes	array	Yes	At least one dish required
isPickup	boolean	No	Pickup order
isDelivery	boolean	No	Delivery order
isAsap	boolean	No	Immediate order (vs scheduled)
inPlace	boolean	No	In-Store order
shortNumber	string	No	Display number shown on screen
basePrice	number	No	Total order price
weight	number	No	Expected order weight in grams
expectedPickupTime	number	No	Unix timestamp (seconds) for scheduled orders
autoComplete	boolean	No	Allow automatic order completion (default: true)
autoPickpad	boolean	No	Allow automatic Pickpad assignment (default: true)
stationId	string	No	Target specific station
pickpadsRequired	number	No	Number of Pickpad devices needed

User Fields

Field	Type	Required	Description
name	string	Yes	Customer first name
fullName	string	No	Customer full name
phone	string	No	Phone number
email	string	No	Email address
id	string	No	Customer identifier

Dish Fields

Field	Type	Required	Description
id	string	Yes	Dish identifier
name	string	Yes	Dish name
count	number	Yes	Quantity
categoryId	string	Yes	Category identifier
price	number	No	Price per item
weight	number	No	Weight per item in grams
variation	string	No	Size/variant (e.g., "Large")
modifiers	array	No	List of modifiers

Modifier Fields

Field	Type	Required	Description
id	string	Yes	Modifier identifier
name	string	Yes	Modifier name
count	number	Yes	Quantity
price	number	No	Additional price

Status Values

Value	Name	Description
0	NEW	Order just created
10	IN_PROGRESS	Order is being prepared
20	READY	Order is prepared, waiting for pickup
25	PICKPAD	Order placed on Pickpad device
30	TAKEN	Customer picked up the order
40	FINISHED	Order completed
50	CANCELED	Order canceled

tip

Setting status to 10 (IN_PROGRESS) gets the order distributed to a Pickpad right away. The exact behavior depends on your Distribute on status setting in the dashboard.

Response

Success

{
  "accountId": "acc-123",
  "locationId": "loc-001",
  "queueId": null,
  "orderId": "order-123",
  "payload": {
    "orderId": "order-123",
    "orderStatus": 10,
    "stationId": "station-001",
    "pickpadIds": ["pad-1", "pad-2"],
    "order": { ... },
    "pickpads": [
      {
        "id": "pad-1",
        "name": "Pickpad #1",
        "stationId": "station-001"
      }
    ],
    "cluster": null
  }
}

If no pad or cluster is free (or the account is configured to always queue), queueId comes back set and pickpadIds/pickpads come back empty — the order is placed automatically once a pad frees up, and the usual distributed webhook fires at that point. See Orders Queue for how that works. If the order was routed to a cluster instead of an individual pad, cluster describes it — see Cluster Object.

Validation Error

{
  "status": 1,
  "message": "dishes - No dishes provided, user.name - name must be a string"
}

Example

curl -X POST https://pickpad-api.example.com/distribution/webhook/generic \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "id": "order-001",
    "status": 10,
    "locationId": "loc-001",
    "user": { "name": "John" },
    "dishes": [
      { "id": "d1", "name": "Burger", "count": 1, "categoryId": "cat-1" }
    ],
    "isPickup": true,
    "isAsap": true,
    "inPlace": false
  }'