Graphql schema documentation

link GraphQL Schema definition

Overview

Welcome to tyllPOS’s GraphQL API!

tyllPOS’s GraphQL API is a tool to help customers integrate tyllPOS’s functionality with their own applications and workflows.

To begin, you’ll need to use the credentials of the user who has access to tyllPOS Hub.

  1. Sign up and get your credentials.
  2. Use these credentials with the addSession API to obtain a token.
  3. Use this token in any future API requests

If you want to know more details about our API, please review our documentation at:

https://docs.tyllpos.com/

Service endpoint

The tyllPOS API’s base endpoint is: https://api.tyllpos.com/graphql

Authentication

All requests to the APIs must be authenticated, that’s why you first need a user account from tyllPOS’s Hub Site.

Adds a user session and receives a token

addSession mutation

Using a console client

curl "$YOUR_API_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation f($input: AddSessionInput!) {
      addSession(input: $input) {
        token
      }
    }",
    "variables": "{
      \"input\": {
        \"email\": \"jdoe@example.com\",
        \"password\": \"PASSWORD\"
      }
    }"
  }'

In the previous example, please replace $YOUR_API_URL with service endpoint. The email and password that you need to use are the same that you use to login in our Hub Solution

Response sample

{
  "data": {
    "addSession": {
      "token": "..."
    }
  }
}

From now on, you must use the given token to execute queries, mutations. So, whenever you see $YOUR_AUTH_TOKEN use the token value instead.

Organizations

Retrieve the organization list

organizations query

Using a console client

curl "$YOUR_API_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUR_AUTH_TOKEN" \
  -d '{
    "query": "query organizations {
      organizations {
        id
        name
      }
    }"
  }'

Response sample

{
  "data": {
    "organizations": [
      {
        "name": "McDonald's",
        "id": "d65d246e-2e1f-4a49-b5f5-1cf60ce85f3d"
      }
    ]
  }
}

Organization

Retrieve the details for the given organization

organization query

Using a console client

curl "$YOUR_API_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUR_AUTH_TOKEN" \
  -d '{"query":
    "query organization {
      organization(id: \"d65d246e-2e1f-4a49-b5f5-1cf60ce85f3d\") {
        id
        name
        members {
         firstName
         lastName
         email
        }
        children {
          entries {
            name
          }
        }
      }
    }"
  }'

Response sample

{
  "data": {
    "organization": {
      "name": "McDonald's",
      "members": [
        {
          "lastName": "Dach",
          "firstName": "Alanna",
          "email": "kariane2011@kovacek.net0"
        },
        {
          "lastName": "Vladbob",
          "firstName": "Bob",
          "email": "tyllbob@mailinator.com"
        }
      ],
      "id": "d65d246e-2e1f-4a49-b5f5-1cf60ce85f3d",
      "children": {
        "entries": [
          {
            "name": "Southeast"
          },
          {
            "name": "Southwest"
          }
        ]
      }
    }
  }
}

Add Organization Unit

addOrganizationUnit mutation

mutation addOrganizationUnit($input: AddOrganizationUnitInput!){
  addOrganizationUnit(input: $input) {
    id
    name
  }
}

Response sample

{
  "data": {
    "addOrganizationUnit": {
      "name": "Foo's Kitchen",
      "id": "4c972684-9e07-4101-8fcd-5442f80690d4"
    }
  }
}

Update Organization information

mutation updateLocation($input: UpdateLocationInput!, $organizationUnitId: UUID!){
  updateLocation(input: $input, organizationUnitId: $organizationUnitId) {
    id
    name
  }
}

Delete organization

mutation deleteOrganizationUnit($id: UUID!) {
  deleteOrganizationUnit(id: $id) {
    id
  }
}

Profile

Retrieve the details for the current logged user

profile query

Using a console client

curl "$YOUR_API_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $YOUR_AUTH_TOKEN" \
  -d '{"query":
    "query profile {
      profile {
        firstName
        lastName
        email
        phone
      }
    }"
  }'

Response sample

{
  "data": {
    "profile": {
      "phone": "+1 (205) 555-1212",
      "lastName": "Vladbob",
      "firstName": "Bob",
      "email": "tyllbob@mailinator.com"
    }
  }
}

Changelogs

Retrieve changelogs

changelogs query

Response sample

{
  "data": {
    "changelog": {
      "entries": [
        {
          "title": "Hub v1.0 is out!",
          "id": "d65d246e-2e1f-4a49-b5f5-1cf60ce85f3d",
          "body": "..."
        }
      ]
    }
  }
}

