Skip to main content

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​

FieldTypeRequiredDescription
idstringYesUnique order identifier
statusnumberYesOrder status (see Status Values)
locationIdstringYesLocation/station identifier
userobjectYesCustomer information
dishesarrayYesAt least one dish required
isPickupbooleanNoPickup order
isDeliverybooleanNoDelivery order
isAsapbooleanNoImmediate order (vs scheduled)
inPlacebooleanNoIn-Store order
shortNumberstringNoDisplay number shown on screen
basePricenumberNoTotal order price
weightnumberNoExpected order weight in grams
expectedPickupTimenumberNoUnix timestamp (seconds) for scheduled orders
autoCompletebooleanNoAllow automatic order completion (default: true)
autoPickpadbooleanNoAllow automatic Pickpad assignment (default: true)
stationIdstringNoTarget specific station
pickpadsRequirednumberNoNumber of Pickpad devices needed

User Fields​

FieldTypeRequiredDescription
namestringYesCustomer first name
fullNamestringNoCustomer full name
phonestringNoPhone number
emailstringNoEmail address
idstringNoCustomer identifier

Dish Fields​

FieldTypeRequiredDescription
idstringYesDish identifier
namestringYesDish name
countnumberYesQuantity
categoryIdstringYesCategory identifier
pricenumberNoPrice per item
weightnumberNoWeight per item in grams
variationstringNoSize/variant (e.g., "Large")
modifiersarrayNoList of modifiers

Modifier Fields​

FieldTypeRequiredDescription
idstringYesModifier identifier
namestringYesModifier name
countnumberYesQuantity
pricenumberNoAdditional price

Status Values​

ValueNameDescription
0NEWOrder just created
10IN_PROGRESSOrder is being prepared
20READYOrder is prepared, waiting for pickup
25PICKPADOrder placed on Pickpad device
30TAKENCustomer picked up the order
40FINISHEDOrder completed
50CANCELEDOrder canceled
tip

Setting status to 10 (IN_PROGRESS) gets the order distributed to a Pickpad right away. The exact behavior depends on the station's Distribute on status setting.

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 Pickpad 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 Pickpad 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 Pickpad, 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
}'