Enterprise User Accounts

This is Phase 2 of the feature that was originally called ‘Enterprise Accounts’ but was renamed to Enterprise Index Rebuild. It is also related to Business Model Configuration

Phase 2 - Towards Payments

  • as an Enterprise User, I can:
  • Understand the payment implications of my choice of package for each of my enterprises (and see how much is accumulating)
  • See my current aggregated outstanding balance
  • See monthly account balance totals, and a breakdown in the form of a transaction history
  • Add service packages/memberships to my account
  • Manage my payment methods
  • Make a one off payment
  • Set up automatic payments

Proposed interface

Basically a tabbed interface, making the related but distinct aspects of user account management easy to switch between.

Part 1: Enterprises

  • Shows a list of the enterprises owned by the current user, with a summary of the package, turnover and bill for the current month for each user.
  • Clicking on a row opens the billing history for the relevant enterprise in reverse chronological order. Star designates current (incomplete) month
  • Could also have a list of available packages/memberships at the bottom of this list, or in a separate tab (not sure which yet).

Part 2: Transaction History

  • Tab gives the current outstanding balance for the current user
  • Panel shows a full transaction history for the current user, basically a breakdown of all charges (per enterprise, service package and membership) and all credits (payments).
  • Split into calendar months to easily show month by month breakdown

Part 3: Payments

  • Tab shows the name of the default automatic payment method if one is chosen, otherwise just shows ‘Manual’ or something.
  • Top of the list has a button for creating a new payment method, this takes the user to a separate interface for adding a new method
  • List of payment methods gives a summary on the left and allows three actions on the right: make payment, manage, remove.
  • ‘Make payment’ tab allows the user to make a one off payment using the relevant payment method, gives the current balance as a default choice for the amount to be paid
  • ‘Manage’ tab lets the user update payment method details (and I think we should move the ‘remove’ button into the manage tab, it doesn’t need its own column)

looking good!! some thoughts from me

General things

  • when talking to a large user last week about pricing, we talked about having a voluntary option for enterprises to voluntarily contribute 2% of transactions above the $50 and have this go into their feature development pool, so that they’re basically building up an account they can then draw upon when they want stuff done (rather than having to find the money separately). This idea was very well received and it would be great to be able to incorporate it here, I think it’s not that hard (see below)
  • Not sure if the term ‘balance’ is being used in a couple of different ways or might be confusing - is this amount owing / outstanding, not amount paid?
  • I wonder if some of the detailed drop-downs could be slightly over-complicating for first iteration (possibly not, if we need to get invoicing right)
  • can we have a way to export to csv (in xero report form) so that we can generate invoice for anyone that wants it
  • GST / tax . .

Part 1: Enterprises

  • columns could be Name; Package; Turnover; Owing (or Bill); Overflow (the rest of the 2% - $50 if cap reached)
  • similar on next layer down

Part 2: Transaction History

  • not sure what Pb is? Cost / owing?
  • do we need the balance column? or enough just to have summary at the top?

have a few more comments but need to run to meeting . . for payments we can perhaps simplify for this version e.g. we don’t actually have facility for mastercard etc

General Things

  • I think the 2% thing is doable but certainly not trivial. It would need a global config setting to turn it on and off, and a per enterprise setting to turn it on and off, and these would have to be taken into account with calculating the monthly bill for each enterprise. Once the calculator is built I’d guess it’s probably a 3-4 hour kind of job, but I think we should focus on getting the calculator designed and built before we start adding extras to it? That is my gut feeling, happy to take it on board if it is vital.
  • Yeah, sorry. Probably not using the right terms. “Balance” on the first page means “current outstanding balance for this month”. So maybe just “bill” is a better word? Balance on the second page means the account balance after the transaction in question took place, so like a running balance on your bank statement.
  • Re. complexity. We could lose the dropdown in the first window, as most of that info is contained in the second window…
  • I guess we can generate an invoice from the data we have here, shouldn’t be too difficult.
  • Hm, tax. Would we need to support multiple tax categories and to be able to assign them to different packages/service packages? That could get tricky… Google doesn’t pay tax, why do we have to? haha

