#csv #data #monthly #reports #extract #lo-la #sum-up

app lola-sumup

A cli program to create LoLa specific exports from monthly SumUp reports

1 unstable release

0.1.0 Aug 1, 2024

#31 in Finance

MIT license

140KB
3K SLoC

lola-sumup

CLI to evaluate the monthly SumUp CSV extracts and extract LoLa specific reports.

Summary

The cli application lola-sumup has two subcommands: prepare and export.

The prepare subcommand parses two SumUp extracts with monthly data and creates an intermediate file, combining data from both reports, enriched with three columns Topic, Owner, and Purpose. The user may redact the content of those three columns, as the simple heuristics may not get it right out of the box.

The (potentially redacted) intermediate file is consumed by the second export step. It generates three different exports from it, dedicated to different purposes in the context of LoLa's monthly closing process.

Versions

The format of the sumup sales reports has changed. lola-sumup has been adapted in a non-backwards-compatible way.

Version Sumup-exports
0.1.0 Up to April 2024
0.2.0 As of May 2024

CLI

The lola-sumup command has two subcommands:

A cli program to create exports from sumup transactions exported in CSV format

Usage: lola-sumup <COMMAND>

Commands:
  prepare  Prepares an enriched intermediate file from the original sumup sales report CSV and transaction report CSV
  export   Consumes the (potentially redacted) intermediate file and exports to different special purpose CSV files
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

The prepare step

The lola-sumup prepare command works as follows:

Prepares an enriched intermediate file from the original sumup sales report CSV and transaction report CSV

Usage: lola-sumup prepare --sales-report <SALES_REPORT> --transaction-report <TRANSACTION_REPORT> <MONTH>

Arguments:
  <MONTH>  the month for which transactions are to be processed (<yyyymm>, e.g. 202305)

Options:
  -s, --sales-report <SALES_REPORT>              the sales-report to process
  -t, --transaction-report <TRANSACTION_REPORT>  the transaction-report to process
  -h, --help                                     Print help
  -V, --version                                  Print version

It produces a file named e.g. intermediate_202305_20230603142215.csv, where 202305 is the processed month with the timestamp indicating when the process was executed (03. June 2023 14:22:15).

Manual redaction of existing transactions

The last four columns of the file are pre-filled using sensible heuristics. The derived values may or may not be correct though and can be redacted. If modified, ensure certain constraints are met, otherwise further processing will fail during the export step.

The four columns that may be modified are:

  • Topic: The main topic of the transaction, one of
    • MiTi: Items sold by Mittagstisch. Automatically assigned if the transaction occurred before 14:15.
    • Cafe: Items sold by LoLa Café. Automatically assigned if the transaction occurred between 14:15 and 18:00.
    • Verm: Items sold by Renters of the rooms. Automatically assigned if the transaction occurred after 18:00.
    • SoFe: Items sold in context of the summer party ("Sommer-Fest").
    • Deposit: Key deposit.
    • Rental: Rental fee.
    • Culture: Items sold in context of cultural events.
    • PaidOut: Income paid out in cash to external party.
    • Packaging: Sold re-usable packaging for dishes
  • Owner: Only relevant for Topic MiTi: MiTi (for menus produced and sold by Mittagstisch) or LoLa (LoLa beverages and food from LoLa, sold by Mittagstisch)
  • Purpose: Consumption or Tip (the former is also used for Topics Deposit, Rental, Culture, or PaidOut)
  • Comment: Empty, can be manually filled to keep some context

Adding artificial transactions for Cash payments that were not entered into SumUp

It is also possible to add lines to capture transactions that were not entered into the SumUp System.

