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.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"
      }
    ]
  }'