Orders & Compliance page

[mjallday]

Email address should be support+orders not orders+support

[kyungmin]

:thumbsup:

[mjallday]

We should use the same terminology here as we did in the API. So either we change the type in the API to be a "Balance" account or we use the term "payable" account here. If Payable does not make sense then we should change it to something that makes sense (e.g. sweep).

Also, this would ideally link to the docs where a reader could learn how to utilize this functionality

[mjallday]

This should link to documentation on how to implement Orders.

[mjallday]

This looks nice to me. My main concern is that it's difficult for the reader to dig deeper into any of this content. How can they drill down and learn more about any particular subject?

[fangpenlin]

the screenshot is a little bit shrank too much, and pixel of font looks like kinda broken. Maybe it can be pre-resized to avoid that issue?

[dmdj03]

@mjallday Customer balance is most intuitive to me. We already have the concept of an order balance which we are referring to as "balance" in the API. It makes sense to me that we keep the naming consistent but append "customer" to balance. Using any terminology with "account" in it will require us to explain this and differentiate it from the other types of accounts, especially in the dashboard. We also used to refer to the Customer as an account, so I'd imagine some of our users out there may regard the customer object as a customer account in the way they speak about it. Or they may think it's a physical account like a bank account.

[mjallday]

The issue you may run into there is if we release a second account on a customer.

A customer may have many accounts so when you talk about their balance it becomes unclear what you mean. If you call the bank they do not ask you what your balance is, they ask you what your balance is on your savings account.

As it stands right now I believe the correct terminology would be "Your customer's balance on their payable (or sweep) account".

The same thing may happen when we release foreign currency. A customer may begin to have an account that holds USD and an account that holds EUR.

[kyungmin]

I would rather focus on simplifying the nomenclature of Balanced, rather than trying to match it perfectly to the real world. My worry is that, when customers encounter this new concept, they would ask us "what's the difference between payable/sweep account vs. all of the other accounts?". My answer would be that the payable/sweep account is not a real bank account, but its concept is rather similar to our existing concept of balance in orders. I don't want to confuse our users by introducing yet another account type.

[mjallday]

I agree with that @kyungmin. Standardizing terminology is a great idea and consistency is key. Is your concern here that it's possible to confuse an account with a bank account? I'd like to address that separately from my immediate concern which is that in this mock is that we're calling it a "sweep account" on the left hand side and then a "customer balance" on the diagram on the right hand side.

If you feel that the nomenclature needs clarification please open an issue, I'd love to discuss that.

[kyungmin]

Yes. "Account" is a general term and people will most likely associate it with our existing bank "accounts". As you see in the mock, it's more natural to see that the money moves from order balance to customer balance then finally to customer's bank account, than from order balance to customer's payable account to customer's bank account.

I've already updated the description on the left hand side to match "customer balance" on the diagram.

[remear]

A Customer does not have a balance. -1 on this terminology. It's inaccurate and misleading.

Yes. "Account" is a general term and people will most likely associate it with our existing bank "accounts".

What is this based on? You have a Facebook account. You have a Pinterest account. You have a bank account. Balanced users have a Dashboard account. Balanced used to have an Account resource that was the predecessor of Customer. Account is a general term and context matters. Give context and solve confusion by linking to documentation.

[kyungmin]

A Customer does not have a balance. -1 on this terminology. It's inaccurate and misleading.

@remear Can you elaborate on why is it inaccurate and misleading? Would achieving this level of accuracy benefit users or is it an implementation detail that our customers don't need to know about? Why do we have to link it to the documentation when we could make it more intuitive?

[msherry]

IMHO, every time we have to solve ambiguity by linking to documentation, we've already lost. People don't read docs -- we see this all the time in support. It's a helpful resource to refer people to when they have questions, but no one reads docs to answer their own questions. We can't change user behavior. Therefore, we should strive to make things as clear as possible on their own, without supplementary reading material.

[remear]

While I agree with @msherry, a marketplace isn't something you can just fire up and operate for long without proper education. We work to make it as easy as possible, but some things are inherently complex and require effort to learn and understand. You can hop into the seat of a car and drive, but that doesn't instantly make you aware of all the traffic laws, vehicle maintenance, and safety information. You actually have to spend time learning those rules, laws, and concepts, a good many of them by reading documentation.

A Customer does not have a balance. You're not going to be able to see a balance attribute on a Customer object. A Customer has a collection of Account resources. Currently there is only one type, payable, and there will be only one, for now. In the future, there could be more. Furthermore, this account is only for bulk crediting and the eventual settlement to a bank account. You may not debit it. If you say a Customer's balance, is it the balance of some balance account? Is that the balance of all their accounts? Can they use that balance to pay for other things without funds leaving the system? Is Customer a funding instrument now, reverting our stance on transactions operating around Customer resources? A Customer is not a funding instrument. It does not maintain a balance. Conveying the concept that it does is misleading. In your effort to simplify the concept you may very well make it more confusing because you've fostered assumptions.

[kyungmin]

@remear Would you make the same argument for orders? An Order is not a funding instrument, but it has a balance property. While they do have technically different functionalities, it's conceptually similar to how balance is related to orders.

[dmdj03]

Actually, one point of confusion they may see with customer balance is whether this is the balance of all money owed to the merchant (from unpaid, active orders, which we are not displaying at the moment) or what we're trying to say here—money credited to the customer, waiting to be settled.

[remear]

@kyungmin No, I wouldn't. An Order is a grouping construct for transactions that isolates its funds from other Orders and maintains (requires) its own balance. It was designed that way.

A Customer does not maintain a balance. Customer accounts each maintain their own balance.

[mjallday]

IMHO, every time we have to solve ambiguity by linking to documentation, we've already lost

That's true if what we write does not convey the message we intend it to. However, I think that if someone wants to read more about it then we should provide them the ability to do so.

I'm not saying that the sentences are not clear, only that if someone goes "Gee, this bulk credit thing sounds awesome, how can I add that to my app" that they have a clear path to follow to do so.

[kyungmin]

What about "Settlement account"? This will at least make it easier to remember that it's related to "Settlement".

[dmdj03]

+1 to settlement account. It ties in well with the transaction description of settlement. That way, we won't have to explain in the dashboard that the customer balance/payable account is related to settlements.

[kyungmin]

@remear @mjallday what do you think?

[mjallday]

I think there's two separate conversations going on here:

1. The mocks
2. Naming of the account and Balanced nomenclature.

I'd like to avoid calling it a settlement account because it's tying us to a specific implementation. What happens if there's a second account type that can also settle? My personal viewpoint is that Balanced provides a set of primitives that can be composed to perform all sorts of actions and very specific names can tie us to specific implementations which can make this confusing.

For the second conversation let's catch up with you and @dmdj03 offline, I'd love to discuss more in depth but feel it's detracting from the other topic of conversation (although it is related) and would like to try and keep this focussed on the mocks.

[dmdj03]

The language is blocking on the orders page release. Can you give me specific examples of these future accounts we may add to the customer? It's hard for me to gauge the relationship and nature of these accounts when they do not exist yet. Should we be optimizing for something that doesn't exist yet and that we have no idea what may come in the future?