Order: difference of net_amount_due_money and total_money fields

Questions
1

Reading Order Object - Square API Reference,
can you please add updated documentation or this page to explain how these are different? Or link to a guide which does?

total_money
Read only The total amount of money to collect for the order

net_amount_due_money
Read only The net amount of money due on the order.

I could imagine one gross and one net, and the difference is discounts. But “money to collect” sure sounds like it would be after discounts. Please help us understand when this differs, thanks!

There is also net_amounts (an object) which is clear. It applies after refunds.

net_amounts
Read only The net money amounts (sale money - return money).

I could also imagine e.g. if a payment has been applied but money is still owed, then they might differ. This guide Orders API: How It Works could have a sentence added here to explain it:

In the response, the gross_sales_money elements reflect the item totals, while net_amount_due_money reflects the subtotal for the order ($116.00). [INSERT HERE: The total_money matches the net amount because [reason] although other times [it would not because].]

EDIT: looking at some other example orders I see one (it was a refund exchange order created in app) with a total_money of >0 and net_amount_due_money = 0. That is a case when they differ. Maybe when the order is paid in full net_amount_due_money will change to 0? Whatever the case it really could be documented on the API reference, please. Any guarantees about mutability vs immutability and how it may change based on the state of the order would be helpful in the docs too.

2

:wave: I’m Square Dev AI, here to help answer your question!
Based on the information you’ve provided, the following documentation will help answer your question:

Additional Documentation

Orders API: How It Works
Orders API Overview
Common Data Types

If this documentation helped you find a solution, please check the box indicating that this reply solves the problem.
Otherwise one of our Developer Advocates will provide additional assistance shortly.

3

The total_money field in the Order object represents the total amount of money calculated for all items, taxes, discounts, and service charges in the order. This is the gross amount before any payments or refunds are applied.

On the other hand, net_amount_due_money represents the net amount that is due for the order. This is the amount that still needs to be collected after any payments or refunds have been applied to the order.

In other words, total_money is the total cost of the order, while net_amount_due_money is the remaining balance that needs to be paid. If no payments or refunds have been applied, these two values would be the same. However, if a payment has been made or a refund has been issued, net_amount_due_money would be less than total_money.

This answer was reviewed by @Bryan-Square.

4

Thank you, can this please be added to the documentation under each type? The existing content is so very brief, this actually is really helpful. Thanks!