Sales Management API

🚧

Beta

The Sales Management API is currently in beta. Endpoints may change. Contact [email protected] to request access.

Introduction

The Sales Management API is the v3.0 surface for ingesting and querying sales. Use it to:

• Push sales from an external system (POS, marketplace, kiosk, ordering platform) into Flipdish so they appear in reporting, reconciliation, and the audit trail.
• Cancel a sale when a customer or restaurant voids an order.
• Update delivery status as an order moves from kitchen to customer.
• Read sales back across an entire org using the org-wide query endpoints — no salesChannelId needed. The previous sales-channel-scoped read endpoints are deprecated; see Reading sales (deprecated) below.

📘

Related guides

• Building a POS analytics or back-office integration (forecasting, scheduling, margin)? Start with Build a POS sales analytics integration — it covers the full onboarding, menu sync, and reconciliation pipeline on top of this API.
• Building a marketplace integration that also needs menu sync, item snooze, and operations status updates? See Build a marketplace integration for the end-to-end flow covering those extra surfaces.

All paths live under https://api.flipdish.co and require Authorization: Bearer <token> (OAuth2 client-credentials). See Getting Started for the token exchange.

Concept model

📘

Don't parse or validate ID shapes

saleId, brandId, and salesChannelId are opaque strings — no format is enforced, and orgs/brands/channels created before the current naming convention may not match the common shape shown above. Compare them by exact string equality only; never assume a prefix, length, or character set.

Authentication

All Sales Management endpoints use the OAuth2 Bearer token:

curl https://api.flipdish.co/salesManagement/orgs/org123/sales \
  -H 'Authorization: Bearer <access_token>' \
  -H 'User-Agent: <your_app_name>/<version>'

Obtain the token via the client-credentials grant (see Getting Started). Send it on every request. Never send it from a browser or mobile client — server-side only.

Creating a sale

POST /salesManagement/orgs/{orgId}/sales

Records a completed sale against the org. The x-idempotency-key header is required; supply a fresh GUID (UUID v4) per logical sale. If a request with the same key was already processed, the original response is returned rather than creating a duplicate — this makes the call safe to retry on network failures.

Minimal example

curl -X POST https://api.flipdish.co/salesManagement/orgs/org123/sales \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -H 'x-idempotency-key: 11111111-1111-1111-1111-111111111111' \
  -H 'User-Agent: <your_app_name>/<version>' \
  -d '{
    "salesChannelId": "sc123",
    "requestedFulfillmentTime": "2025-10-28T14:30:00Z",
    "desiredAsap": true,
    "dispatchType": "TakeAway",
    "menuId": "123e4567-e89b-12d3-a456-426614174000",
    "menuRevisionId": "23",
    "items":     [ { "menuItemId": "12a85f64-5717-4562-b3fc-2c963f66afb5", "quantity": 1, "unitPrice": 10.00, "modifierItems": [] } ],
    "charges":   [],
    "discounts": [],
    "payments":  [ { "type": "Sale", "paymentMethod": "Cash", "amount": 10.00, "paidAt": "2025-10-28T14:30:00Z" } ]
  }'

Response:

{
  "data": {
    "saleId": "AF34FV",
    "createdAt": "2025-10-28T14:25:10Z",
    "dispatchTime": "2025-10-28T14:30:00Z"
  }
}

Full request with all fields