If you do so, ensure some fields are filled correctly, and some fields are left blank. I.e.

  • Account: Provide an email address that clearly identifies who created the "artificial" transaction
  • Date
  • Time: Best guess
  • Type: "Sales"
  • Transaction ID: Leave blank
  • Receipt Number: Leave blank - unless you do have some receipt
  • Payment Method: Cash (as Card would never be missing in the SumUp Transactions)
  • Quantity: Best guess
  • Description: Best effort - ideally copy one of the existing descriptions to be precise
  • Currency: "CHF"
  • Price (Gross): The paid amount
  • Price (Net): Copy of the previous value in Price (Gross)
  • Tax: Leave blank
  • Tax rate: Leave blank
  • Transaction refunded: Leave blank
  • Commission: 0 (it's a cash payment)
  • Topic: See list of Topics above
  • Owner: Blank if Topic is not MiTi. MiTi or LoLa if topic is MiTi
  • Purpose: Likely Consumption unless it's a tip
  • Comment: Provide some reference for later audit as to why the transaction is artificially created (e.g. reference to email)

Constraints for manual redactions

For all items (existing SumUp transactions and artificially added transactions), it must be true that:

  • Topic and Purpose contain valid values
  • Owner contains either valid values or is empty
  • for Topic MiTi: Owner must be either MiTi or LoLa
  • for Topic other than MiTi: Owner must be blank

The export step

The lola-sumup export command:

Consumes the (potentially redacted) intermediate file and exports to different special purpose CSV files

Usage: lola-sumup export <INTERMEDIATE_FILE>

Arguments:
  <INTERMEDIATE_FILE>  the intermediate file to process

Options:
  -h, --help     Print help
  -V, --version  Print version

It produces three exports (with month and execution timestamp accordingly):

  • accounting_202305_20230603142503.csv
  • mittagstisch_202305_20230603142503.csv
  • summary_202305_20230603142503.csv

Description of the exports

Summary Report

The summary file collects all original and derived columns that are required to build the other reports or for deeper insights.

The columns of the resulting summary file are defined as follows:

  • Generic Columns:
    • Date: Calendar Date
  • Gross Values of consumptions of topics MiTi, Cafe, Verm (commissions not subtracted) split by payment method
    • MiTi_Cash: Gross Cash Income Mittagstisch (including LoLa beverages)
    • MiTi_Card: Gross Card Income Mittagstisch (including LoLa beverages)
    • MiTi Total: Total Gross Income Mittagstisch (including LoLa beverages) [MiTi_Cash + MiTi_Card], also [Gross MiTi (MiTi) + Gross MiTi (LoLa)]
    • Cafe_Cash: Gross Cash Income Café
    • Cafe_Card: Gross Card Income Café
    • Cafe Total: Total Gross Income Café [Cafe_Cash + Cafe_Card]
    • Verm_Cash: Gross Cash Income Rentals
    • Verm_Card: Gross Card Income Rentals
    • Verm Total: Total Gross Income Rentals [Verm_Cash + Verm_Card]
    • SoFe_Cash: Gross Cash summer party
    • SoFe_Card: Gross Card summer party
    • SoFe Total: Total Gross summer party [SoFe_Cash + SoFe_Card]
    • Deposit_Cash: Gross Cash Key Deposit
    • Deposit_Card: Gross Card Key Deposit
    • Deposit Total: Total Gross Key Deposit [Deposit_Cash + Deposit_Card]
    • Packaging_Cash: Gross Cash Key Deposit
    • Packaging_Card: Gross Card Key Deposit
    • Packaging Total: Total Gross Key Deposit [Packaging_Cash + Packaging_Card]
    • Rental_Cash: Gross Cash Rental Payment
    • Rental_Card: Gross Card Rental Payment
    • Rental Total: Total Gross Rental Payment [Rental_Cash + Rental_Card]
    • Culture_Cash: Gross Cash Culture
    • Culture_Card: Gross Card Culture
    • Culture Total: Total Gross Culture [Culture_Cash + Culture_Card]
    • PaidOut_Cash: Gross Cash PaidOut
    • PaidOut_Card: Gross Card PaidOut
    • PaidOut Total: Total Gross PaidOut [PaidOut_Cash + PaidOut_Card]
  • Gross values consumption, Tips and total reported values by payment method:
    • Gross Cash: Total Gross Income Cash [MiTi_Cash + Cafe_Cash + Verm_Cash + SoFe_Cash + Deposit_Cash + Packaging_Cash + Rental_Cash + Culture_Cash + PaidOut_Cash]
    • Tips_Cash: Tips Cash
    • SumUp Cash: Total Income Cash [Gross Cash + Tips_Cash]
    • Gross Card: Gross Gross Income Card [MiTi_Card + Cafe_Card + Verm_Card + SoFe_Card + Deposit_Card + Packaging_Card + Rental_Card + Culture_Card + PaidOut_Card]
    • Tips_Card: Tips Card
    • SumUp Card: Total Gross Income Card [Gross Card + Tips_Card]
    • Gross Total: Gross Total Income [Gross Cash + Gross Card]
    • Tips Total: [Tips_Cash + Tips_Card]
    • SumUp Total: [Gross Total + Tips Total] or [SumUp Cash + SumUp Card]
  • Card related payments: Gross values, commission and net values by topic:
    • Gross Card MiTi: Gross Card Income Mittagstisch MiTi_Card (including beverages LoLa)
    • MiTi_Commission: Card Commission for Mittagstisch (Menus and Tips, but not from LoLa beverages)
    • Net Card MiTi: Net Card Income Mittagstisch [Gross Card MiTi - MiTi_Commission] - commission on meals and tips are deducted, sales of beverages still included
    • Gross Card LoLa: Gross Card Income LoLa (Café, Vermietungen, summer party, Deposit, Rental, Culture) [Cafe_Card + Verm_Card + SoFe_Card + Deposit_Card + Rental_Card + Culture_Card + PaidOut_Card]
    • LoLa_Commission: Card Commission for LoLa (non-Mittagstisch related, but including commission for items sold by MiTi)
    • LoLa_Commission_MiTi: Card Commission for LoLa items sold by MiTi only, so not from Café or Rentals
    • Net Card LoLa: Net Card Income LoLa (Café and Vermietungen) [Gross Card LoLa - LoLa_Commission]
    • Gross Card Total: Gross Card Income (MiTi, Café, Vermietungen) [Gross Card MiTi + Gross Card LoLa]
    • Total Commission: Card Commission Total (MiTi, Café, Vermietungen) [MiTi_Commission + LoLa_Commission]
    • Net Card Total: Total Net Card Income [Gross Card Total - Total Commission]
    • Net Payment SumUp MiTi: Total Net Payment SumUp Mittagstisch related (Net card payments concerning Mittagstisch (Sales from meals, tips, sales of LoLa goods paid via card)) [MiTi_Card + MiTi_Tips_Card - MiTi_Total_Commission]
  • Tips by Topic:
    • MiTi_Tips_Cash: Tips for Mittagstisch paid in Cash
    • MiTi_Tips_Card: Tips for Mittagstisch paid by Card
    • MiTi_Tips: Tips for Mittagstisch (Total) [MiTi_Tips_Cash + MiTi_Tips_Card]
    • Cafe_Tips: Tips for Café
    • Verm_Tips: Tips for Vermietungen
  • Split of Topic Mittagstisch by Owner:
    • Gross MiTi (MiTi): Gross Income Mittagstisch from their own Menus (paid via Card or Cash)
    • Gross MiTi (LoLa): Gross Income Mittagstisch with LoLa-items (Beverages...) (paid via Card or Cash)
    • Gross MiTi (MiTi) Card: Gross Income Mittagstisch from their own Menus (paid via Card only) (not including tips)
    • Net MiTi (MiTi) Card: Net Income Mittagstisch Menus w/o commission paid by card [Gross MiTi (MiTi) Card - MiTi_Commission]
    • Net MiTi (LoLa): Net total income Mittagstisch with LoLa items w/o commission [Gross MiTi (LoLa) - LoLa_Commission_MiTi]
    • Contribution MiTi: Share MiTi from selling LoLa items [20% * Net MiTi (LoLa)]
    • Net MiTi (LoLA) - Share LoLa: 80% of Net total income Mittagstisch with LoLa items w/o commission [Net MiTi (LoLa) * 0.8]
    • Sponsored Reductions: Reductions sponsored by LoLa [2 * (MealCount_Reduced + MealCount_Regular)]
    • Debt to MiTi: Net amount LoLa needs to pay out to Mittagstisch [Net Payment SumUp MiTi - Net MiTi (LoLA) - Share LoLa + Sponsored Reductions]
    • Income LoLa MiTi: Income LoLa from MiTi selling LoLa [Gross MiTi (LoLa) - Contribution MiTi]
  • Statistics relevant for Mittagstisch:
    • MealCount_Regular: Number of regular meals per day
    • MealCount_Reduced: Number of meals with reductions sponsored by LoLa per day
    • MealCount_Regular: Number of meals for stagaire sponsored by LoLA per day
    • MealCount_Children: Number of children meals per day

Mittagstisch Report

The purpose of the Mittagstisch export is to provide the relevant financial information to the Mittagstisch team.

The columns of the resulting file are defined as follows:

  • Generic columns
  • Count of Menus
    • Hauptgang: Number of regular meals per day MealCount_Regular
    • Reduziert: Number of regular meals per day [MealCount_Reduced + MealCount_Praktikum]
    • Kind: Number of children meals per day MealCount_Children
  • Income by ownership (MiTi or LoLa):
    • Küche: Gross income from menus [Gross MiTi (MiTi)]
    • Total Bar: Gross income from selling LoLa items (Bar) [Gross MiTi (LoLa)]
    • Anteil LoLa: Gross income LoLa from MiTi selling LoLa items
    • Anteil MiTi: Gross income MiTi from selling LoLa items
  • Gross totals by payment method, differentiating income and tips:
    • Einnahmen barz.: Income and Tips paid in Cash [MiTi_Cash + MiTi_Tips_Cash]
    • davon TG barz.: Total Tips paid in cash MiTi_Tips_Cash
    • Einnahmen Karte: Income and Tips paid by Card [MiTi_Card + MiTi_Tips_Card]
    • davon TG Karte: Total Tips paid by card MiTi_Tips_Card
    • Total Einnahmen (oT): Total payments (Cash + Card - w/o Tips) [MiTi Total]
  • Net totals:
    • Kommission Bar: Commission for LoLa payments LoLa_Commission_MiTi
    • Netto Bar: Net Income for selling LoLa items [Total Bar - Kommission Bar]
    • Karte MiTi: Gross income from menus paid by card (not including tips) [Gross MiTi (MiTi) Card]
    • Kommission MiTi: Commission on Gross Card MiTi (including commission on tips) MiTi_Commission
    • Netto Karte MiTi: Net income from menus paid by card [Net MiTi (MiTi) Card]
  • Netting with LoLa
    • Net Total Karte: Net card payments concerning Mittagstisch (Sales from meals, tips, sales of LoLa goods paid via card) [Net Paymnet SumUp MiTi]
    • Verkauf LoLa (80%) 80% of net sales lola goods [-Net MiTi (LoLA) - Share LoLa]
    • Gesponsort LoLa sponsored reductions (2.00 per Meal) [Sponsored Reductions]
    • Überweisung: Net Payment LoLa to Mittagstisch [Debt to MiTi]

Accounting Report

The purpose of the accounting export is to provide the relevant information on monthly level to the book-keeper.

The columns of the resulting accounting.csv file are defined as follows:

  • Date: Date
  • Payment SumUp: Total Net Income plus tips paid via Card. Daily payment by SumUp (next business day) [Net Card Total + Tips_Card]. Will be posted 10110/10920, but based on Account Statement, not this report.
  • Total Cash Debit: Total daily cash debit [Gross Cash - MiTi_Cash - PaidOut Total]
  • Total Card Debit: Total daily card debit [Gross_Card_LoLa + Tips_Card - MiTi_Tips_Card]
  • 10000/23050: Total Cash Income Key Deposit Deposit_Cash
  • 10000/30200: Total Cash Income Cafe Cafe_Cash
  • 10000/30700: Total Cash Income Food Rentals Verm_Cash (LoLa Food sold by renters)
  • 10000/30800: Total Cash Income summer party SoFe_Cash (LoLa Food sold during summer party)
  • 10000/31000: Total Cash Income Rental Fee Rental_Cash (fees for renting the rooms)
  • 10000/32000: Total Cash Income Cultural Payments Culture_Cash
  • 10000/46000: Total Cash Cost Reduction on Material Cost Packaging_Cash
  • 10920/10000: Total Gross Payments Card paid out in cash to external parties PaidOut_Card
  • 10920/23050: Total Gross Payments Card Key Deposit Deposit_Card
  • 10920/30200: Total Gross Payments Card Cafe Cafe_Card
  • 10920/30700: Total Gross Payments Card Rentals Verm_Card (LoLa Food sold by renters)
  • 10920/30800: Total Gross Payments Card summer party SoFe_Card (LoLa Food sold during summer party)
  • 10920/31000: Total Gross Payments Card Rental Fee Rental_Card (fees for renting the rooms)
  • 10920/32000: Total Gross Payments Card Cultural Payments Culture_Card
  • 10920/46000: Total Gross Payments Card Reduction on Material Cost Packaging_Card
  • 10920/20051: Net Card income + tips (card) Mittagstisch [Net Card MiTi + MiTi_Tips_Card]
  • 10920/10910: Tips LoLa paid via Card [Tips_Card - MiTi_Tips_Card]
  • 68450/10920: Commission for Café, Vermietung, summer party, Deposit, Rental, Cultural Payments, and PaidOut, i.e. w/o Mittagstisch [Commission LoLa]
  • 59991/20051: LoLa sponsored reductions (Sponsored Reductions)
  • 20051/10930: Amount LoLa owes to Mittagstisch (Debt to MiTi)
  • 20051/30500: Income LoLa from MiTi selling LoLa [Gross MiTi (LoLa) - Contribution MiTi = Income LoLa MiTi]
  • 10930/10100: Payment to Mittagstisch (Debt to MiTi or 20051/10930) - posting date according to the actual payment

The first three columns after the date do not require postings. They serve for consolidation purposes:

  • Payment SumUp has to match the bank statement showing the daily sumup payments (which are posted on our account with a delay of one or more days).
  • Total Cash Debit and Total Card Debit helps to reconcile the cash account ledger ("Kassendokument"). Please note that those two columns potentially aggregate multiple entries in the cash account ledger for each day.

Where the absolute net sum for the transitory accounts must not be > 0.05, i.e.:

  • for 10920: abs(10920/30200 + 10920/30700 + 10920/30800 + 10920/23050 + 10920/46000 + 10920/31000 + 10920/32000 +10920/20051 + 10920/10000 + 10920/10910 - Payment SumUp - 68450/10920) < 0.05
  • for 20051: abs(10920/20051 - 20051/10930 - 20051/30200 + 59991/20051) < 0.05

Dependencies

~30–59MB
~1M SLoC