---
openapi: 3.0.0
info:
  title: 20Tabs API
  description: 'The 20Tabs API gives your app access to the 20Tabs point of sale:
    read an organization''s catalog, customers, receipts and closings, place orders,
    and process payments through your own payment methods. Your app obtains access
    via the OAuth 2.0 authorization code flow when an organization installs it; all
    other endpoints expect the resulting access token as a Bearer token in the Authorization
    header.'
  contact:
    name: 20Tabs
    email: dev@20tabs.nl
    url: https://20tabs.nl
  version: v1
security:
- oauth2: []
tags:
- name: organization
  description: The organization your app is installed in
- name: daily_closings
  description: Daily closings with cashflow and revenue breakdowns
- name: monthly_closings
  description: Monthly closings aggregating the daily closings of a month
- name: receipts
  description: Receipts with their items, payments and outstanding amount
- name: orders
  description: Order placement and submission
- name: customers
  description: The organization's customer base
- name: products
  description: The organization's product catalog
- name: tax_rates
  description: Tax rates configured for the organization
- name: category_of_revenues
  description: Categories used to break down revenue in closings and reports
- name: payments
  description: Payments recorded on receipts
- name: payment_methods
  description: Payment methods your app registers on the organization's registers
- name: modals
  description: Modals your app shows to users on the register
- name: tasks
  description: Tasks your app creates for the organization's backoffice
- name: subscription
  description: Your app's subscription for the organization
- name: oauth
  description: OAuth 2.0 authorization code flow