{
  "salesChannelId": "sc123",
  "source": "POS",
  "requestedFulfillmentTime": "2025-10-28T14:30:00Z",
  "desiredAsap": false,
  "dispatchType": "DineIn",
  "externalId": "your-platform-order-12345",
  "displayId": "2A003",
  "menuId": "123e4567-e89b-12d3-a456-426614174000",
  "menuRevisionId": "23",
  "customer": {
    "name": "Jane Smith",
    "contactPhoneNumber": "+353871234567",
    "emailAddress": "[email protected]",
    "externalId": "customer_456"
  },
  "dineIn": {
    "tableId": "12",
    "guests": 2
  },
  "notes": "Allergen note: contains nuts",
  "items": [
    {
      "menuItemId": "12a85f64-5717-4562-b3fc-2c963f66afb5",
      "quantity": 1,
      "unitPrice": 13.99,
      "notes": "No onions",
      "modifierItems": [
        { "menuItemId": "10a85f64-5717-4562-b3fc-2c963f66afb3", "quantity": 1, "unitPrice": 1.50 }
      ]
    }
  ],
  "charges":   [ { "type": "Service", "amount": 1.55 } ],
  "discounts": [ { "type": "Spot", "amount": 1.00 } ],
  "payments": [
    {
      "type": "Sale",
      "paymentMethod": "Credit",
      "amount": 16.04,
      "paidAt": "2025-10-28T14:25:00Z",
      "description1": "Visa ****4921",
      "description2": "VM278412312"
    }
  ],
  "metadata": "{\"posTerminal\":\"till-2\"}"
}

Field reference

Sale object schema

The shapes above (salesChannelId, items, charges, …) form the PublicSale object — one consistent schema used in three places:

• The request body for POST .../sales.
• The response body for every org-wide GET sale endpoint (the deprecated channel-scoped GET endpoints return the same shape).
• The sale field embedded in sale.created.v1 / sale.updated.v1 webhook events (see Sale webhook events).

This section documents every field of the nested customer, delivery, dineIn, items, charges, discounts, and payments objects. The top-level fields are covered in the field reference above.

customer

Optional. Identifies the end customer placing the sale.

contactPhoneNumber availability

contactPhoneNumber is always in E.164 format (leading +, e.g. +353871234567). Local-format numbers (with a leading 0) cannot be normalised to E.164 without a country code and are dropped.

When contactPhoneNumber IS present:

When contactPhoneNumber is ABSENT:

emailAddress availability

When emailAddress IS present:

When emailAddress is ABSENT:

delivery

Required when dispatchType is Delivery.

delivery.location

dineIn

Required when dispatchType is DineIn.

items[]

At least one item is required. Items nest recursively: a modifierItems[] entry has the exact same shape as its parent item, so any depth of modifier (e.g. pizza → size → topping → extra-cheese) is expressed as nested items rather than a separate schema.

charges[]

Required on create, but the array can be empty. Additional monetary lines beyond item prices.

discounts[]

Required on create, but the array can be empty. Discounts always apply at the sale level — there is no per-line discount. Every discount carries amount (number, >= 0) and type; whether code is required depends on type:

payments[]

Required on create, but the array can be empty — an empty array means the sale is unpaid. A refund is recorded as its own line rather than mutating the original payment: expect a Sale-type line for the original charge and a separate Refund-type line when money is returned.

Cancelling a sale

POST /salesManagement/orgs/{orgId}/sales/{saleId}/cancel

Marks an existing sale as cancelled. Cancellation is final — create a new sale if the customer reorders.

curl -X POST https://api.flipdish.co/salesManagement/orgs/org123/sales/AF34FV/cancel \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: <your_app_name>/<version>' \
  -d '{
    "salesChannelId": "sc123",
    "cancellationReason": "Cancelled by customer",
    "cancellationNotes": "Customer called to cancel — out of area"
  }'

cancellationReason is required. Allowed values: Cancelled by customer, Cancelled by restaurant, Cancelled by marketplace, Cancelled by integration partner, Cancelled by system, Other. cancellationNotes is free text (max 255 chars) and is round-tripped on the sales.cancelled.v1 webhook event.

Updating delivery status

POST /salesManagement/orgs/{orgId}/sales/{saleId}/deliveryStatus

Records a delivery state transition as the order progresses through fulfilment. Send transitions in order.

# Mark as dispatched (left kitchen with driver)
curl -X POST https://api.flipdish.co/salesManagement/orgs/org123/sales/AF34FV/deliveryStatus \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: <your_app_name>/<version>' \
  -d '{ "salesChannelId": "sc123", "status": "SALE_DISPATCHED" }'

# Mark as delivered (customer received)
curl -X POST https://api.flipdish.co/salesManagement/orgs/org123/sales/AF34FV/deliveryStatus \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: <your_app_name>/<version>' \
  -d '{ "salesChannelId": "sc123", "status": "SALE_DELIVERED" }'