NOTE: There is no way to add a changelog via Mutation, this action needs to be done via our Admin interface.

Announcements

Retrieve announcements

announcements query

NOTE: There is no way to add an announcement via Mutation, this action needs to be done via our Admin interface.

Taxes

Retrieve taxes

query TaxFee($organizationUnitId: UUID!) {
  organization(id: $organizationUnitId) {
    id
    charges {
      entries {
        id
        name
        isPercent
        beforeTax
        amount
        type
        organizationUnit {
          id
          name
        }
      }
      totalEntries
    }
  }
}

Add a Tax

add tax

Update a Tax

update tax

Delete a Tax

delete tax

Fees

Retrieve fees

query TaxFee($organizationUnitId: UUID!) {
  organization(id: $organizationUnitId) {
    id
    charges {
      entries {
        id
        name
        isPercent
        beforeTax
        amount
        type
        organizationUnit {
          id
          name
        }
      }
      totalEntries
    }
  }
}

Add a Fee

add fee

Update a Fee

update fee

Delete a Fee

delete fee

Users

Retrieve list of members

query Members($organization: UUID!) {
  organization(id: $organization) {
    id
    members {
      id
      firstName
      lastName
      email
      disabled
      phone
    }
  }
}

Make a request to reset password

mutation f($input: RequestResetInput!) {
  requestReset(input: $input) {
    message
  }
}

Reset user’s password

mutation f($input: ResetPasswordInput!) {
  resetPassword(input: $input) {
    message
  }
}

Add a user

mutation f($input: AddUserInput!) {
  addUser(input: $input) {
    token
  }
}

Confirm email

mutation confirmEmail($token: String!) {
  confirmEmail(token: $token)
}

Edit a user

mutation editUser($input: EditUserInput!) {
  editUser(input: $input) {
    id
    firstName
    lastName
    sex
    phone
    email
    ssn
    homeAddress {
      line1
      line2
      city
      state
      zip
    }
  }
}

Resend e-mail confirmation

mutation resendEmailConfirmationEmail($userId: UUID!) {
  resendEmailConfirmationEmail(userId: $userId) {
    id
  }
}

Confirm phone number

mutation confirmPhone($phoneNumber: String!, $code: String!) {
  confirmPhone(phoneNumber: $phoneNumber, code: $code)
}

Update Password

mutation UpdatePassword($input: UpdatePasswordInput!) {
  updatePassword(input: $input)
}

Invitations

Retrieve invitations

invitations query

query Invitations($rootOrganizationUnitId: UUID!) {
  invitations(rootOrganizationUnitId: $rootOrganizationUnitId) {
    id
    inviteeEmail
    organizationUnits {
      id
      name
    }
  }
}

Create Invitations

mutation CreateInvitations($input: CreateInvitationsInput!) {
  createInvitations(input: $input) {
    rootOrganizationUnitId
  }
}

Re-send invitation e-mail

mutation resendInvitationEmail($invitationId: UUID!, $rootOrganizationUnitId: UUID!) {
  resendInvitationEmail(invitationId: $invitationId, rootOrganizationUnitId: $rootOrganizationUnitId) {
    id
  }
}

Delete pending invitation

mutation deletePendingInvitation($invitationId: UUID!) {
  deletePendingInvitation(invitationId: $invitationId) {
    inviteeEmail
  }
}

Devices

Retrieve devices

query Devices($organization: UUID!) {
  organization(id: $organization) {
    id
    name
    devices {
      id
      deviceId
      name
      state
      status
      pairingStatus
      allowTips
      lastSeenAt
    }
  }
}

Associate Device

mutation associateDevice($deviceId: UUID!, $organizationUnitId: UUID!, $name: String!){
  associateDevice(deviceId: $deviceId, organizationUnitId: $organizationUnitId, name: $name) {
    id
    name
    allowTips
    lastSeenAt
  }
}

Update Device

mutation updateDevice($input: UpdateDeviceInput!){
  updateDevice(input: $input) {
    id
    name
    allowTips
    lastSeenAt
  }
}

Dissociate device

mutation startDeviceDissociation($deviceId: UUID!, $organizationUnitId: UUID!){
  startDeviceDissociation(deviceId: $deviceId, organizationUnitId: $organizationUnitId) {
    id
  }
}

Billing

Retrieve Billing information

