Create orders

You can begin receiving orders by setting up a webhook endpoint on your server. This endpoint, referred previously as receiptOpeningUrl, should be configured to handle requests from TheFork. If a new reservation is made for a specific restaurant on TheFork (identified by the CustomerId value), we call the receiptOpeningUrl with an HTTP POST request to your system.

URL:

POST receiptOpeningUrl

HEADER:

Authorization: Bearer {ACCESS_TOKEN} : TheFork will include the following authorization header to the request where {ACCESS_TOKEN} is the access token previously sent to us
CustomerId : our UUID identifier of the restaurant
Content-Type: application/json

BODY: TheFork will send you a JSON document with the following properties

Property	Type	Default Value	Description
orderId	String	-	TheFork's UUID identifier of the order.
createdAt	String	-	ISO 8601 date with time indicating when the order was created.
updatedAt	String	`""`	ISO 8601 date with time indicating when the order was last updated.
`@deprecated` customerName	String	`""`	Use `customer.firstName` and `customer.lastName` instead. The first and last name of the customer separated by `"/"`.
`@deprecated` customerUuid	String	`""`	Use `customer.id` instead. TheFork customer UUID identifier.
customer	Object or Null	`null`	Contains details about the customer.
├─ customer.id	String	`""`	TheFork customer UUID identifier.
├─ customer.civility	String	`""`	Customer's title (e.g., `Mr`, `Ms`, `Dr`, `Ambassador`).
├─ customer.firstName	String	`""`	Customer's first name.
├─ customer.lastName	String	`""`	Customer's last name.
├─ customer.allergies	String[]	`[]`	List of customer's allergies.
├─ customer.dietaryRestrictions	String[]	`[]`	List of customer's dietary restrictions.
├─ customer.spendingBehaviour	String[]	`[]`	List of customer's spending behaviour.
├─ customer.customerRelationship	String[]	`[]`	List of customer's relationship.
├─ customer.riskLevel	String[]	`[]`	List of risks about customer.
├─ customer.otherTags	String[]	`[]`	List of customer tags manually added by restaurant
├─ customer.seatingPreferences	String[]	`[]`	List of customer's seating preferences.
└─ customer.note	String	`""`	General notes about the customer.
dateOfMeal	String	-	ISO 8601 date of the meal.
startTime	String	-	ISO 8601 date with time indicating scheduled start of the meal.
duration	Integer or Null	`null`	Expected duration of the meal in minutes.
loyaltyAmount	Integer	`0`	Discount amount in cents for TheFork loyalty "Yums" linked to the reservation (i.e. `1000` for `-10` euros).
loyaltyName	String	`""`	Discount name for TheFork loyalty "Yums".
reservationStatus	String	-	Possible values: `RECORDED`, `CONFIRMED`, `CANCELED`, `NO_SHOW`, `REQUESTED`, `REFUSED`. Main statuses: `RECORDED` (most frequent, reservation is confirmed) `CANCELED` (reservation has been canceled) `NO_SHOW` (reservation has been flagged as no-show) Secondary statuses: `REQUESTED` (waiting for restaurant action) `REFUSED` (declined by restaurant) `REJECTED` (general error)
mealStatus	String	-	Current status of the meal: `CONFIRMED` (only if restaurant uses reconfirmation tools), `ARRIVED`, `SEATED`, `PARTIALLY_ARRIVED`, `BILL`, `LEFT`.
offer	Object or Null	`null`	Details of any applied offer.
├─ offer.type	String	-	The type of offer (e.g., `presetMenu`, `promotion`).
├─ offer.name	String	-	The name of the offer.
├─ offer.discountPercentage	Number or Null	`null`	The discount percentage of the offer (`20`, `30`, `40` or `50` in case of a promotion).
├─ offer.presetMenuType	String	`""`	The type of preset menu, if type is `presetMenu`.
├─ offer.price	Number or Null	`null`	The price of the menu in the currency, in case of preset menu.
└─ offer.currency	String	-	The currency of the preset menu price.
`@deprecated` offerName	String	`""`	Use `offer.name` instead. Name of the applied offer, if any.
partySize	Integer or Null	`null`	Number of people.
prepayment	Object	`null`	Details of any prepayment made. Can be `null`.
├─ prepayment.amount	Integer	-	Amount prepaid on this reservation (deposit) in cents.
└─ prepayment.currency	String	-	Currency of the deposit.
reservationNote	String	`""`	Notes added to the reservation by customer.
reservationTags	String[]	`[]`	Tags associated with the reservation.
restaurantNote	String	`""`	Internal notes for the restaurant staff.
`@deprecated` table	String	`""`	Use `tables[].name` instead. A string representation of the assigned tables separated by `" + "`.
tables	Object[]	`[]`	An array of table names and their respective areas.
├─ tables[].name	String	-	Name of the specific table.
└─ tables[].areaName	String	`""`	Name of the area where the table is located.

Response: if the call is successful, TheFork expects your system to return an empty response with the 204 status code. If your system returns a 5xx status code, we may retry the call later.

Request example:

curl --location --request POST 'https://pos.webhook/order' \
  -H 'Authorization: Bearer your-secret' \
  -H 'Content-Type: application/json' \
  -H 'CustomerId: 849cc863-4409-4e2e-b437-9e0567b06528' \
  --data-raw '{
    "orderId": "3008d6ff-8292-43ab-b203-06ea1cf9537a",
    "createdAt": "2025-06-26T16:50:12.000+02:00",
    "updatedAt": "2025-06-26T16:55:47.000+02:00",
    "customerName": "John/Doe",
    "customerUuid": "acc9078a-6509-4342-8a1d-b6e7e7f7f124",
    "customer": {
      "id": "acc9078a-6509-4342-8a1d-b6e7e7f7f124",
      "civility": "Mr",
      "firstName": "John",
      "lastName": "Doe",
      "allergies": ["Lactose Intolerant", "Sulfites"],
      "dietaryRestrictions": ["Gluten Free", "Dairy Free"],
      "note": "Chef's cusing"
    },
    "dateOfMeal": "2025-06-26",
    "startTime": "2025-06-26T17:00:00.000+02:00",
    "duration": 90,
    "loyaltyAmount": 1000,
    "loyaltyName": "Yums",
    "reservationStatus": "RECORDED",
    "mealStatus": "ARRIVED",
    "offer": {
      "type": "presetMenu",
      "name": "quatro mani cena",
      "discountPercentage": null,
      "presetMenuType": "generic",
      "price": 99,
      "currency": "EUR"
    },
    "offerName": "quatro mani cena",
    "partySize": 2,
    "prepayment": {
      "amount": 14000,
      "currency": "EUR"
    },
    "reservationNote": "I would need a baby chair",
    "reservationTags": ["Romantic", "Birthday"],
    "restaurantNote": "CEO of Acme, Inc. Treat with care",
    "table": "T2 + 2",
    "tables": [
      {
        "name": "T2",
        "areaName": "terrasse_internal"
      },
      {
        "name": "2",
        "areaName": "indoor"
      }
    ]
  }'