status is SALE_DISPATCHED or SALE_DELIVERED. Both transitions surface in operational dashboards and downstream reporting.

Reading sales (deprecated)

🚧

Deprecated

The sales-channel-scoped read endpoints below are deprecated and have been removed from this reference — they no longer appear in the sidebar or in reference/sales-management-api.json's navigation. They remain callable for existing integrations and will keep working, but won't receive further updates. New integrations should use the org-wide query endpoints instead, which cover the same use cases without requiring a salesChannelId.

• GET /salesManagement/orgs/{orgId}/salesChannels/{salesChannelId}/sales?fromDate=YYYY-MM-DD&toDate=YYYY-MM-DD (formerly "List sales by date range") → use List sales (org-wide, full payload).
• GET /salesManagement/orgs/{orgId}/salesChannels/{salesChannelId}/sales/{saleId} (formerly "Get a sale") → use Get a sale (org-wide).

Org-wide queries (Beta)

🚧

Beta

These endpoints are currently in beta — they may change without notice.

The org-wide endpoints do not require a salesChannelId. Use them when you need to query or look up sales across all channels of an org (or scoped to one property), or when you don't know which sales channel a sale belongs to. Every org-wide list/get endpoint returns the full payload — header fields plus the nested sale object — in one call; there's no separate headers-only variant.

List sales (org-wide, full payload)

GET /sales/orgs/{orgId}/sales

Returns paginated full sale payloads across all channels of the org, sorted by creation time descending. All query parameters are optional and combinable.

# Most-recent 50 sales across the org
curl "https://api.flipdish.co/sales/orgs/org123/sales" \
  -H 'Authorization: Bearer <access_token>' \
  -H 'User-Agent: <your_app_name>/<version>'

# Last 24 hours
curl "https://api.flipdish.co/sales/orgs/org123/sales?after=2025-10-27T00:00:00Z&before=2025-10-28T00:00:00Z" \
  -H 'Authorization: Bearer <access_token>' \
  -H 'User-Agent: <your_app_name>/<version>'

Response:

{
  "pageSize": 50,
  "hasMoreRecords": true,
  "nextCursor": "<opaque token>",
  "data": [
    {
      "saleId": "AF34FV",
      "orgId": "org123",
      "brandId": "br123",
      "propertyId": "p789",
      "salesChannelId": "sc123",
      "salesChannelType": "POS",
      "externalId": "your-platform-order-12345",
      "source": "POS",
      "dispatchType": "DineIn",
      "status": "created",
      "createdAt": "2025-10-28T14:25:10Z",
      "updatedAt": "2025-10-28T14:25:10Z",
      "sale": {
        "salesChannelId": "sc123",
        "source": "POS",
        "requestedFulfillmentTime": "2025-10-28T14:30:00Z",
        "dispatchType": "DineIn",
        "menuId": "123e4567-e89b-12d3-a456-426614174000",
        "menuRevisionId": "23",
        "items": [ { "menuItemId": "12a85f64-5717-4562-b3fc-2c963f66afb5", "quantity": 1, "unitPrice": 13.99, "modifierItems": [] } ],
        "charges": [],
        "discounts": [],
        "payments": [ { "type": "Sale", "paymentMethod": "Cash", "amount": 13.99, "paidAt": "2025-10-28T14:25:00Z" } ]
      }
    }
  ]
}

Paginating: when hasMoreRecords is true, pass nextCursor as the cursor query parameter on the next request together with the same filter parameters. Cursors are not portable across different endpoints (org-wide vs. property-scoped) or different filter combinations.

List sales for a property (full payload)

GET /sales/orgs/{orgId}/properties/{propertyId}/sales

Same shape and query parameters (pageSize, cursor, after, before) as List sales (org-wide, full payload), scoped to one property.

curl "https://api.flipdish.co/sales/orgs/org123/properties/p789/sales?pageSize=100" \
  -H 'Authorization: Bearer <access_token>' \
  -H 'User-Agent: <your_app_name>/<version>'

📘

Cursor portability

