TheFork Orders API

openapi: 3.2.0
info:
  title: TheFork POS Orders API
  description: TheFork POS API enables point-of-sale providers to integrate their systems with TheFork Management (TFM) platform and synchronize reservations and orders.
  version: v1
  contact:
    name: TheFork Integrations
    email: integrations@thefork.com
    url: https://docs.thefork.io/
  termsOfService: https://docs.thefork.io/pdf/LaFourchette-Partners-API-Licence-2.pdf
servers:
- url: https://api.thefork.io/pos/v1
  description: Production (POS provider callbacks to TheFork)
tags:
- name: Orders
  description: Open and close point-of-sale orders tied to reservations.
paths:
  /orders:
    post:
      tags:
      - Orders
      summary: Open Order
      description: Called by TheFork to the POS provider's configured receipt opening URL when a reservation is seated, instructing the POS to open an order for the reservation. The POS responds with 204 on success; TheFork may retry on 5xx errors.
      operationId: openOrder
      parameters:
      - name: CustomerId
        in: header
        required: true
        description: The restaurant's UUID identifier.
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            examples:
              openOrder:
                summary: Open order for a seated reservation
                value:
                  orderId: 2c1f7e90-1a2b-4c3d-8e9f-0a1b2c3d4e5f
                  createdAt: '2026-06-20T20:35:00Z'
                  reservationStatus: CONFIRMED
                  partySize: 4
                  startTime: '2026-06-20T20:30:00Z'
                  customer:
                    id: cus_55ab
                    firstName: Camille
                    lastName: Durand
                    allergies:
                    - peanuts
                  tables:
                  - name: T12
                    areaName: Terrace
      responses:
        '204':
          description: Order accepted. Empty body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /orders/{orderId}/close:
    post:
      tags:
      - Orders
      summary: Close Order
      description: Close an order on payment and send the final order details (total amount and currency) back to TheFork so the reservation can be marked LEFT.
      operationId: closeOrder
      parameters:
      - name: orderId
        in: path
        required: true
        description: TheFork's UUID for the order.
        schema:
          type: string
          format: uuid
      - name: X-Api-Key
        in: header
        required: true
        description: POS provider API key.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderClose'
            examples:
              closeOrder:
                summary: Close order on payment
                value:
                  total:
                    amount: 12500
                    currency: EUR
                  closedAt: '2026-06-20T22:10:00Z'
      responses:
        '204':
          description: Order closed. Empty body.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    OrderClose:
      type: object
      required:
      - total
      properties:
        total:
          $ref: '#/components/schemas/Money'
        closedAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the order was closed.
    Error:
      type: object
      properties:
        status:
          type: integer
        message:
          type: string
    Offer:
      type: object
      properties:
        type:
          type: string
        name:
          type: string
        discount:
          type: number
        price:
          type: integer
          description: Price in the smallest currency unit (cents).
    Order:
      type: object
      required:
      - orderId
      - createdAt
      - reservationStatus
      - partySize
      - startTime
      properties:
        orderId:
          type: string
          format: uuid
          description: TheFork's UUID for the order.
          example: 2c1f7e90-1a2b-4c3d-8e9f-0a1b2c3d4e5f
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the order was opened.
          example: '2026-06-20T20:35:00Z'
        reservationStatus:
          $ref: '#/components/schemas/ReservationStatus'
        partySize:
          type: integer
          description: Number of guests.
          example: 4
        startTime:
          type: string
          format: date-time
          description: Scheduled meal start time (ISO 8601).
          example: '2026-06-20T20:30:00Z'
        customer:
          $ref: '#/components/schemas/Customer'
        prepayment:
          $ref: '#/components/schemas/Money'
        offer:
          $ref: '#/components/schemas/Offer'
        tables:
          type: array
          items:
            $ref: '#/components/schemas/Table'
    Money:
      type: object
      description: A monetary amount with currency.
      properties:
        amount:
          type: integer
          description: Amount in the smallest currency unit (cents).
          example: 12500
        currency:
          type: string
          description: ISO 4217 currency code.
          example: EUR
    Customer:
      type: object
      properties:
        id:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        allergies:
          type: array
          items:
            type: string
        dietaryRestrictions:
          type: array
          items:
            type: string
    ReservationStatus:
      type: string
      enum:
      - RECORDED
      - CONFIRMED
      - CANCELED
      - NO_SHOW
      - REQUESTED
      - REFUSED
    Table:
      type: object
      properties:
        name:
          type: string
          example: T12
        areaName:
          type: string
          example: Terrace
  responses:
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid API key or bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key issued by TheFork for POS API v1.
    BearerToken:
      type: http
      scheme: bearer
      description: Bearer token presented by TheFork on calls to the POS provider.