paths:
  "/v1/daily_closings/{id}":
    get:
      summary: Retrieve a daily closing
      description: Returns a daily closing, including the cashflow per payment method,
        the revenue broken down per category of revenue, employee, device and voucher,
        and any voucher redemptions.
      parameters:
      - in: path
        name: id
        description: Unique identifier of the daily closing
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Retrieve a daily closing
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/DailyClosing"
      tags:
      - daily_closings
      operationId: getV1DailyClosingsId
      security:
      - oauth2:
        - daily_closing:read
  "/v1/organization":
    get:
      summary: Retrieve the organization
      description: Returns the organization this subscription is authorized for, including
        its business profile and contact details.
      responses:
        '200':
          description: Retrieve the organization
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Organization"
      tags:
      - organization
      operationId: getV1Organization
      security:
      - oauth2:
        - organization:read
  "/v1/monthly_closings/{id}":
    get:
      summary: Retrieve a monthly closing
      description: Returns a monthly closing with the combined cashflow and revenue
        of all daily closings in the month, together with the individual daily closings
        it covers.
      parameters:
      - in: path
        name: id
        description: Unique identifier of the monthly closing
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Retrieve a monthly closing
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/MonthlyClosing"
      tags:
      - monthly_closings
      operationId: getV1MonthlyClosingsId
      security:
      - oauth2:
        - monthly_closing:read
  "/v1/payment_methods":
    get:
      summary: List payment methods
      description: Returns the payment methods registered by your app that have not
        been archived.
      responses:
        '200':
          description: List payment methods
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/PaymentMethod"
      tags:
      - payment_methods
      operationId: getV1PaymentMethods
      security:
      - oauth2:
        - payment/methods:read
    post:
      summary: Register a payment method
      description: Registers a payment method that becomes available on the organization's
        registers. When a user pays with it, 20Tabs calls your app's webhook with
        the `receipt_id` and `payment_method_id`; your app processes the transaction
        and records the result by creating a payment.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/postV1PaymentMethods"
        required: true
      responses:
        '201':
          description: Register a payment method
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PaymentMethod"
      tags:
      - payment_methods
      operationId: postV1PaymentMethods
      security:
      - oauth2:
        - payment/methods:write
  "/v1/payment_methods/{id}":
    patch:
      summary: Update a payment method
      description: Updates a payment method registered by your app.
      parameters:
      - in: path
        name: id
        description: Unique identifier of the payment method
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/patchV1PaymentMethodsId"
        required: true
      responses:
        '200':
          description: Update a payment method
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/PaymentMethod"
      tags:
      - payment_methods
      operationId: patchV1PaymentMethodsId
      security:
      - oauth2:
        - payment/methods:write
    delete:
      summary: Archive a payment method
      description: Archives a payment method registered by your app, removing it from
        the organization's registers. Existing payments keep referring to it.
      parameters:
      - in: path
        name: id
        description: Unique identifier of the payment method
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '204':
          description: Archive a payment method
      tags:
      - payment_methods
      operationId: deleteV1PaymentMethodsId
      security:
      - oauth2:
        - payment/methods:write
  "/v1/payments":
    post:
      summary: Create a payment
      description: Records a payment on a receipt, for example after your app has
        processed a transaction through one of its registered payment methods. All
        pending items on the receipt are marked as paid.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/postV1Payments"
        required: true
      responses:
        '201':
          description: Create a payment
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Payment"
      tags:
      - payments
      operationId: postV1Payments
      security:
      - oauth2:
        - payment:write
  "/v1/receipts":
    get:
      summary: List receipts for a daily closing
      description: Returns all receipts that were settled in the given daily closing,
        including their items and payments.
      parameters:
      - in: query
        name: daily_closing_id
        description: Unique identifier of the daily closing
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: List receipts for a daily closing
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Receipt"
      tags:
      - receipts
      operationId: getV1Receipts
      security:
      - oauth2:
        - receipt:read
  "/v1/receipts/{id}":
    get:
      summary: Retrieve a receipt
      description: Returns a receipt with its items, payments, customer and outstanding
        amount.
      parameters:
      - in: path
        name: id
        description: Unique identifier of the receipt
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: Retrieve a receipt
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Receipt"
      tags:
      - receipts
      operationId: getV1ReceiptsId
      security:
      - oauth2:
        - receipt:read
  "/v1/receipts/{receipt_id}/appendices":
    post:
      summary: Append an appendix to a receipt
      description: Adds a line of text to the receipt's appendices. Appendices are
        printed at the bottom of the receipt, for example a reference to a transaction
        in your system.
      parameters:
      - in: path
        name: receipt_id
        description: Unique identifier of the receipt
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/postV1ReceiptsReceiptIdAppendices"
        required: true
      responses:
        '201':
          description: Append an appendix to a receipt
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Receipt"
      tags:
      - receipts
      operationId: postV1ReceiptsReceiptIdAppendices
      security:
      - oauth2:
        - receipt:write
  "/v1/customers":
    get:
      summary: List customers
      description: Returns all active customers of the organization.
      responses:
        '200':
          description: List customers
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Customer"
      tags:
      - customers
      operationId: getV1Customers
      security:
      - oauth2:
        - customer:read
    post:
      summary: Create a customer
      description: Creates a customer owned by your app. If a customer with the given
        email address already exists, no customer is created; the existing customer
        is returned with a `303 See Other` status and a `Location` header pointing
        to it.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/postV1Customers"
        required: true
      responses:
        '201':
          description: Create a customer
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Customer"
      tags:
      - customers
      operationId: postV1Customers
      security:
      - oauth2:
        - customer:write
  "/v1/customers/{id}":
    patch:
      summary: Update a customer
      description: Updates the given attributes of a customer; attributes that are
        not included in the request keep their current value.
      parameters:
      - in: path
        name: id
        description: Unique identifier of the customer
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/patchV1CustomersId"
        required: true
      responses:
        '200':
          description: Update a customer
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Customer"
      tags:
      - customers
      operationId: patchV1CustomersId
      security:
      - oauth2:
        - customer:write
    put:
      summary: Replace a customer
      description: Replaces all attributes of a customer with the given values; attributes
        that are not included in the request are cleared.
      parameters:
      - in: path
        name: id
        description: Unique identifier of the customer
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/putV1CustomersId"
        required: true
      responses:
        '200':
          description: Replace a customer
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Customer"
      tags:
      - customers
      operationId: putV1CustomersId
      security:
      - oauth2:
        - customer:write
  "/v1/orders":
    post:
      summary: Create and submit an order
      description: Creates an order and submits it for preparation. Provide exactly
        one of `receipt_id`, `customer_id`, `table_id`, `group_id` or `employee_id`
        to determine the receipt the order is placed on; a new receipt is opened when
        none is open yet. Each item either references a product by `product_id` or
        `product_barcode` — inheriting its price, tax rate and preparation settings
        — or describes a free-form item with `description` and `price`. Items can
        carry nested sub-items, for example product options.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/postV1Orders"
        required: true
      responses:
        '201':
          description: Create and submit an order
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Order"
      tags:
      - orders
      operationId: postV1Orders
      security:
      - oauth2:
        - order:write
  "/v1/orders/submissions":
    post:
      summary: Submit an order
      description: Submit an order, the order will be posted to the receipt it belongs
        to triggeren all configured callbacks in the organization.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/postV1OrdersSubmissions"
        required: true
      responses:
        '201':
          description: Submit an order
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Order"
      tags:
      - orders
      operationId: postV1OrdersSubmissions
      security:
      - oauth2:
        - order:write
  "/v1/products":
    get:
      summary: List products
      description: Returns all products in the organization's catalog that are not
        archived
      responses:
        '200':
          description: List products
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/Product"
      tags:
      - products
      operationId: getV1Products
      security:
      - oauth2:
        - product:read
    post:
      summary: Create a product
      description: Creates a product owned by your app. If a product with the given
        PLU already exists, no product is created; the existing product is returned
        with a `303 See Other` status and a `Location` header pointing to it.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/postV1Products"
        required: true
      responses:
        '201':
          description: Create a product
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Product"
      tags:
      - products
      operationId: postV1Products
      security:
      - oauth2:
        - product:write
  "/v1/products/find":
    get:
      summary: Find a product by PLU
      description: Looks up a single product by its PLU or barcode.
      parameters:
      - in: query
        name: plu
        description: PLU or barcode of the product
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Find a product by PLU
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Product"
      tags:
      - products
      operationId: getV1ProductsFind
      security:
      - oauth2:
        - product:read
  "/v1/tax_rates":
    get:
      summary: List tax rates
      description: Returns all tax rates configured for the organization.
      responses:
        '200':
          description: List tax rates
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/TaxRate"
      tags:
      - tax_rates
      operationId: getV1TaxRates
      security:
      - oauth2:
        - tax_rate:read
  "/v1/category_of_revenues":
    get:
      summary: List categories of revenue
      description: Returns all categories of revenue configured for the organization,
        including archived ones.
      responses:
        '200':
          description: List categories of revenue
          content:
            application/json:
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/CategoryOfRevenue"
      tags:
      - category_of_revenues
      operationId: getV1CategoryOfRevenues
      security:
      - oauth2:
        - category_of_revenue:read
    post:
      summary: Create a category of revenue
      description: Creates a category of revenue owned by your app. Assign products
        and payments to it to break down revenue in closings and reports.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/postV1CategoryOfRevenues"
        required: true
      responses:
        '201':
          description: Create a category of revenue
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/CategoryOfRevenue"
      tags:
      - category_of_revenues
      operationId: postV1CategoryOfRevenues
      security:
      - oauth2:
        - category_of_revenue:write
  "/v1/modals":
    post:
      summary: Show a modal
      description: Displays a modal in the user's session on the register, for example
        to confirm a payment your app is processing.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/postV1Modals"
        required: true
      responses:
        '201':
          description: Show a modal
      tags:
      - modals
      operationId: postV1Modals
  "/v1/tasks":
    post:
      summary: Create a task
      description: Creates a task for the organization, shown in the taskmanager until
        it is completed. Use tasks to ask users to take action in your app, for example
        to resolve missing data.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/postV1Tasks"
        required: true
      responses:
        '201':
          description: Create a task
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/Task"
      tags:
      - tasks
      operationId: postV1Tasks
  "/v1/subscription":
    patch:
      summary: Update the subscription
      description: Updates the state of your app's subscription for this organization.
        Mark the subscription as active once your app has finished setting up.
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/patchV1Subscription"
        required: true
      responses:
        '200':
          description: Update the subscription
      tags:
      - subscription
      operationId: patchV1Subscription
    delete:
      summary: Cancel the subscription
      description: Deletes your app's subscription for this organization, immediately
        revoking its access and refresh tokens.
      responses:
        '204':
          description: Cancel the subscription
      tags:
      - subscription
      operationId: deleteV1Subscription
  "/oauth/authorize":
    get:
      tags:
      - oauth
      summary: Request authorization
      description: Starts the authorization code flow. Renders a consent page in the
        user's browser on the organization's domain; after the user approves, the
        browser is redirected to `redirect_uri` with `code`, `state` and `subscription_id`
        query parameters.
      operationId: getOauthAuthorize
      servers:
      - url: https://{organization}.20tabs.app
        description: The organization's own 20Tabs domain
        variables:
          organization:
            default: demo
            description: Subdomain of the organization installing the app
      security: []
      parameters:
      - name: client_id
        in: query
        required: true
        schema:
          type: string
        description: Client id of the registered app
      - name: redirect_uri
        in: query
        required: true
        schema:
          type: string
          format: uri
        description: Callback URL; must be allowed by the registered app
      - name: state
        in: query
        required: false
        schema:
          type: string
        description: Opaque value echoed back on the redirect
      - name: read_only
        in: query
        required: false
        schema:
          type: boolean
        description: Request only the read scopes of the app, if the app supports
          read-only installs
      responses:
        '200':
          description: Consent page (HTML)
          content:
            text/html:
              schema:
                type: string
        '302':
          description: Redirect to `redirect_uri` with `code`, `state` and `subscription_id`
        '422':
          description: Unknown client id or redirect URI not allowed
  "/oauth/token":
    post:
      tags:
      - oauth
      summary: Exchange an authorization code or refresh token for an access token
      description: Exchanges the authorization `code` for an access token.
      operationId: postOauthToken
      servers:
      - url: https://api.20tabs.app
        description: The 20Tabs API domain
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                  - authorization_code
                  - refresh_token
                  description: Defaults to an authorization code exchange when omitted
                code:
                  type: string
                  description: Authorization code received on the redirect (authorization_code
                    grant)
                redirect_uri:
                  type: string
                  format: uri
                  description: Must match the redirect URI used in the authorization
                    request
                client_secret:
                  type: string
                  description: Client secret of the registered app (required for an
                    authorization code exchange)
                refresh_token:
                  type: string
                  description: Refresh token (refresh_token grant)
      responses:
        '200':
          description: Access token issued
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OauthToken"
        '401':
          description: Invalid code, code verifier or client credentials
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OauthError"
        '422':
          description: Redirect URI mismatch
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OauthError"
  "/oauth/refresh":
    post:
      tags:
      - oauth
      summary: Refresh an access token
      description: Exchanges a refresh token for a new access and refresh token pair.
      operationId: postOauthRefresh
      servers:
      - url: https://api.20tabs.app
        description: The 20Tabs API domain
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - refresh_token
              properties:
                refresh_token:
                  type: string
      responses:
        '200':
          description: Access token refreshed
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OauthToken"
        '401':
          description: Invalid refresh token
          content:
            application/json:
              schema:
                "$ref": "#/components/schemas/OauthError"
