Reporting

This guide explains how to retrieve and process reporting information using the Winston POS API.

1. Retrieving bills

The primary source of revenue data is the bills collection. You can retrieve bills using the list endpoint.

Important limitations:

• Time range: For the bills collection, you can query at most 2 days of data at a time.
• Filtering: You must provide one of modifiedSince, modifiedAt, or businessDay.
• Pagination: The default limit is 100 records, and the maximum is 1000. Use skip to paginate through larger datasets.

2. Handling payments

A common pitfall when reporting from the bills collection is that bills include all payment attempts, including failed ones.

When processing a bill, you must iterate through its payments array and only count those with a status of "complete".

Example bill structure:

{
  "_id": "...",
  "total": 45.50,
  "payments": [
    {
      "amount": 45.50,
      "status": "failed",
      "machine_name": "pin"
    },
    {
      "amount": 45.50,
      "status": "complete",
      "machine_name": "cash"
    }
  ]
}

In the example above, the bill was eventually paid with cash. If you simply sum the amount of all payments, you would double-count the revenue.

3. Grouping sales

Winston POS allows customers to create custom groupings of sales for reporting purposes.

You might want to use the same groupings for your custom implementation to ensure consistency with the internal reports generated by Winston POS.

If a customer has configured revenue groups, they are the recommended way to group sales. If not, you can use the VAT list as a fallback method to group by category and VAT rate.

Revenue groups

1. Retrieve Revenue Groups: /list/revenueGroups.
2. Map Categories: Retrieve categories (/list/categories) and use the revenueGroup_id field to link them to a revenue group.
3. Process Bill Products: Each product in a bill (bill.products[]) has a category_id. Use this to trace back to the revenue group.

VAT list (fallback)

If there are no revenue groups configured use the dedicated /categories/vatList endpoint.

4. Summary of key collections

• bills: The main transaction records.
• revenueGroups: High-level grouping for sales.
• categories: Product categories, linked to revenueGroups.
• vats: VAT rate definitions.

By combining these resources, you can build comprehensive reports that align with the Winston POS internal reporting logic.