Part1: Enterprises

  • Ok, those column names sound good. Maybe Bill? Then we can decouple the state of the payment from the per enterprise bill calculator and just tell the user what they owe in aggregate without reference to a specific enterprise.

Part2: Transaction History

  • Sorry bad handwriting. It’s Db and is Debit. So the columns are Debit, Credit and Balance, like a bank statement. A value in the Debit column is a cost incurred and a value in the Credit column is a payment made.
  • I think balance column is useful, but happy to be told otherwise.

Other things:

  • ‘Mastercard’ might be a card stored and processed by Pin Payments or whatever modules we decide to support. Pin Payments lets you store card details for customers and then use an API token to charge the card whenever you would like. That way we don’t need to store card details on our system.

@RohanM Here is my rough thinking about how to structure the data we will require in order to be able to charge enterprise users for using the OFN

Part 1: Creating a structure for instance-level rules who gets charged how much and for what

  • In the spirit of flexibility, I think we want to keep the structure of rules pretty open and configurable
  • For now, we can probably get away with just setting up some instance-level preferences
  • For each different ‘package’ (hub, hub profile, producer hub, producer shop, producer profile) have fields for ‘monthly cap’ and ‘% turnover’ which are used to determine monthly cost.
  • In the future:
  • We will probably want to be able to grandfather rules or alter rules for a given enterprise on an individual basis (eg. discounted rate or free usage), so I think we ultimately want to store the package rules as a model instance instead of a ‘sells’ string. This would probably mean delegating responsibility for determining whether an enterprise could have a shop or not to the package model…
  • We could retain global preferences for package rules, which would just represent the default rules for new enterprises, which can then be altered later… anyway, I am getting distracted

Part 2: Tracking changes to enterprise attributes that are relevant to payments

  • We need to know when the owner of an enterprise changes, and when the sells value changes. This information will be used to calculate the cost incurred by a given user for a given enterprises (see Part 3)
  • I have had a look at the paper_trail gem and it seems like a pretty good option, as it allows you to track changes to a instance of a model conditionally, or only when particular attributes are changed, which is what we need. So I think I am going to go with that.

Part 3: Calculating how much a user owes

  • I propose setting up a nightly job, which runs through each enterprise and uses the following information to calculate how much they owe for the current month: 1) what proportion of the current month the user has owned the enterprise, 2) what proportion of the month the enterprise has had each sells value, 3) the turnover of the enterprise for the given period, 4) the resulting cost of 1,2 and 3 as determined by the instance-level rules, 5) whether the enterprise’s trial has expired or not, and 6) the cost of any packages purchased by the user
  • The same job also needs to initiate new invoices/orders (see Part 4). At the beginning of each calendar month the current invoice is archived and a new one is created, but determining the outstanding balance from the previous invoice and setting that as the opening balance of the new invoice.

Part 4: Creating invoices and payments

  • The result of the calculator needs to be stored SOMEWHERE, but I’m not sure exactly where yet. I like the idea of using the existing orders/payments system to create an ‘order’ and to populate it with ‘products’ (which represent the packages/enterprises a user has bought/owns). I am just wary that wrangling orders to do this could end up being more work than is it worth. For instance: would it mean that we have to create a new ‘variant’ for every different enterprise in the system so that we can add a ‘line-item’ about them to the ‘order’?
  • If we don’t use the existing payment/order models, then we are probably going to have to build something from scratch, which will undoubtedly end up being a lot of work anyway. I really don’t know which way to go with this yet…
  • UPDATE: Just had a brainwave: we can use adjustments (rather than line items) on the existing order model to itemise account invoices! Might involve a bit of tweaking in terms of not sending the usual emails, and formatting any invoice emails differently (we might need a flag on the order to make it behave slightly differently…), but I think that could work! Then we can basically just set up a user for each OFN instance to be the account admin, and all the invoices for all of the other users in the system will appear as ‘orders’ in their order interface, and we can process/capture payments in the same way! Cool…