Cursors are tied to both the endpoint and the filters used when they were issued — a cursor from the org-wide list isn't portable to the property-scoped list (or vice versa), and cursors aren't portable between different propertyId filters.

Response fields (org-wide header)

Every item in data above wraps a SaleHeaderResponse plus a nested sale object (the full Sale object schema):

Get a sale (org-wide)

GET /sales/orgs/{orgId}/sales/{saleId}

Returns the full projected sale for the given org and saleId without requiring a salesChannelId. Use this when you have a saleId from a webhook event and don't want to look up which sales channel it belongs to.

curl https://api.flipdish.co/sales/orgs/org123/sales/AF34FV \
  -H 'Authorization: Bearer <access_token>' \
  -H 'User-Agent: <your_app_name>/<version>'

Response — the header fields plus a nested sale object (the full Sale object schema):

{
  "saleId": "AF34FV",
  "orgId": "org123",
  "brandId": "br123",
  "propertyId": "p789",
  "salesChannelId": "sc123",
  "salesChannelType": "POS",
  "externalId": "your-platform-order-12345",
  "source": "POS",
  "dispatchType": "DineIn",
  "status": "created",
  "createdAt": "2025-10-28T14:25:10Z",
  "updatedAt": "2025-10-28T14:25:10Z",
  "sale": {
    "salesChannelId": "sc123",
    "source": "POS",
    "requestedFulfillmentTime": "2025-10-28T14:30:00Z",
    "desiredAsap": false,
    "dispatchType": "DineIn",
    "externalId": "your-platform-order-12345",
    "displayId": "2A003",
    "menuId": "123e4567-e89b-12d3-a456-426614174000",
    "menuRevisionId": "23",
    "customer": {
      "name": "Jane Smith",
      "contactPhoneNumber": "+353871234567"
    },
    "dineIn": { "tableId": "12", "guests": 2 },
    "items": [
      { "menuItemId": "12a85f64-5717-4562-b3fc-2c963f66afb5", "quantity": 1, "unitPrice": 13.99, "modifierItems": [] }
    ],
    "charges": [ { "type": "Service", "amount": 1.55 } ],
    "discounts": [],
    "payments": [
      { "type": "Sale", "paymentMethod": "Credit", "amount": 15.54, "paidAt": "2025-10-28T14:25:00Z" }
    ]
  }
}

cancelledAt is omitted here since the sale hasn't been cancelled; it appears (ISO 8601 UTC) once status is cancelled.

Webhook events

Flipdish fires sale-related webhook events for every sale created via this API. See Sale webhook events for event schemas, payload structure, and how to subscribe.

Idempotency and retries

Pre-launch checklist

• Access token obtained via client-credentials grant and stored securely server-side
• Authorization: Bearer <access_token> sent on every request
• User-Agent header set on every request
• Per-sale x-idempotency-key (fresh GUID) sent on every POST .../sales call
• externalId set on every sale for round-trip deduplication
• menuId and menuRevisionId match the published revision in use
• dispatchType, delivery, and dineIn are consistent (delivery location present when deliveredBy is Client; tableId and guests present for DineIn)
• Cancel path tested end-to-end on a sandbox sale
• Delivery status transitions tested (SALE_DISPATCHED → SALE_DELIVERED) on a sandbox sale
• Reconciler runs periodically using the org-wide list endpoint (beta)
• Webhook endpoint verifies HMAC over the raw body using a timing-safe compare
• Webhook endpoint returns 2xx within 10 seconds; heavy work is queued
• Handlers idempotent on saleId / eventId
• Re-enable logic in place if a subscription is auto-disabled

Further reading

• Getting Started — OAuth2 credential setup
• Sale webhook events — event schemas, payload structure, and how to subscribe
• Subscribe to Flipdish Events (v3) — webhook delivery contract and signature verification
• User Agents — required User-Agent format
• Build a POS sales analytics integration — full analytics pipeline: onboarding, menu sync, canonical schema mapping, App Store distribution
• Build a marketplace integration — marketplace-specific guide (menu sync, operations updates, snooze handling)
• API Reference (v3.0) — every v3 endpoint and model