Sales Management

Create a sale

Records a completed sale against an org. Use this endpoint to ingest sales from an external point-of-sale, ordering, or marketplace system into Flipdish so they appear in reporting, reconciliation, and the audit trail. Each request must include a unique x-idempotency-key header. Retries with the same key return the original response instead of producing a duplicate sale, which makes the call safe to retry on network failures.

post/salesManagement/orgs/{orgId}/sales

Request

Base URL: https://api.flipdish.co (the document declares no server; this is the origin it was published from)
URL: https://api.flipdish.co/salesManagement/orgs/{orgId}/sales
Auth: HTTP bearer

Path parameters

orgIdstring required

Organization ID in standard format

Example:org123

Headers

x-idempotency-keystring required

Unique idempotency key (GUID) to ensure the request is processed only once. If a request with the same key was already processed, the original response will be returned.

Example:123e4567-e89b-12d3-a456-426614174000

Request body

salesChannelIdstring required

Sales Channel ID in standard format

sourcestring

Free text field for partner to add their source e.g. App, ChatGPT etc

requestedFulfilmentTimestring required

The time at which the restaurant hands over responsibility of the food. ISO 8601 UTC format

requestedFulfillmentTimestring

⚠️ Deprecated — will be removed in a future release. Use requestedFulfilmentTime instead. The time at which the restaurant hands over responsibility of the food. ISO 8601 UTC format

desiredAsapboolean

True if user wants it asap. False if user wants it at a specific time. If user provides true but requestedFulfilmentTime is more than an hour away then override it to false.

dispatchType'DineIn' | 'TakeAway' | 'Collection' | 'Delivery' required

Fulfilment mode

externalIdstring

The partner/platform's own reference identifier for this sale (e.g. the marketplace's order number or the POS system's ticket ID). This is a machine-readable correlation key: Flipdish stores this value and it can be used to look up the sale using your own system's ID. It is not shown to restaurant staff by default. If displayId is omitted, externalId is used as the fallback back-of-house display label — so if externalId is a long UUID or opaque string, supplying a short displayId is strongly recommended.

displayIdstring

A short, human-readable label shown to restaurant staff in back-of-house systems (KDS, POS, receipt printouts). Unlike externalId — which is a machine-readable correlation key for partner integrations — displayId is the label staff use to identify a sale in their day-to-day workflow (e.g. #2A003). Keep it brief so it remains scannable at a glance. If omitted, externalId is used as the fallback display label.

menuIdstring required

Menu ID

menuRevisionIdstring required

Revision ID

notesstring

Notes intended for the restaurant staff / chef

metadatastring

Free text JSON for adding any additional information

Example request

{
  "salesChannelId": "sc123",
  "source": "App",
  "requestedFulfilmentTime": "2025-10-28T14:30:00Z",
  "requestedFulfillmentTime": "2025-10-28T14:30:00Z",
  "desiredAsap": true,
  "dispatchType": "Delivery",
  "externalId": "bd1ed236-ee79-11ed-a05b-0242ac12A003",
  "displayId": "2A003",
  "menuId": "123e4567-e89b-12d3-a456-426614174000",
  "menuRevisionId": "123",
  "customer": {
    "externalId": "customer_123",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Smith",
    "maskingCode": "024755255",
    "contactMaskingCode": "024755255",
    "phoneNumber": "+1234567890",
    "contactPhoneNumber": "+35312345678",
    "emailAddress": "john.smith@flipdish.com"
  },
  "delivery": {
    "notes": "Leave at door, don't ring the bell",
    "deliveredBy": "Client",
    "location": {
      "addressFields": {
        "line1": "Apartment 5",
        "line2": "123 Main Street",
        "line3": "State",
        "postCode": "12345"
      },
      "countryCode": "GB",
      "coordinates": {
        "latitude": 24.867762,
        "longitude": 67.057387
      }
    }
  },
  "dineIn": {
    "tableId": "3",
    "guests": 10
  },
  "notes": "please keep the spices minimum",
  "charges": [
    {
      "menuItemId": "123e4567-e89b-12d3-a456-426614174000",
      "itemId": "123e4567-e89b-12d3-a456-426614174000",
      "type": "Delivery",
      "amount": 2.5,
      "vat": 0.47
    }
  ],
  "discounts": [
    {
      "type": "Voucher",
      "code": "FIRST10",
      "amount": 10
    }
  ],
  "items": [
    {
      "menuItemId": "123e4567-e89b-12d3-a456-426614174000",
      "menuItemName": "Margherita Pizza",
      "quantity": 2,
      "unitPrice": 15,
      "notes": "No onions please",
      "modifierItems": [
        {
          "menuItemId": "123e4567-e89b-12d3-a456-426614174000",
          "menuItemName": "Extra Cheese",
          "quantity": 1,
          "unitPrice": 2.5,
          "notes": "Extra cheese",
          "modifierItems": []
        }
      ]
    }
  ],
  "payments": [
    {
      "type": "Sale",
      "paymentMethod": "Cash",
      "amount": 15.69,
      "description1": "Visa ****4921",
      "description2": "VM278412312",
      "paidAt": "2025-10-28T14:30:00Z"
    }
  ],
  "metadata": "{\"key\": \"value\"}"
}

Response

Sale created successfully

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.