@Kirsten, just a question, this “overflow” tab would appear only if the business model of the local instance include this feature? For example in Scandinavia we have not planned that, we thought we would just charge 2% on all the transactions… so we may not need that feature and it can be confusing if it’s there and 0.

my god @oeoeaio I think that’s utterly brilliant - then everything we do to improve order management, prinint and resending invoices etc just gets passed through. And we can just use the same invoice reports if we want to extract the invoices into separate accounting package.

You are a genius.

Tax: as far as I can make out, all services that we are providing as OFN Aus do attract GST. Especially given recent rulings on Uber and AirBNB etc, I think we’d just be creating future trouble for ourselves to try and avoid this. I’ve got some recent detailed advice from my accountant about GST that we are going to have to retrospectively put into the shipping calculator (urgh, will update info but not wanting to hurt @RohanM just yet). Key immediate question for us is whether the $50 cap (for example) is inclusive or exclusive of GST - I feel that we discussed this with board or management group but can’t remember the outcome - @serenity or @sstead can you remember which way we’re going to do this?

Either way, is probably a matter of setting up in the configurability whether the ‘fee’ includes tax or not, and which rate, and if it’s going to be done as order adjustments anyway, this can all probably just be copied from the way @RohanM has set up the tax on fees?

I also wonder if doing things this way, would potentially open up more easily future implementation of @MyriamBoure’s ideal of having the OFN fees just applied in the order. So if they go with flat 2% to everything, that could actually be added on as a fee that goes right into the shopfront - not something we have to deal with now, just noting

@MyriamBoure see Rob’s comments above - we won’t be doing it at the outset and when we do it’s all in the context of configurable by instance, and then by enterprise

My foggy memory is telling me that we said 2% or $50 exclusive of GST.

OK @oeoeaio, just trying to work out where we’re at with this, with a view to handover to @RohanM while you’re travelling. Notes below outline what I think we have in place (and some questions that arose while working it out)

As Super-Admin, I go to Configuration/Accounts & Billing and:

  • Set up ‘Accounts Administration Distributor’ and associated shipping and payment method
  • Q: if i set my default billing payment method to (for example) pin payments - how would this work? will just set it to check for now as assume that won’t break anything
  • Run ‘Billing Information’ calculator
    • tells me that it is in progress, doesn’t notify when done
  • Run the ‘Update Invoices Now’ calculator
    • as above, doesn’t yet notify when done

Then I go looking for what this has done. I can see that in admin/account I now have entries under each enterprise that I own, but I cannot see anywhere where this entry is not zero - even where I think it should have a value, so I think this isn’t yet done

I can’t see any creation of orders under my Account Administrator Hub (may not be critical in Phase 1) . . not sure when this would happen either, probably best not every time someone hits ‘Update Invoices Now’ without a warning . . or will this be an auto-job at end of month?

okey dokey, following talk to @oeoeaio and @RohanM, this is what we’re aiming to complete in this iteration (phase 1), ideally by end of this sprint (29th July)

When do invoices get sent?

  • Need control over whether the ‘Update Invoices Now’ calculator sends emails or not
  • [TO DO] create yes/no switch that Update Invoices checks so that it knows whether to send emails
  • this switch should be obvious and easily switchable just before you hit the job (or change its auto-timing)

What do invoices look like?

  • Create a separate mailer to handle invoices, which will send email that has a different format
  • [TO DO] Kirsten to adapt order confirmation email so that it fits account information, and contains all required info for valid tax invoice
  • [TO DO] Implement adjusted invoice template


  • [TO DO] Check handling of tax in the order creation, probably adjust it

NB. This new invoice mailer can/could be used as the basis of the system-wide invoice generation and emailing system. So if @lin_d_hop is working on that (now or soon), she and kirsten should make sure on same page

Are these all the tasks? and who is doing what?

minor thing - @oeoeaio and @RohanM - can we do database backup and reload next time we push, i just lost my accounts admin hub and set-up. Setting them up again, but annoying if i have to do each time :smile:

erm - so have just pushed the new version and reset up my accounts hub and some test orders for July etc, but now I am getting this (img below) where yesterday I was getting a list of the enterprises i own and a line of info on them? @oeoeaio

Hi @Kirsten

Seems to be working for me with current production data?

My only thought is that you had probably run the Update Invoices job on the same day as you created the orders, and so they wouldn’t have been picked up because the job only looks up to the previous midnight (when it is set up to run automatically it runs at 1am). Maybe try running it again and see if it picks up you orders from the other day now?

Note that invoices are only created for users that actually need to be charged, and items are only added when the turnover is > $0. Therefore enterprises with trials will appear on invoices with a bill of $0.00, but hubs that sold no produce or producers will not appear as items on invoices. My thinking around this is that it would be better to not flood the system with a bunch of empty orders and adjustments. This setup is easy to change if it is not the desired behaviour.

Your list of things in post 10 looks pretty right to me. My feeling around notification of job completion is that it is not worth the time it would take to build the infrastructure that would be required to live update the status in the page. Note that you can manually refresh the page, and if the “In progress” message is not there, the job is done. Considering that the intended usage is to set the job up to run automatically in the early hours of the morning, I think this is probably sufficient for our requirements for now. Perhaps I could add a sentence after the “In progress” block which tells the user that they can refresh the page to see whether the job is finished or not?

ok, so the next day thing would have been the problem last time. But now I am trying to do it and it is telling me that the task is still running (so I can’t do the generate invoices step), although it started at 1am (and is now 1:37pm) - so something must be stuck? am on staging1

Assume it is because it hasn’t completed that I’m not seeing account info for bulk foods, which I should because I placed some yesterday?

@RohanM - think this is probably starting point for you to pick this up? I cannot see what else we need to do until that task completed and I can have a go at generating the invoices. Grazie :slight_smile:

The delayed job runner wasn’t running on staging1 for some reason. I’ve enabled it and the update user invoices job seems to be running now.

cool. so now I’m trying to do the next step and generate invoices. This only happens for the ‘previous calendar month’ and annoyingly I don’t have any orders for June so I can’t see what it’s doing!!!

@RohanM could you please finangle the orders in the screen-grab below (in staging1) so that they are all in June, so that we can identify what this step does!! Thanks :slight_smile:

Hi @Kirsten,

All done, how’s that looking?

okey dokey, so now we are in action :smile:

When I am logged in (staging1) as admin@openfoodfoundation.org (the accounts distributor), I can now see two auto-generated orders, which have the correct info in them - yay!

So the next steps to get this to be useable seem to be:

1. WHAT do we email to customers?

Whichever way we ‘call’ the email generation, we still need to work out what is actually emailed, as most likely the standard order confirmation email would be pretty confusing. At the moment I can’t see what it actually does so is hard to specify differences.

I started filling in thoughts about this here and realised it needs a page of its own, so please pick up conversation here

Option to print to pdf as well

2. GST / tax

From discussions here we think we want to add GST onto our 2% / $50.

I am hoping that we can do this by making the fee types used to create the adjustments ‘GST inclusive’, just like we’ve done for other fees, but need to set somewhere different I expect. And then we will also need to adjust the actual rates so that they are 10% higher (e.g. 2.2% and $55)

Then hopefully the GST should just magically work, although we’ll need to pay attention to the invoice template

Hard-code vs fields in config

3. How do we generate invoice emails to customers?

We had some discussion about this and agreed that for now they certainly shouldn’t be automatically emailed, but we need to either

  • have a way to ‘send emails’ from the config / accounts and billing when the invoices are generated, OR once they are generated

  • be able to send from within the order (‘Resend’ currently causes a grumpy cat :frowning: )

  • be able to select multiple orders and ‘bulk action’ / ‘send emails’ - which would tie-in with @lin_d_hop’s work on re-doing the Order Index page for more useability Order Management - wishlist

@oeoeaio @sstead - would we consider this to be testing? or done?