openapi: 3.0.3
info:
  title: EposNow HQ REST API
  description: >-
    The EposNow HQ REST API lets developers programmatically interact with the
    cloud-based aspects of the Epos Now point of sale (POS) platform for retail
    and hospitality - products, categories, transactions (sales), customers,
    stock, tax rates, and devices. This document models the documented V2 API
    surface (base https://api.eposnowhq.com/api/V2). Epos Now recommends the
    newer V4 / "Global" API (https://api.eposnowhq.com/api/v4) for new
    integrations, which reorganizes the same domains; V4 per-resource paths are
    not fully enumerated here. All requests use HTTP Basic authentication with a
    per-device access token (Base64 of "API Key:API Secret") issued from the
    Back Office. List endpoints are paginated at up to 200 records per page via
    the page query parameter.
  version: 'V2'
  contact:
    name: Epos Now Developers
    url: https://developer.eposnowhq.com/
servers:
  - url: https://api.eposnowhq.com/api/V2
    description: EposNow HQ REST API (V2)
security:
  - basicAuth: []
tags:
  - name: Products
    description: The product catalog sold at the point of sale.
  - name: Categories
    description: Categories that group products for the till and reporting.
  - name: Transactions
    description: Sales records (orders) captured at the point of sale.
  - name: Customers
    description: Customer records for loyalty, accounts, and CRM.
  - name: Stock
    description: Product stock levels and stock control.
  - name: Devices
    description: Registered tills and API devices on the account.
paths:
  /Product:
    get:
      operationId: listProducts
      tags:
        - Products
      summary: List products
      description: Returns a paginated list of products, up to 200 per page.
      parameters:
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of products.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProduct
      tags:
        - Products
      summary: Create a product
      description: Creates a new product in the catalog.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: The created product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /Product/{Id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getProduct
      tags:
        - Products
      summary: Get a product
      description: Returns a single product by its ID.
      responses:
        '200':
          description: The requested product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateProduct
      tags:
        - Products
      summary: Update a product
      description: Updates an existing product.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Product'
      responses:
        '200':
          description: The updated product.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Product'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteProduct
      tags:
        - Products
      summary: Delete a product
      description: Deletes a product from the catalog.
      responses:
        '200':
          description: Deletion confirmation.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /Category:
    get:
      operationId: listCategories
      tags:
        - Categories
      summary: List categories
      description: Returns a paginated list of categories, up to 200 per page.
      parameters:
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of categories.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Category'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCategory
      tags:
        - Categories
      summary: Create a category
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Category'
      responses:
        '200':
          description: The created category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /Category/{Id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getCategory
      tags:
        - Categories
      summary: Get a category
      responses:
        '200':
          description: The requested category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCategory
      tags:
        - Categories
      summary: Update a category
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Category'
      responses:
        '200':
          description: The updated category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCategory
      tags:
        - Categories
      summary: Delete a category
      responses:
        '200':
          description: Deletion confirmation.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /Transaction:
    get:
      operationId: listTransactions
      tags:
        - Transactions
      summary: List transactions
      description: >-
        Returns a paginated list of transactions (sales records), up to 200 per
        page.
      parameters:
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of transactions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createTransaction
      tags:
        - Transactions
      summary: Create a transaction
      description: Creates a new transaction (sale) with its line items and tenders.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Transaction'
      responses:
        '200':
          description: The created transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /Transaction/{Id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getTransaction
      tags:
        - Transactions
      summary: Get a transaction
      responses:
        '200':
          description: The requested transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateTransaction
      tags:
        - Transactions
      summary: Update a transaction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Transaction'
      responses:
        '200':
          description: The updated transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteTransaction
      tags:
        - Transactions
      summary: Delete a transaction
      responses:
        '200':
          description: Deletion confirmation.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /Customer:
    get:
      operationId: listCustomers
      tags:
        - Customers
      summary: List customers
      description: Returns a paginated list of customers, up to 200 per page.
      parameters:
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of customers.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCustomer
      tags:
        - Customers
      summary: Create a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
      responses:
        '200':
          description: The created customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /Customer/{Id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getCustomer
      tags:
        - Customers
      summary: Get a customer
      responses:
        '200':
          description: The requested customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCustomer
      tags:
        - Customers
      summary: Update a customer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Customer'
      responses:
        '200':
          description: The updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCustomer
      tags:
        - Customers
      summary: Delete a customer
      responses:
        '200':
          description: Deletion confirmation.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /ProductStock:
    get:
      operationId: listProductStock
      tags:
        - Stock
      summary: List product stock levels
      description: >-
        Returns a paginated list of product stock levels, up to 200 per page.
        Used to read on-hand inventory per product.
      parameters:
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of product stock levels.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProductStock'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /StockTransfer:
    get:
      operationId: listStockTransfers
      tags:
        - Stock
      summary: List stock transfers
      description: >-
        Returns a paginated list of stock transfers between locations, up to 200
        per page.
      parameters:
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of stock transfers.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /TaxRate:
    get:
      operationId: listTaxRates
      tags:
        - Products
      summary: List tax rates
      description: Returns a paginated list of tax rates, up to 200 per page.
      parameters:
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of tax rates.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /Device:
    get:
      operationId: listDevices
      tags:
        - Devices
      summary: List devices
      description: >-
        Returns a paginated list of the tills and API devices registered on the
        account, up to 200 per page.
      parameters:
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: A paginated list of devices.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Device'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /Device/{Id}:
    parameters:
      - $ref: '#/components/parameters/Id'
    get:
      operationId: getDevice
      tags:
        - Devices
      summary: Get a device
      responses:
        '200':
          description: The requested device.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication. The access token is the Base64 encoding of
        "API Key:API Secret" (the API Key, a colon, then the API Secret, with no
        spaces), sent as "Authorization: Basic {token}". Credentials are issued
        per API Device registered under Web Integrations in the Epos Now Back
        Office.
  parameters:
    Id:
      name: Id
      in: path
      required: true
      description: The unique identifier of the resource.
      schema:
        type: integer
    Page:
      name: page
      in: query
      required: false
      description: The page number of results to return (up to 200 records per page).
      schema:
        type: integer
        default: 1
  responses:
    Unauthorized:
      description: Missing or invalid Basic authentication credentials.
    NotFound:
      description: The requested resource was not found.
  schemas:
    Product:
      type: object
      properties:
        Id:
          type: integer
        Name:
          type: string
        Description:
          type: string
        CategoryId:
          type: integer
        SalePrice:
          type: number
        CostPrice:
          type: number
        Barcode:
          type: string
        TaxRateId:
          type: integer
      additionalProperties: true
    Category:
      type: object
      properties:
        Id:
          type: integer
        Name:
          type: string
        ParentId:
          type: integer
      additionalProperties: true
    Transaction:
      type: object
      description: A sales record (order) captured at the point of sale.
      properties:
        Id:
          type: integer
        DeviceId:
          type: integer
        CustomerId:
          type: integer
        DateTime:
          type: string
          format: date-time
        Amount:
          type: number
        TransactionItems:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    Customer:
      type: object
      properties:
        Id:
          type: integer
        Title:
          type: string
        Forename:
          type: string
        Surname:
          type: string
        EmailAddress:
          type: string
        PhoneNumber:
          type: string
        CustomerTypeId:
          type: integer
      additionalProperties: true
    ProductStock:
      type: object
      properties:
        ProductId:
          type: integer
        LocationId:
          type: integer
        CurrentStock:
          type: number
      additionalProperties: true
    Device:
      type: object
      properties:
        Id:
          type: integer
        Name:
          type: string
        LocationId:
          type: integer
      additionalProperties: true