Technical Specification
Technical overview of the Pickpad integration with Toast POS platform.
Authentication
Pickpad authenticates as a Toast Partner application using machine client credentials (clientId / clientSecret) via the Toast Authentication API. Access tokens are cached and refreshed automatically before expiry.
| Detail | Value |
|---|---|
| Auth type | Machine client (TOAST_MACHINE_CLIENT) |
| Endpoint | /authentication/v1/authentication/login |
| Token caching | Until expiry (minus 30 s buffer) |
Webhook Events
Pickpad subscribes to order_updated webhook events. Toast sends the full order snapshot with every update, so any mid-process modifications (added items, voided selections, price changes) are automatically reflected without differential state tracking.
| Detail | Value |
|---|---|
| Event | order_updated |
| Payload | Full order state |
| Deduplication | Content-hash based (30 s window) |
API Endpoints Used
| API | Endpoint | Purpose |
|---|---|---|
| Authentication | POST /authentication/v1/authentication/login | Obtain access token |
| Orders | GET /orders/v2/orders/{guid} | Retrieve order details and customer info |
| Orders | PATCH /orders/v2/orders/{guid}/deliveryInfo | Update delivery state on fulfillment |
| Config | GET /config/v2/diningOptions | Resolve dining behavior (dine-in, takeout, delivery) |
| Partners | GET /partners/v1/restaurants | List partner restaurants and locations |
Entity Mapping
All Toast entities are mapped using GUID.
| Entity | Field | Usage |
|---|---|---|
| Order | order.guid | Order identifier |
| Menu item | item.guid | Dish ID and external ID |
| Menu group | itemGroup.guid | Category mapping |
| Modifier | item.guid (on modifier selection) | Modifier external ID |
| Dining option | diningOption.guid | Resolve order type |
| Restaurant | restaurantGuid | Location mapping |
| Customer | customer.guid | Customer identification |
Order Lifecycle
Order status is derived from two fields in the webhook payload:
fulfillmentStatuson selections — tracks kitchen preparation (NEW→SENT→READY)paymentStatuson checks — tracks payment state (OPEN→CLOSED)
| Webhook State | Pickpad Status |
|---|---|
Items sent to KDS (fulfillmentStatus: SENT) | In Progress |
All items prepared (fulfillmentStatus: READY) | Ready |
Paid and closed (paymentStatus: CLOSED + closedDate set) | Finished |
Order voided (voided: true) | Canceled |
For restaurants without Toast KDS, order status falls back to payment and approval status to determine the lifecycle stage.
Error Handling
- API calls use exponential-backoff retry (3 attempts on 5xx responses)
- API request timeout: 20 seconds
- Dining options are cached for 10 minutes
- Restaurant list is cached for 1 minute