openapi: 3.0.3
info:
  title: TheFork B2B Customers Orders API
  description: TheFork B2B API lets restaurants and groups integrate with TheFork Management (TFM) platform. It supports designing custom booking flows, creating and managing reservations with meal date, party size, and customer data, presenting preset menus, accessing personalized guest data such as allergies, dietary restrictions, and seating preferences, and retrieving guest reviews. The API is fronted by a Kong gateway and uses a single API version across all endpoints; breaking changes introduce a new version with a six-month deprecation window. Authentication uses the Auth0 OAuth 2.0 client credentials flow to obtain a bearer access token (audience https://api.thefork.io). Specifications are derived from the public developer portal at https://docs.thefork.io.
  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/manager/v1
  description: Production
security:
- OAuth2ClientCredentials: []
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:
    Offer:
      type: object
      properties:
        type:
          type: string
        name:
          type: string
        discount:
          type: number
        price:
          type: integer
          description: Price in the smallest currency unit (cents).
    ReservationStatus:
      type: string
      enum:
      - RECORDED
      - CONFIRMED
      - CANCELED
      - NO_SHOW
      - REQUESTED
      - REFUSED
    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'
    Table:
      type: object
      properties:
        name:
          type: string
          example: T12
        areaName:
          type: string
          example: Terrace
    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
    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.
    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
    Error:
      type: object
      properties:
        status:
          type: integer
        message:
          type: string
  responses:
    TooManyRequests:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid API key or bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    OAuth2ClientCredentials:
      type: oauth2
      description: Auth0 OAuth 2.0 client credentials flow. Exchange client_id and client_secret for a bearer token at https://auth.thefork.io/oauth/token with audience https://api.thefork.io. Tokens expire after 8600 seconds.
      flows:
        clientCredentials:
          tokenUrl: https://auth.thefork.io/oauth/token
          scopes: {}