Dojo Parties API

openapi: 3.2.0
info:
  title: EPOS Data API (REST) Parties API
  version: '1.0'
  description: 'REST contract that an external POS/EPOS system implements so Dojo products can

    fetch and update commerce entities (Orders, Tables, Areas, Parties, Reservations)

    and record payments.'
servers:
- url: https://your-epos.example.com
  description: 'The EPOS Data REST API has no shared base URL: each EPOS provider hosts the

    endpoints on their own domain and registers them against that base via

    `PUT /epos/integrations/rest`. The placeholder `https://your-epos.example.com`

    is illustrative — replace with your own publicly reachable HTTPS URL.'
tags:
- name: Parties
paths:
  /v1/parties:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePartyRequest'
      tags:
      - Parties
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Party'
          description: Party successfully created.
        4XX:
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
        5XX:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
      operationId: v1-post-parties
      summary: Create party
      description: 'Create a new party in the POS domain. Capability: `CreateParty`'
      parameters:
      - $ref: '#/components/parameters/WaiterId'
      - $ref: '#/components/parameters/DojoRequestingProduct'
      - $ref: '#/components/parameters/DeviceId'
      - $ref: '#/components/parameters/DeviceType'
  /v1/parties/{partyId}:
    parameters:
    - name: partyId
      description: The ID of the party to retrieve.
      schema:
        type: string
      in: path
      required: true
    - $ref: '#/components/parameters/WaiterId'
    - $ref: '#/components/parameters/DojoRequestingProduct'
    - $ref: '#/components/parameters/DeviceId'
    - $ref: '#/components/parameters/DeviceType'
    get:
      tags:
      - Parties
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Party'
          description: Ok
        4XX:
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
        5XX:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
      operationId: v1-get-parties-partyId
      summary: Get party
      description: 'Retrieves a specific party. Capability: `GetPartyById`'
    put:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePartyRequest'
      tags:
      - Parties
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Party'
          description: Party successfully updated.
        4XX:
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
        5XX:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
      operationId: v1-put-parties-partyId
      summary: Update party
      description: 'Sets the party''s details to those provided. Capability: `UpdatePartyById`'
    delete:
      tags:
      - Parties
      responses:
        '200':
          description: .
        4XX:
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
        5XX:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
      operationId: v1-delete-parties-partyId
      summary: Delete party
      description: 'Deletes a specific party. Capability: `DeletePartyById`'
  /v1/parties/search:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchPartiesRequest'
        required: true
      tags:
      - Parties
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedPartiesResponse'
          description: Ok
        4XX:
          description: Client Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
        5XX:
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EPOSError'
      operationId: v1-search-parties
      summary: Search parties
      description: 'Searches through parties on the EPOS.

        By default, this endpoint should exclude parties with `endTime` set, including them only when `completedOnly: true`.

        Capability: `SearchParties`'
      parameters:
      - $ref: '#/components/parameters/WaiterId'
      - $ref: '#/components/parameters/DojoRequestingProduct'
      - $ref: '#/components/parameters/DeviceId'
      - $ref: '#/components/parameters/DeviceType'
