Skip to main content

Automatic completion

"Automatic completion" is run automatically to complete Charges and make balance transfers between Dreambound payers. The general principle is that, when a trigger event happens -- like a card payment or a new invoice -- our system will try to "bill" users by paying Charges off immediately.

This is a spec

This document is a spec. If the implementation is different from what is defined here, this spec takes precedence and the implementation is wrong. If you're changing the implementation, be sure to update this spec. Thanks!

Charges criteria​

Automatic completion will attempt to make Payments for Charges that:

  • Are ready to pay: Not already completed, and either invoiced or overdue
  • Involve internal Payers only: Charges involving external Payers mean real-world money movement, which is out of scope of automatic completion.
  • For charges to customers, their balance can cover: See below.

Triggers​

Automatic completion is run when:

  • An Invoice is first created
  • An Invoice is updated
  • An external payment is made to an Invoice

In the future, we will run automatic completion on a regular time interval.

Special handling for customers​

Normally, a negative balance on a Payer is OK; it just means that they owe Dreambound money (and we can debit or bill them separately). If paying someone causes a negative balance, it just means that Dreambound (as a marketplace) is vouching for the transaction and, in the worst case situation, would make up the difference.

With customers, however, we want to avoid negative balances. Since it is challenging to bill a customer, we would prefer that the Charge be represented as incomplete or overdue.

Charges to customers / Payments from customers​

Charges to a customer have special handling, since we prefer that customers do not carry negative balances.

These Charges are completed one by one:

  • In order of invoice timestamp (earliest first)
  • So long as the customer's balance can cover the amount of the Charge

For example, if the customer has a $50 balance and 3 Charges for $20 each, the first 2 Charges will be completed and the last Charge is still incomplete. The customer now has a $10 balance and will need to fund the account with $10 more to complete the last Charge.

Charges from customers / Payments to customers​

No special handling: Charges from a customer are eligible for automatic completion. Charges from customers are usually for things like credits or refunds, where we want the payment to issue immediately and reflect on the customer's balance.