Sale webhook events

Overview

The sale.* event family fires for every sale recorded on Flipdish — regardless of channel (POS, kiosk, web, marketplace, or API). The full sale object is embedded in the event payload, so no follow-up GET is required.

Events

sale.created.v1

Fires when a sale is first recorded. The data.sale field carries the complete PublicSale object at the moment of creation: items, modifiers, charges, discounts, payments, customer, delivery/dine-in details, and menu reference. See Sale object schema for a field-by-field breakdown of every nested object (customer, delivery, dineIn, items, charges, discounts, payments).

{
  "eventType": "sale.created.v1",
  "eventId": "01HXYZ...",
  "eventCreatedAt": "2025-10-28T14:00:00.000Z",
  "data": {
    "orgId": "org123",
    "brandId": "br123",
    "propertyId": "p123",
    "salesChannelId": "sc123",
    "salesChannelType": "UberEats",
    "source": "App",
    "saleId": "3N356",
    "sale": {
      "dispatchType": "Delivery",
      "externalId": "sale-external-123",
      "displayId": "2A003",
      "menuId": "123e4567-e89b-12d3-a456-426614174000",
      "menuRevisionId": "123",
      "customer": { ... },
      "items": [ ... ],
      "charges": [ ... ],
      "discounts": [ ... ],
      "payments": [ ... ]
    }
  }
}

📘

Sale-level identifiers: externalId vs displayId

The data.sale object carries two distinct identifier fields:

Field	Audience	Purpose
data.sale.externalId	Machines / developers	Your platform's opaque order reference (e.g. a marketplace order UUID). Stored by Flipdish and usable as a lookup key. Never shown to staff by default.
data.sale.displayId	Humans — kitchen staff, receipts	Short, human-readable label (max 15 chars) printed on receipts and shown on KDS screens. If omitted, Flipdish falls back to externalId as the display label — so if externalId is a long UUID, also supply a short displayId.

There is also data.sale.customer.externalId, which identifies the customer in your system — entirely separate from the sale-level externalId. See Sale object schema for full field details.

sale.updated.v1

Fires when a sale's content changes materially — items added or removed, charges or discounts modified. The embedded sale reflects the post-update state.

sale.status.updated.v1

A unified status event covering POS kitchen states, delivery states, and cancellation in a single discriminated union.

Status values: SALE_CANCELLED, SALE_PREPARED_BY_KITCHEN, SALE_DISPATCHED, SALE_ON_THE_WAY, SALE_DELIVERED.

📘

externalId on status events

sale.status.updated.v1 does not carry a sale sub-object (it only signals a lifecycle state change). externalId is therefore absent from status events. If you need the external ID for a given saleId, correlate via the org-wide GET endpoint.

Webhook body structure

All sale.* webhook deliveries share the same outer envelope:

data fields

The following fields appear inside data for all sale.* events:

Subscribing

Subscribe to sale.* events via the Webhook Service API or the Flipdish portal. See Subscribe to Flipdish Events (v3) for the full delivery contract, headers, and signature verification.

Related

• Subscribe to Flipdish Events (v3) — delivery contract and signature verification
• Sales Management API — full PublicSale schema, creating/cancelling sales, org-wide queries