servers:
- url: https://api.20tabs.app
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'OAuth 2.0 authorization code flow. The resulting access token
        is sent as `Authorization: Bearer <token>`.'
      flows:
        authorizationCode:
          authorizationUrl: https://{organization_domain}.20tabs.app/oauth/authorize
          tokenUrl: https://api.20tabs.app/oauth/token
          scopes:
            organization:read: Read organization details
            daily_closing:read: Read daily closings
            monthly_closing:read: Read monthly closings
            receipt:read: Read receipts
            receipt:write: Update receipts
            customer:read: Read customers
            customer:write: Create and update customers
            order:write: Create orders
            product:read: Read products
            product:write: Create products
            payment:write: Create payments
            payment/methods:read: Read payment methods
            payment/methods:write: Manage payment methods
            tax_rate:read: Read tax rates
            category_of_revenue:read: Read categories of revenue
            category_of_revenue:write: Create categories of revenue
          refreshUrl: https://api.20tabs.app/oauth/refresh
  schemas:
    DailyClosing:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the daily closing.
        cashflow:
          type: object
          properties:
            amounts:
              type: object
              description: Amounts received per payment method.
          required:
          - amounts
          description: Cashflow generated during the day, per payment method.
        revenue:
          type: object
          properties:
            per_category_of_revenue:
              type: array
              items:
                "$ref": "#/components/schemas/Revenue"
              description: Revenue per category of revenue.
            per_employee:
              type: array
              items:
                "$ref": "#/components/schemas/Revenue"
              description: Revenue per employee.
            per_device:
              type: array
              items:
                "$ref": "#/components/schemas/Revenue"
              description: Revenue per device.
            per_voucher:
              type: array
              items:
                "$ref": "#/components/schemas/Revenue"
              description: Revenue per voucher.
          required:
          - per_category_of_revenue
          - per_employee
          - per_device
          - per_voucher
          description: Revenue generated during the day, broken down per dimension.
        voucher_redemptions:
          type: array
          items:
            "$ref": "#/components/schemas/VoucherRedemption"
          description: Vouchers redeemed during the day.
        created_at:
          type: string
          format: date-time
          description: Time the daily closing was created.
        for_date:
          type: string
          format: date
          description: Trading date the daily closing covers.
      required:
      - id
      - cashflow
      - revenue
      - voucher_redemptions
      - created_at
      - for_date
      description: The financial closing of a single trading day.
    Revenue:
      type: object
      properties:
        amount:
          allOf:
          - "$ref": "#/components/schemas/Money"
          description: Revenue amount.
        tax_rate:
          allOf:
          - "$ref": "#/components/schemas/TaxRate"
          description: Tax rate of the category of revenue.
        category_of_revenue:
          allOf:
          - "$ref": "#/components/schemas/CategoryOfRevenue"
          description: Category of revenue the revenue belongs to, when broken down
            per category of revenue.
        employee:
          allOf:
          - "$ref": "#/components/schemas/Employee"
          description: Employee who generated the revenue, when broken down per employee.
        device:
          allOf:
          - "$ref": "#/components/schemas/Device"
          description: Device the revenue was generated on, when broken down per device.
        voucher:
          allOf:
          - "$ref": "#/components/schemas/Voucher"
          description: Voucher the revenue was generated with, when broken down per
            voucher.
      required:
      - amount
      description: Revenue generated within one segment of a breakdown.
    Money:
      type: object
      properties:
        value:
          type: string
          description: Decimal amount as a string, for example "10.50".
        currency:
          type: string
          description: ISO 4217 currency code, for example "EUR".
      required:
      - value
      - currency
      description: A monetary amount in a specific currency.
    TaxRate:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the tax rate.
        name:
          type: string
          description: Name of the tax rate.
        percentage:
          type: string
          description: Tax percentage, for example 21.0.
        label:
          type: string
          description: Human-readable label combining the name and percentage.
      required:
      - id
      - name
      - percentage
      - label
      description: A tax rate configured for the organization.
    CategoryOfRevenue:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the category of revenue.
        name:
          type: string
          description: Name of the category of revenue.
        archived:
          type: boolean
          description: Whether the category of revenue has been archived.
      required:
      - id
      - name
      - archived
      description: A category used to break down revenue in closings and reports.
    Employee:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the employee.
        name:
          type: string
          description: Name of the employee.
        created_at:
          type: string
          format: date-time
          description: Time the employee was added to the organization.
      required:
      - id
      - name
      - created_at
      description: An employee of the organization.
    Device:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the device.
        uuid:
          type: string
          description: UUID of the device.
        name:
          type: string
          description: Name of the device.
        kind:
          type: string
          description: 'Device type: register, customer_facing_display, preparation_display,
            kiosk, backoffice_display, network_printer, or bluetooth_printer.'
        subtype:
          type: string
          description: Secondary classification within a kind (e.g. register or handheld
            for registers; preparation or runner for preparation displays).
        locale:
          type: string
          description: Locale the device operates in, for example `nl` or `en`.
        register_network:
          type: boolean
          description: Whether this register participates in the shared register network.
        external_buzzer:
          type: boolean
          description: Whether an external buzzer is connected.
        primary_payment_method:
          allOf:
          - "$ref": "#/components/schemas/PaymentMethod"
          description: Primary payment method configured on the device.
        secondary_payment_method:
          allOf:
          - "$ref": "#/components/schemas/PaymentMethod"
          description: Secondary payment method configured on the device.
        quickselect_page_id:
          type: integer
          format: int64
          description: Unique identifier of the quickselect page shown on the device.
        preparation_location_ids:
          type: array
          items:
            type: string
          description: Unique identifiers of the preparation locations the device
            prepares.
        monitoring_preparation_location_ids:
          type: array
          items:
            type: string
          description: Unique identifiers of the preparation locations the device
            monitors.
        settings:
          type: string
          description: Kind-specific settings hash.
        archived:
          type: boolean
          description: Whether the device has been archived.
      required:
      - id
      - uuid
      - name
      - kind
      - subtype
      - locale
      - register_network
      - external_buzzer
      - primary_payment_method
      - secondary_payment_method
      - quickselect_page_id
      - preparation_location_ids
      - monitoring_preparation_location_ids
      - settings
      - archived
      description: A device of the organization, such as a register, display or printer.
    PaymentMethod:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the payment method.
        name:
          type: string
          description: Display name shown to users on the register.
        online:
          type: boolean
          description: Whether the payment is processed online (`true`) or in store
            (`false`).
        tap_to_pay:
          type: boolean
          description: Whether the payment method uses Tap to Pay.
        operator_reference:
          type: string
          description: Reference that helps 20Tabs users identify the payment method
            in your system.
        required_data:
          type: object
          description: Fields the user must fill in when paying with this method.
        created_at:
          type: string
          format: date-time
          description: Time the payment method was registered.
        updated_at:
          type: string
          format: date-time
          description: Time the payment method was last updated.
      required:
      - id
      - name
      - online
      - tap_to_pay
      - operator_reference
      - required_data
      - created_at
      - updated_at
      description: A payment method registered by your app, available on the organization's
        registers.
    Voucher:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the voucher.
        name:
          type: string
          description: Name of the voucher.
      required:
      - id
      - name
      description: A voucher sold and redeemed through the organization.
    VoucherRedemption:
      type: object
      properties:
        voucher:
          allOf:
          - "$ref": "#/components/schemas/Voucher"
          description: Voucher that was redeemed.
        amount:
          allOf:
          - "$ref": "#/components/schemas/Money"
          description: Amount redeemed.
      required:
      - voucher
      - amount
      description: A redemption of a voucher.
    Organization:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the organization.
        name:
          type: string
          description: Name of the organization.
        display_name:
          type: string
          description: Trading name shown on receipts and customer-facing screens.
        email:
          type: string
          description: Contact email address of the organization.
        phone:
          type: string
          description: Contact phone number of the organization.
        first_name:
          type: string
          description: First name of the contact person.
        last_name:
          type: string
          description: Last name of the contact person.
        coc:
          type: string
          description: Chamber of Commerce (KvK) registration number.
        vat:
          type: string
          description: VAT identification number.
        street:
          type: string
          description: Street of the business address.
        building:
          type: string
          description: Name of the building of the business address.
        building_number:
          type: string
          description: Building number of the business address.
        postal_code:
          type: string
          description: Postal code of the business address.
        city:
          type: string
          description: City of the business address.
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country code of the business address.
        locale:
          type: string
          description: Default locale of the organization, for example `nl` or `en`.
        created_at:
          type: string
          format: date-time
          description: Time the organization joined 20Tabs.
      required:
      - id
      - name
      - display_name
      - email
      - phone
      - first_name
      - last_name
      - coc
      - vat
      - street
      - building
      - building_number
      - postal_code
      - city
      - country_code
      - locale
      - created_at
      description: An organization using 20Tabs.
    MonthlyClosing:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the monthly closing.
        cashflow:
          type: object
          properties:
            amounts:
              type: object
              description: Amounts received per payment method.
          required:
          - amounts
          description: Combined cashflow of all daily closings in the month, per payment
            method.
        revenue:
          type: object
          properties:
            per_category_of_revenue:
              type: array
              items:
                "$ref": "#/components/schemas/Revenue"
              description: Revenue per category of revenue.
            per_employee:
              type: array
              items:
                "$ref": "#/components/schemas/Revenue"
              description: Revenue per employee.
            per_device:
              type: array
              items:
                "$ref": "#/components/schemas/Revenue"
              description: Revenue per device.
            per_voucher:
              type: array
              items:
                "$ref": "#/components/schemas/Revenue"
              description: Revenue per voucher.
          required:
          - per_category_of_revenue
          - per_employee
          - per_device
          - per_voucher
          description: Combined revenue of all daily closings in the month, broken
            down per dimension.
        voucher_redemptions:
          type: array
          items:
            "$ref": "#/components/schemas/VoucherRedemption"
          description: Vouchers redeemed during the month.
        daily_closings:
          type: array
          items:
            "$ref": "#/components/schemas/DailyClosing"
          description: Daily closings the monthly closing covers.
        created_at:
          type: string
          format: date-time
          description: Time the monthly closing was created.
      required:
      - id
      - cashflow
      - revenue
      - voucher_redemptions
      - daily_closings
      - created_at
      description: The financial closing of a calendar month, aggregating its daily
        closings.
    postV1PaymentMethods:
      type: object
      properties:
        name:
          type: string
          description: Display name shown to users on the register
        online:
          type: boolean
          description: Whether the payment is processed online (`true`) or in store
            (`false`)
        tap_to_pay:
          type: boolean
          description: Whether the payment method uses Tap to Pay
        operator_reference:
          type: string
          description: Reference that helps 20Tabs users identify the payment method
            in your system
        required_data:
          type: array
          description: 'Fields the user must fill in when paying with this method,
            for example the barcode and pincode of a voucher. The collected values
            are sent to your payment webhook. Example: [{ name: ''card_number'', type:
            ''string'', translated_name: { nl: ''Kaartnummer'', en: ''Card number''
            } }]'
          items:
            type: string
      required:
      - name
      - online
      description: Register a payment method
    patchV1PaymentMethodsId:
      type: object
      properties:
        name:
          type: string
          description: Display name shown to users on the register
      description: Update a payment method
    postV1Payments:
      type: object
      properties:
        receipt_id:
          type: integer
          format: int64
          description: Unique identifier of the receipt the payment settles
        amount:
          type: integer
          format: int32
          description: Amount paid, in euro cents
        payment_method_id:
          type: integer
          format: int64
          description: Unique identifier of the payment method that was used
      required:
      - receipt_id
      - amount
      - payment_method_id
      description: Create a payment
    Payment:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the payment.
        receipt_id:
          type: integer
          format: int64
          description: Unique identifier of the receipt the payment settles.
        payment_method_id:
          type: integer
          format: int64
          description: Unique identifier of the payment method that was used.
        category_of_revenue:
          allOf:
          - "$ref": "#/components/schemas/CategoryOfRevenue"
          description: Category of revenue the payment counts towards, if any.
        voucher:
          allOf:
          - "$ref": "#/components/schemas/Voucher"
          description: Voucher the payment was made with, if any.
        amount:
          allOf:
          - "$ref": "#/components/schemas/Money"
          description: Amount paid.
        created_at:
          type: string
          format: date-time
          description: Time the payment was created.
        updated_at:
          type: string
          format: date-time
          description: Time the payment was last updated.
      required:
      - id
      - receipt_id
      - payment_method_id
      - category_of_revenue
      - amount
      - created_at
      - updated_at
      description: A payment recorded on a receipt.
    Receipt:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the receipt.
        items:
          type: array
          items:
            "$ref": "#/components/schemas/ReceiptItem"
          description: Line items on the receipt.
        customer:
          allOf:
          - "$ref": "#/components/schemas/Customer"
          description: Customer the receipt belongs to, if any.
        payments:
          type: array
          items:
            "$ref": "#/components/schemas/Payment"
          description: Payments recorded on the receipt.
        open_amount:
          allOf:
          - "$ref": "#/components/schemas/Money"
          description: Amount still to be paid.
        paid_at:
          type: string
          format: date-time
          description: Time the receipt was paid in full; null while the receipt is
            open.
        opened_at:
          type: string
          format: date-time
          description: Time the receipt was opened.
      required:
      - id
      - items
      - payments
      - open_amount
      - paid_at
      - opened_at
      description: A receipt grouping ordered items and the payments that settle them.
    ReceiptItem:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the item.
        product_id:
          type: integer
          format: int64
          description: Unique identifier of the ordered product; null for free-form
            items.
        description:
          type: string
          description: Description of the item as shown on the receipt.
        note:
          type: string
          description: Note shown on the preparation receipt.
        price:
          allOf:
          - "$ref": "#/components/schemas/Money"
          description: Unit price after discounts.
        tax_rate:
          allOf:
          - "$ref": "#/components/schemas/TaxRate"
          description: Tax rate applied to the item.
        category_of_revenue:
          allOf:
          - "$ref": "#/components/schemas/CategoryOfRevenue"
          description: Category of revenue the item counts towards.
        cost_price:
          allOf:
          - "$ref": "#/components/schemas/Money"
          description: Cost price of the item.
        representation_by:
          allOf:
          - "$ref": "#/components/schemas/Employee"
          description: Employee who added the item to the receipt.
        payment_status:
          type: string
          description: 'Payment status of the item: `pending` or `paid`.'
        voucher:
          allOf:
          - "$ref": "#/components/schemas/Voucher"
          description: Voucher sold with the item, if any.
        created_at:
          type: string
          format: date-time
          description: Time the item was added to the receipt.
      required:
      - id
      - product_id
      - description
      - note
      - price
      - tax_rate
      - category_of_revenue
      - cost_price
      - representation_by
      - payment_status
      - created_at
      description: A line item on a receipt.
    Customer:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the customer.
        name:
          type: string
          description: Full name of the customer.
        locale:
          type: string
          description: Preferred locale of the customer, for example `nl` or `en`.
        pinned:
          type: boolean
          description: Whether the customer is pinned for quick access on the register.
        last_receipt_at:
          type: string
          format: date-time
          description: Time of the customer's most recent receipt.
        groups:
          type: array
          items:
            type: string
          description: Names of the customer groups the customer belongs to.
        email:
          type: string
          description: Email address of the customer.
        phone:
          type: string
          description: Phone number of the customer.
        address:
          type: string
          description: Postal address of the customer.
        identifier:
          type: string
          description: External identifier of the customer, for example a membership
            number.
        app_data:
          type: object
          description: Arbitrary data stored on the customer by your app.
      required:
      - id
      - name
      - locale
      - pinned
      - last_receipt_at
      - groups
      - email
      - phone
      - address
      - identifier
      - app_data
      description: A customer of the organization.
    postV1ReceiptsReceiptIdAppendices:
      type: object
      properties:
        appendix:
          type: string
          description: Text to append to the receipt
      required:
      - appendix
      description: Append an appendix to a receipt
    postV1Customers:
      type: object
      properties:
        name:
          type: string
          description: Full name of the customer
        email:
          type: string
          description: Email address, used to detect existing customers
        phone:
          type: string
          description: Phone number
        address:
          type: string
          description: Postal address
        app_data:
          type: object
          description: Arbitrary data your app wants to store on the customer
      required:
      - name
      description: Create a customer
    patchV1CustomersId:
      type: object
      properties:
        name:
          type: string
          description: Full name of the customer
        email:
          type: string
          description: Email address
        phone:
          type: string
          description: Phone number
        address:
          type: string
          description: Postal address
        app_data:
          type: object
          description: Arbitrary data your app wants to store on the customer
      description: Update a customer
    putV1CustomersId:
      type: object
      properties:
        name:
          type: string
          description: Full name of the customer
        email:
          type: string
          description: Email address
        phone:
          type: string
          description: Phone number
        address:
          type: string
          description: Postal address
        app_data:
          type: object
          description: Arbitrary data your app wants to store on the customer
      description: Replace a customer
    postV1Orders:
      type: object
      properties:
        customer_id:
          type: integer
          format: int64
          description: Unique identifier of the customer to place the order for
        table_id:
          type: integer
          format: int64
          description: Unique identifier of the table to place the order on
        group_id:
          type: integer
          format: int64
          description: Unique identifier of the group to place the order for
        employee_id:
          type: integer
          format: int64
          description: Unique identifier of the employee to place the order for
        receipt_id:
          type: integer
          format: int64
          description: Unique identifier of an open receipt to add the order to
        note:
          type: string
          description: Note added to the receipt
        takeout_time:
          type: string
          format: date-time
          description: Pick-up time for takeout orders
        items:
          type: array
          description: Items to order
          items:
            type: object
            properties:
              product_id:
                type: string
                description: Unique identifier of the product to order
              product_barcode:
                type: string
                description: PLU or barcode of the product to order
              description:
                type: string
                description: Item description; defaults to the product name
              note:
                type: string
                description: Note shown on the preparation receipt
              price:
                type: number
                format: float
                description: Unit price in euros, including VAT; defaults to the product
                  price
              discount:
                type: number
                format: float
                description: Discount applied to the item; defaults to the product
                  discount
              no_discount:
                type: boolean
                description: Whether the item is excluded from receipt-wide discounts
              tax_rate_id:
                type: integer
                format: int64
                description: Unique identifier of the tax rate; defaults to the product
                  tax rate
              product_category_id:
                type: array
                description: Unique identifiers of the product categories the item
                  belongs to
                items:
                  type: string
              category_of_revenue_id:
                type: integer
                format: int64
                description: Unique identifier of the category of revenue; defaults
                  to the product category of revenue
              preparation_location_id:
                type: integer
                format: int64
                description: Unique identifier of the preparation location the item
                  is sent to
              course:
                type: integer
                format: int32
                description: Course the item is served in; defaults to the product
                  default course
              unit_name:
                type: string
                description: Unit the item is sold in, for example kg
              unit_quantity:
                type: integer
                format: int32
                description: Quantity in the given unit
              unit_default_quantity:
                type: integer
                format: int32
                description: Default quantity in the given unit
              items:
                type: array
                description: Nested sub-items, for example product options
                items:
                  type: object
      required:
      - items
      description: Create and submit an order
    Order:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the order.
        receipt_id:
          type: integer
          format: int64
          description: Unique identifier of the receipt the order was placed on.
        items:
          type: array
          items:
            "$ref": "#/components/schemas/ReceiptItem"
          description: Items that were ordered.
      required:
      - id
      - receipt_id
      - items
      description: An order placed on a receipt.
    postV1OrdersSubmissions:
      type: object
      properties:
        order_id:
          type: integer
          format: int64
          description: Unique identifier of the order to submit
      required:
      - order_id
      description: Submit an order
    Product:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the product.
        name:
          type: string
          description: Name of the product.
        plu:
          type: string
          description: PLU or barcode identifying the product.
        price:
          allOf:
          - "$ref": "#/components/schemas/Money"
          description: Selling price including VAT.
        tax_rate_id:
          type: integer
          format: int64
          description: Unique identifier of the tax rate applied to the product.
        category_of_revenue_id:
          type: integer
          format: int64
          description: Unique identifier of the category of revenue the product belongs
            to.
        tax_rate:
          allOf:
          - "$ref": "#/components/schemas/TaxRate"
          description: Tax rate applied to the product.
        category_of_revenue:
          allOf:
          - "$ref": "#/components/schemas/CategoryOfRevenue"
          description: Category of revenue the product belongs to.
        default_course:
          type: integer
          format: int32
          description: Course the product is served in by default (0 for no course).
      required:
      - id
      - name
      - plu
      - price
      - tax_rate_id
      - category_of_revenue_id
      - tax_rate
      - category_of_revenue
      - default_course
      description: A product in the organization's catalog.
    postV1Products:
      type: object
      properties:
        name:
          type: string
          description: Name of the product
        plu:
          type: string
          description: PLU or barcode identifying the product
        price:
          type: number
          format: float
          description: Selling price in euros, including VAT
        tax_rate_id:
          type: integer
          format: int64
          description: Unique identifier of the tax rate to apply
        category_of_revenue_id:
          type: integer
          format: int64
          description: Unique identifier of the category of revenue the product belongs
            to
        default_course:
          type: integer
          format: int32
          description: Course the product is served in by default (0 for no course)
          default: 0
      required:
      - name
      - plu
      - price
      - tax_rate_id
      - category_of_revenue_id
      description: Create a product
    postV1CategoryOfRevenues:
      type: object
      properties:
        name:
          type: string
          description: Name of the category of revenue
      required:
      - name
      description: Create a category of revenue
    postV1Modals:
      type: object
      properties:
        session_id:
          type: integer
          format: int64
          description: Unique identifier of the user session to show the modal in
        title:
          type: string
          description: Title of the modal
        text:
          type: string
          description: Body text of the modal
        type:
          type: string
          description: Leave empty for a plain text modal, or use `confirm_payment`
            for a payment confirmation modal
        metadata:
          type: object
          description: 'For `confirm_payment` modals: the `reference`, `amount` and
            `payment_method_id` of the payment to confirm'
      required:
      - session_id
      - title
      - text
      description: Show a modal
    postV1Tasks:
      type: object
      properties:
        name:
          type: object
          description: 'Task name per locale, for example { "en": "Missing barcode",
            "nl": "Ontbrekende barcode" }'
        description:
          type: object
          description: Task description per locale
      required:
      - name
      description: Create a task
    Task:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the task.
        name:
          type: object
          description: Task name per locale.
        description:
          type: object
          description: Task description per locale.
        completed_at:
          type: string
          format: date-time
          description: Time the task was completed; null while the task is open.
      required:
      - id
      - name
      - description
      - completed_at
      description: A task shown in the organization's backoffice until it is completed.
    patchV1Subscription:
      type: object
      properties:
        state:
          type: string
          description: New state of the subscription
          enum:
          - active
      required:
      - state
      description: Update the subscription
    OauthToken:
      type: object
      description: An access token issued to your app for one organization.
      properties:
        token_type:
          type: string
          example: Bearer
        access_token:
          type: string
        refresh_token:
          type: string
        expires_in:
          type: integer
          format: int32
          description: Access token lifetime in seconds
          example: 3600
        scopes:
          type: array
          items:
            type: string
          description: Scopes granted to the subscription
        subscription_id:
          type: string
          format: uuid
      required:
      - token_type
      - access_token
      - refresh_token
      - expires_in
    OauthError:
      type: object
      description: An OAuth 2.0 error response.
      properties:
        error:
          type: string
          example: invalid_grant
        error_description:
          type: string
      required:
      - error