query Billing($organization: UUID!) {
  organization(id: $organization) {
    id
    name
    billing {
      ein
      accountHolder {
        address {
          line1
          line2
          city
          state
          zip
        }
        dob
        email
        firstName
        lastName
        ssn
        phone
      }
      bankAccount {
        accountName
        accountNumber
        bankName
        swiftCode
        routingNumber
      }
      billingAddress {
        line1
        line2
        city
        state
        zip
      }
      billingEmail
      billingPhone
      billingTerm
      billingTermStartTime
      billingTermEndTime
    }
  }
}

Update Billing information

mutation updateBilling($input: UpdateBillingInput!, $organizationUnitId: UUID!){
  updateBilling(input: $input, organizationUnitId: $organizationUnitId) {
    id
  }
}

Update Payment information

mutation updatePayment($input: UpdatePaymentInput!, $organizationUnitId: UUID!){
  updatePayment(input: $input, organizationUnitId: $organizationUnitId) {
    id
  }
}

Report

Retrieve report

query Report($input: ReportInput!) {
  report(input: $input) {
    averageTicketSize
    totalOrders
    totalRefundedAmount
    totalRefundedOrders
    totalTipAmount
    orders {
      id
      orderNumber
      amount
      amountRefunded
      timePlaced
      refunded
      entities {
        name
        quantity
        type
      }
    }
    salesForGraph {
      amount
      endDate
      startDate
    }
    salesForTable {
      entityName
      type
      grossSales
      menuName
      quantitySold
      categoryName
    }
    drawerCountsForTable {
      timestamp
      terminalName
      total
      activeMember
    }
    authenticationEvents {
      device
      id
      loginTime
      managerOverride
      member
    }
  }
}

Export report

mutation exportReport($input: ReportInput!){
  exportReport(input: $input)
}

Pricing

Assign menu prices

assignMenuPrices mutation

mutation assignMenuPrices($input: AssignMenuPricesInput!) {
  assignMenuPrices (input: $input) {
    id
    menuId
    organizationUnitId
    modifierPrices {
      modifierId
      amount
    }
    itemOptionPrices {
      itemOptionId
      amount
    }
  }
}

Query variables sample

{
  "input": {
    "menuId": "1f1d5593-9e12-464a-839b-830388d78b19",
    "organizationUnitId": "7c1a1fb1-c267-41f2-84c7-a9b3870a5800",
    "modifierPrices": [
      {
        "modifierId": "925d45b5-8222-4819-8290-7ea0bc537c72",
        "amount": "12.3"
      }
    ],
    "itemOptionPrices": [
      {
        "itemOptionId": "f45eda2a-45c3-4d11-9942-9eaeccfb0524",
        "amount": "21.3"
      }
    ]
  }
}

Response sample

{
  "data": {
    "assignMenuPrices": {
      "organizationUnitId": "7c1a1fb1-c267-41f2-84c7-a9b3870a5800",
      "modifierPrices": [
        {
          "modifierId": "925d45b5-8222-4819-8290-7ea0bc537c72",
          "amount": "12.3"
        }
      ],
      "menuId": "1f1d5593-9e12-464a-839b-830388d78b19",
      "itemOptionPrices": [
        {
          "itemOptionId": "f45eda2a-45c3-4d11-9942-9eaeccfb0524",
          "amount": "21.3"
        }
      ],
      "id": "30060399-afd3-4f4e-8328-6297f2afa564"
    }
  }
}

Location Item Combos