components:
  parameters:
    WaiterId:
      in: header
      name: waiter-id
      required: false
      schema:
        type: string
      example: '42'
      description: The ID of the waiter making the request, if known
    DeviceType:
      in: header
      name: device-type
      required: false
      schema:
        type: string
      example: Dojo Terminal
      description: The device making the request, if known
    DojoRequestingProduct:
      name: dojo-requesting-product
      in: header
      required: false
      schema:
        type: string
      example: Order&Pay
      description: The dojo product making the request, if known.
    DeviceId:
      name: device-id
      in: header
      required: false
      schema:
        type: string
      example: tm_sandbox_65c5fe8a104a1222b2d8b968
      description: The ID of the device making the request, if known
  schemas:
    PagedPartiesResponse:
      title: PagedOrder
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Party'
          readOnly: false
          x-stoplight:
            id: ou7je7f6bizdg
        before:
          type: string
          x-stoplight:
            id: jutkpidtbhr6q
        after:
          type: string
          x-stoplight:
            id: vwlxjfle0yxqt
      x-stoplight:
        id: bjkxvbo62zl42
    EPOSError:
      title: EPOSError
      type: object
      required:
      - errorType
      properties:
        debugMessage:
          type: string
        traceId:
          type: string
        errorType:
          $ref: '#/components/schemas/EPOSErrorType'
    Cursor:
      title: Cursor
      description: A cursor for use in pagination.
      type: object
      properties:
        limit:
          description: The maximum number of results to be returned in a single page.
          maximum: 100
          type: integer
          x-stoplight:
            id: l5tzcxdo5qbt1
        before:
          description: A cursor for use in pagination for the previous page. before and after are mutually exclusive. Only one of these may be used.
          type: string
          x-stoplight:
            id: 8vxj9sdmbby14
        after:
          description: A cursor for use in pagination for the next page. before and after are mutually exclusive. Only one of these may be used.
          type: string
          x-stoplight:
            id: 1jsibbqp1zdti
      x-stoplight:
        id: m8ixmhyvzw3oo
    CreatePartyRequest:
      title: Create Party Request
      description: Request payload made from Dojo -> EPOS Partner to create a new party in the EPOS domain. Note that Dojo will always provide _all_ known fields.
      properties:
        name:
          title: Name
          type: string
        covers:
          title: Covers
          type: integer
        tableIds:
          title: Table IDs
          type: array
          items:
            type: string
          minLength: 1
        status:
          title: Status
          type: string
        startTime:
          title: Start time
          type: string
          format: date-time
          description: When the party was seated. ISO8601 formatted, ms precise.
        expectedEndTime:
          title: Expected end time
          type: string
          format: date-time
          description: When the party is expected to leave, if known. ISO8601 formatted, ms precise.
        hostNotes:
          title: Host notes
          type: string
        guestRequests:
          title: Guest requests
          type: string
        reservationId:
          title: Reservation ID
          type: string
        deposit:
          $ref: '#/components/schemas/PartyDeposit'
        dojoPartyId:
          title: For reference. The Dojo API party ID.
          type: string
        dojoReservationId:
          title: For reference. The Dojo API reservation ID.
          type: string
      required:
      - startTime
      - tableIds
      - dojoPartyId
      example:
        name: Martin B.
        covers: 4
        tableIds:
        - table-01-001
        - table-01-002
        startTime: '2024-08-12T09:30:00.000Z'
        expectedEndTime: '2024-08-12T11:00:00.000Z'
        guestRequests: nut allergy; gluten intolerance; please could we have a table next to a window?
        hostNotes: called ahead to notify kitchen of dietary requirements - confirm upon arrival
        reservationId: reservation-2024-08-12-0028
        deposit:
          totalAmount:
            value: 5000
            currencyCode: GBP
    PartyDeposit:
      title: Party Deposit
      description: Information about payments captured pre-arrival to secure the reservation.
      required:
      - totalAmount
      - paymentIntentIds
      properties:
        totalAmount:
          $ref: '#/components/schemas/Money'
          description: 'The deposit value of the party at the time it was seated. The common

            flow for this field is that it is set by the Dojo VQ&B RMS shortly

            after a party referring to a reservation (with a deposit) is

            created.'
        description:
          type: string
          description: 'A human-readable description of the deposit. This may be used to

            describe the reason for the deposit, or any other relevant information.'
          example: Sunday Lunch deposit - 4 covers
        paymentIntentIds:
          description: 'List of payment-intents that were captured to make the deposit.

            Some may have been either partially or wholly refunded.


            May not be edited by the EPOS partner.'
          type: array
          items:
            type: string
    Money:
      title: Money
      required:
      - value
      - currencyCode
      type: object
      properties:
        value:
          format: int64
          description: The amount in the minor unit, for example '100' for 1.00 GBP.
          type: integer
        currencyCode:
          description: Three-letter currency code in ISO 4217 alpha-3 format. Currently this accepts `GBP` and `EUR`.
          maxLength: 10
          minLength: 1
          type: string
      example:
        value: 1000
        currencyCode: GBP
      x-stoplight:
        id: c9op7zec1txu2
    UpdatePartyRequest:
      title: Update Party Request
      description: 'The representation of a customer or group of customers _currently_

        seated at/across a set of tables.'
      required:
      - dojoPartyId
      - startTime
      - status
      - tableIds
      type: object
      properties:
        dojoPartyId:
          description: The Dojo API party ID
          type: string
        name:
          title: Name
          description: The human-readable name, typically the name of the lead guest.
          type: string
        covers:
          title: Covers
          description: The number of covers this party occupies.
          type: integer
        tableIds:
          title: Table IDs
          description: The set of tables this party is currently sat across.
          minItems: 1
          type: array
          items:
            type: string
        status:
          title: Status
          description: "An arbitrary description of the party's current status - typically \nused to show where in their journey the party is, such as \n\"partially arrived\", \"ordered\" or \"paying\"/\"paid\"."
          minLength: 1
          type: string
        startTime:
          format: date-time
          title: Start time
          description: 'The time the party was seated. ISO8601 formatted, millisecond

            precision.'
          type: string
        expectedEndTime:
          format: date-time
          title: Expected end time
          description: 'The time the party is expected to depart, if known. ISO8601

            formatted, millisecond precision.'
          type: string
        endTime:
          format: date-time
          title: Actual end time
          description: 'The time the party actually departed. ISO8601 formatted, millisecond

            precision.'
          type: string
        hostNotes:
          title: Host notes
          description: Host-written notes about the party. Not surfaced to the Guest(s).
          type: string
        guestRequests:
          title: Guest requests
          description: "Guest-written requests for the party. Surfaced to & editable by the \nGuest(s). May not be edited by the EPOS partner, as this may contain\ndietary requirements set by the Guest."
          type: string
        deposit:
          $ref: '#/components/schemas/PartyDeposit'
      example:
        startTime: '2024-08-12T09:30:00.000Z'
        status: Ordered
        tableIds:
        - table-01-001
        - table-01-002
    EPOSErrorType:
      type: string
      enum:
      - NotFound
      - UnexpectedError
      - InvalidRequest
      - Conflict
    SearchPartiesRequest:
      description: ''
      type: object
      properties:
        cursor:
          $ref: '#/components/schemas/Cursor'
        completedOnly:
          description: ''
          type: boolean
        tableId:
          description: ''
          type: string
    Party:
      title: Party
      description: 'The representation of a customer or group of customers _currently_

        seated at/across a set of tables.'
      required:
      - id
      - startTime
      - status
      - tableIds
      type: object
      properties:
        id:
          title: ID
          description: "The EPOS-internal ID for this party. Must be globally unique within \nthe EPOS' domain."
          type: string
        name:
          title: Name
          description: The human-readable name, typically the name of the lead guest.
          type: string
        covers:
          title: Covers
          description: The number of covers this party occupies.
          type: integer
        tableIds:
          title: Table IDs
          description: The set of tables this party is currently sat across.
          minItems: 1
          type: array
          items:
            type: string
        status:
          title: Status
          description: "An arbitrary description of the party's current status - typically \nused to show where in their journey the party is, such as \n\"partially arrived\", \"ordered\" or \"paying\"/\"paid\"."
          minLength: 1
          type: string
        startTime:
          format: date-time
          title: Start time
          description: 'The time the party was seated. ISO8601 formatted, millisecond

            precision.'
          type: string
        expectedEndTime:
          format: date-time
          title: Expected end time
          description: 'The time the party is expected to depart, if known. ISO8601

            formatted, millisecond precision.'
          type: string
        endTime:
          format: date-time
          title: Actual end time
          description: 'The time the party actually departed. ISO8601 formatted, millisecond

            precision.'
          type: string
        hostNotes:
          title: Host notes
          description: Host-written notes about the party. Not surfaced to the Guest(s).
          type: string
        guestRequests:
          title: Guest requests
          description: "Guest-written requests for the party. Surfaced to & editable by the \nGuest(s). May not be edited by the EPOS partner, as this may contain\ndietary requirements set by the Guest."
          type: string
        reservationId:
          title: Reservation ID
          description: "If reservations are implemented & this party has an associated \nreservation, the EPOS-internal ID of the reservation this party \ncorresponds to."
          type: string
        deposit:
          $ref: '#/components/schemas/PartyDeposit'
      example:
        id: party-2024-08-12-0001
        startTime: '2024-08-12T09:30:00.000Z'
        status: Ordered
        tableIds:
        - table-01-001
        - table-01-002