query LocationModifiers($locationId: UUID!, $menuId: UUID!) {
  organization(id: $locationId) {
    id
    menu(id: $menuId) {
      id
      title
      latestSnapshot{
        id
        selections {
          id
          title
          description
          disabled
          type
          itemOptions {
            id
            itemId
            name
            price(locationId: $locationId)
            assignedBy: priceAssignedBy(locationId: $locationId) {
              id
              name
            }
            modifierGroups {
              id
              name
              modifiers {
                modifierId: id
                name
                modifierGroupModifierId
                price(locationId: $locationId)
                assignedBy: priceAssignedBy(locationId: $locationId) {
                  id
                  name
                }
                priceComplete(locationId: $locationId)
              }
            }
          }
          comboOptions {
            id
            comboId
            name
            price(locationId: $locationId)
            assignedBy: priceAssignedBy(locationId: $locationId) {
              id
              name
            }
            itemGroups {
              id
              name
              items {
                itemId: id
                title
                itemOptions {
                  itemOptionId: id
                  name
                  itemGroupItemOptionId
                  price(locationId: $locationId)
                  assignedBy: priceAssignedBy(locationId: $locationId) {
                    id
                    name
                  }
                  modifierGroups {
                    modifierGroupId: id
                    name
                    modifiers {
                      modifierId: id
                      name
                      modifierGroupModifierId
                      itemGroupItemOptionId
                      price(locationId: $locationId)
                      assignedBy: priceAssignedBy(locationId: $locationId) {
                        id
                        name
                      }
                      priceComplete(locationId: $locationId)
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Location modifiers

query LocationModifiers($locationId: UUID!, $menuId: UUID!) {
  organization(id: $locationId) {
    id
    menu(id: $menuId) {
      id
      title
      latestSnapshot {
        id
        modifiers {
          id
          name
          price(locationId: $locationId)
          assignedBy: priceAssignedBy(locationId: $locationId) {
            id
            name
          }
          priceComplete(locationId: $locationId)
          disabled
        }
      }
    }
  }
}

Menus

Retrieve menus per organization

  query MenuManagerQuery($id: UUID!, $pagination: PaginationInput, $filter: MenuFilterInput) {
    organization(id: $id) {
      id
      parentId
      name
      menus(pagination: $pagination, filter: $filter) {
        entries {
          id
          title
          description
          updatedAt
          disabled
          version
          status
          organizations {
            id
            name
            type
            parentId
            ancestors {
              id
              name
              type
              parentId
            }
          }
        }
        totalEntries
      }
    }
  }

Retrieve menu details

query MenuQuery($id: UUID!, $pagination: PaginationInput) {
  menu(id: $id) {
    id
    title
    description
    updatedAt
    disabled
    version
    status
    enforceMenuTimes
    availabilityStart
    availabilityEnd
    organizations {
      id
      name
    }
    categories(pagination: $pagination) {
      entries {
        id
        title
        description
        disabled
        color
        imageUrl
        gridPosition {
          x
          y
        }
        cards {
          id
          disabled
          color
          imageUrl
          gridPosition {
            x
            y
          }
          menuItem {
            id
            title
            description
            itemOptions {
              id
              itemId
              name
              modifierGroups {
                id
                name
                preselected
                isRequired
                maxSelections
                minSelections
                unpaginatedModifiers {
                  id
                  name
                }
              }
            }
          }
          menuCombo {
            id
            title
            description
            comboOptions {
              id
              comboId
              name
              itemGroups {
                id
                name
                isMultipleSelectionAllowed
                maxSelections
                minSelections
                itemGroupItems {
                  id
                  itemId
                  itemGroupId
                }
                itemOptions {
                  id
                  name
                }
                items {
                  id
                  title
                  itemOptions {
                    id
                    name
                  }
                }
              }
            }
          }
        }
      }
      totalEntries
    }
  }
}

Retrieve menu modifiers

query ModifierQuery($id: UUID!, $filter: ModifierFilterInput!, $pagination: PaginationInput) {
  menu(id: $id) {
    id
    modifiers (filter: $filter, pagination: $pagination) {
      entries {
        id
        name
        disabled
        menuItems {
          title
        }
        menuCombos {
          title
        }
      }
      totalEntries
    }
  }
}

Applied menus

query AppliedMenusQuery($id: UUID!, $pagination: PaginationInput) {
  organization(id: $id) {
    id
    appliedMenus(pagination: $pagination) {
      entries {
        id
        title
        updatedAt
        version
        disabled
        menuAppliedAt(locationId: $id) {
          id
          name
        }
        priceStatus: pricesComplete(locationId: $id)
      }
      totalEntries
    }
  }
}

Add a Menu

mutation addMenu($input: AddMenuInput!){
  addMenu(input: $input) {
    id
    title
    description
    availabilityEnd
    availabilityStart
  }
}

Update a Menu

mutation updateMenu($id: UUID!, $input: UpdateMenuInput!){
  updateMenu(id: $id, input: $input) {
    id
    title
    description
    availabilityEnd
    availabilityStart
  }
}

Delete Menus

mutation deleteMenus($orgId: UUID!, $ids: [UUID]!) {
  deleteMenus(ids: $ids, organizationUnitId: $orgId) {
    ids
  }
}

Disable Menus

mutation disableMenus($ids: [UUID]!, $organizationUnitId: UUID!){
  disableMenus(ids: $ids, organizationUnitId: $organizationUnitId) {
    ids
  }
}

Enable Menus

mutation enableMenus($ids: [UUID]!, $organizationUnitId: UUID!){
  enableMenus(ids: $ids, organizationUnitId: $organizationUnitId) {
    ids
  }
}

Save a Menu

mutation saveMenu($id: UUID!){
  saveMenu(id: $id) {
    id
  }
}

Apply menu to locations

mutation applyMenuToLocations($menuId: UUID!, $ids: [UUID!]!) {
  applyMenuToLocations(menuId: $menuId, ids: $ids) {
    ids
    menuId
  }
}

Menu Items

Add Menu Item

mutation addMenuItem($input: AddMenuItemInput!) {
  addMenuItem(input: $input) {
    id
  }
}

Update Menu Item

mutation updateMenuItem($input: UpdateMenuItemInput!) {
  updateMenuItem(input: $input) {
    id
  }
}

Enable Menu Item

mutation enableMenuItem($id: UUID!) {
  enableMenuItem(id: $id){
    id
  }
}

Disable Menu Item

mutation disableMenuItem($id: UUID!) {
  disableMenuItem(id: $id){
    id
  }
}

Delete Menu Item

mutation deleteMenuItem($id: UUID!) {
  deleteMenuItem(id: $id){
    id
  }
}

Menu Combos

Add Menu Combo

mutation addMenuCombo($input: MenuComboInput!) {
  addMenuCombo(input: $input) {
    id
  }
}

Update Menu Combo

mutation updateMenuCombo($input: UpdateMenuComboInput!) {
  updateMenuCombo(input: $input) {
    id
  }
}

Enable Menu Combo

mutation enableMenuCombo($id: UUID!) {
  enableMenuCombo(id: $id){
    id
  }
}

Disable Menu Combo

mutation disableMenuCombo($id: UUID!) {
  disableMenuCombo(id: $id){
    id
  }
}

Delete Menu Combo

mutation deleteMenuCombo($id: UUID!) {
  deleteMenuCombo(id: $id){
    id
  }
}

Menu Modifiers

Add Menu Modifier

mutation addMenuModifier($input: AddMenuModifierInput!) {
  addMenuModifier(input: $input){
    id
  }
}

Update Menu Modifier

mutation updateMenuModifier($id: UUID!, $input: UpdateMenuModifierInput!) {
  updateMenuModifier(id: $id, input: $input){
    id
  }
}

Enable Menu Modifier

mutation enableMenuModifier($id: UUID!) {
  enableMenuModifier(id: $id){
    id
  }
}

Disable Menu Modifier

mutation disableMenuModifier($id: UUID!) {
  disableMenuModifier(id: $id){
    id
  }
}

Delete Menu Modifier

mutation deleteMenuModifier($id: UUID!) {
  deleteMenuModifier(id: $id){
    id
  }
}

Menu Categories

Add Menu Category

mutation addMenuCategory($input: AddCategoryInput!) {
  addMenuCategory(input: $input) {
    id
  }
}

Update Menu Category

mutation updateMenuCategory($input: CategoryInput!) {
  updateMenuCategory(input: $input) {
    id
    title
    description
    gridPosition {
      x
      y
    }
  }
}

Switch Menu Category positions

mutation switchCategoryPosition($id1: UUID!, $id2: UUID!) {
  switchCategoryPositions(id1: $id1, id2: $id2) {
    firstCategory {
      gridPosition {
        x
        y
      }
    }
    secondCategory {
      gridPosition {
        x
        y
      }
    }
  }
}

Delete Menu Categories

mutation deleteMenuCategories($ids: [UUID!]!, $organizationUnitId: UUID!) {
  deleteMenuCategories(ids: $ids, organizationUnitId: $organizationUnitId) {
    ids
  }
}

Enable Menu Categories

mutation enableMenuCategories($ids: [UUID!]!, $organizationUnitId: UUID!) {
  enableMenuCategories(ids: $ids, organizationUnitId: $organizationUnitId) {
    ids
  }
}

Disable Menu Categories

mutation disableMenuCategories($ids: [UUID!]!, $organizationUnitId: UUID!) {
  disableMenuCategories(ids: $ids, organizationUnitId: $organizationUnitId) {
    ids
  }
}

Feedback

Add a suggestion

mutation f($input: AddSuggestionFormInput!) {
  addSuggestionForm(input: $input) {
    id
  }
}

Add a comment

mutation f($input: AddGeneralCommentFormInput!) {
  addGeneralCommentForm(input: $input) {
    id
  }
}

Add a bug report

mutation f($input: AddBugReportFormInput!) {
  addBugReportForm(input: $input) {
    id
  }
}

Contact

mutation f($input: AddContactFormInput!) {
  addContactForm(input: $input) {
    id
  }
}

NOTE: Our Hub solution does not show this section for now, but it can accessed via our Admin interface.