Open APIs

 View Only
Expand all | Collapse all

TMF678 amountDue vs remainingAmount

  • 1.  TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Nov 16, 2023 13:04

    Hi TM forum members!

    Could you please help me to clarify  the difference between amountDue and remainingAmount properties of the CustomerBill resource model?



    ------------------------------
    Vladyslav Syzov
    Telenor Denmark
    ------------------------------


  • 2.  RE: TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Nov 17, 2023 09:34

    Vladislav, I'm not sure what is the nature of the confusion, because those 2 attributes are representing 2 different business entities. amountDue is the amount required to be paid in the given billing cycle on the paymentDueDate, while remainingAmount represents the amount of outstanding debt for the given account. 



    ------------------------------
    PAVEL DMITRIYEV
    AT&T Inc.
    ------------------------------



  • 3.  RE: TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Nov 17, 2023 13:42

    Thanks for your answer Pavel, (actually I have created a duplicated thread of this question by mistake https://engage.tmforum.org/discussion/tmf678-amountdue-vs-remainingamount?ReturnUrl=%2fcommunities%2fcommunity-home%2fdigestviewer%3fcommunitykey%3dd543b8ba-9d3a-4121-85ce-5b68e6c31ce5)

    I was confused because of CustomerBill model already has fields taxIncludedAmount and taxExcludedAmount so I decided that these are that fields that show the amount to be paid by paymentDueDate. Or they have different meaning?



    ------------------------------
    Vladyslav Syzov
    Telenor Denmark
    ------------------------------



  • 4.  RE: TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Nov 17, 2023 14:22

    My interpretation would be that taxes included/excluded are for the original invoice and don't have direct correlation to the amountDue and remainingAmount. Here is excerpt from the example in TMF678 user guide to illustrate the point:

    {
    	"id": "CB-123",
    	"href": "https://server:port/tmf-api/Customer_Bill_Management/v5/customerBill/CB-123",
    	"billNo": "780123456",
    	"amountDue": {
    		"unit": "EUR",
    		"value": 0.0
    	},
    	"appliedPayment": [
    		{
    			"appliedAmount": {
    				"unit": "EUR",
    				"value": 50.0
    			},
    			"payment": {
    				"id": "PAY-9876",
    				"href": "https://server:port/tmf-api/Payment_Management/v5/payment/PAY-9876",
    				"name": "csp-bill",
    				"@referredtype": "Payment",
    				"@type": "PaymentRef"
    			},
    			"@type": "AppliedPayment"
    		}
    	],
    	"taxExcludedAmount": {
    		"unit": "EUR",
    		"value": 40.0
    	},
    	"taxIncludedAmount": {
    		"unit": "EUR",
    		"value": 50.0
    	},
    	"taxItem": [
    		{
    			"taxAmount": {
    				"unit": "EUR",
    				"value": 10.0
    			},
    			"taxCategory": "VAT",
    			"taxRate": 0.25,
    			"@type": "TaxItem"
    		}
    	]
    }


    ------------------------------
    PAVEL DMITRIYEV
    AT&T Inc.
    ------------------------------



  • 5.  RE: TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Nov 20, 2023 01:47

    Yes, I've seen this example and it confused me a bit because I expected to see

    "amountDue": { "value": 50.0} - what is required to pay by invoice

    "remainingAmount": {"value": 0.0} - what is left to pay.

    but in this example "amountDue" is 0.0 - ?



    ------------------------------
    Vladyslav Syzov
    Telenor Denmark
    ------------------------------



  • 6.  RE: TMF678 amountDue vs remainingAmount

    Posted Nov 22, 2023 04:12

    I imagine the amountDue is used for countries like Hong Kong where there is no VAT/GST.  The example is probably misleading/incorrect.



    ------------------------------
    Dan d'Albuquerque
    Individual
    ------------------------------



  • 7.  RE: TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Sep 23, 2024 10:09

    hi,

    amountDue doesn't exist in the information framework and its purpose is unclear.

    we have the bill amount (with and without taxes), applied payment(s) and remaining amount. What else do I need?

    I hope TMF API authors follow this community to provide support on the assets they create. In the meantime, just do what you think is best.

    I would just ignore this attribute or duplicate taxIncludedAmount.



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Lyse Platform
    ------------------------------



  • 8.  RE: TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Sep 20, 2024 04:24

    Hi everyone, 

    I'm struggling with the same problem as well as it's not very clear to me what the intent is for every field. If someone would validate my understanding, that would be very helpful.

    • amountDue
      • Represents the amount that is owed for the given customer bill - it is essentially the running "balance" of the customer bill
      • Matches the taxIncludedAmount on initial customer bill creation
    • remainingAmount
      • Represents the amount that is owed on the billing account / all past customer bills - it is determined when the customer bill is created and kept static afterwards

    • taxExcludedAmount
      • Represents the amount that is owed (without tax) for the given customer bill - it is determined when the customer bill is created and kept static afterwards
    • taxIncludedAmount
      • Represents the amount that is owed (with tax) for the given customer bill - it is determined when the customer bill is created and kept static afterwards


    ------------------------------
    Linus Chui
    LotusFlare
    ------------------------------



  • 9.  RE: TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Sep 23, 2024 10:37

    Linus,

    I don't think this definition of remainingAmount can be correct.

    • An invoice typically reflects a specific transaction, outlining the goods or services provided and the amount due for that particular transaction. It's part of the income or revenue recognition process and is accounted for in the Profit & Loss (P&L) statement.
    • The remaining balance (which reflects unpaid invoices from previous periods) is part of the accounts receivable and is recorded in the balance sheet. It tracks the overall credit that a customer owes but is not part of the current period's revenue (unless we're speaking about accrual adjustments but clearly we're not).

    So remaingAmount on a given invoice cannot be an "amount" representing other (unpaid) invoices. That needs to be represented by another concept, typically the remaining unpaid balance.

    What's Possible in Practice?

    you may choose to include a summary of the remaining unpaid balance on a new invoice for transparency and customer awareness. the key term here is "balance", so the amount would come from the balance sheet, while the invoice amount would come from the P&L.

    (there are some rather strict accounting / financial regulations that dictate these concepts)


    a single attribute called "remaining unpaid balance" would also be confusing for the customer. Instead, you would need an array in your API payload with a href pointing to a customer API that would list all unpaid invoices with invoice number, date, amount and age. This is not in current TMF api, though.

    Lastly, remaining unpaid balance is always against the customer account, not billing account (even if 90% of the time, it's the same account). It's the customer that has the  legal responsiblity to pay, not the billing account. Billing account is just a proxy for payment.



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Lyse Platform
    ------------------------------



  • 10.  RE: TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Sep 26, 2024 09:30

    Hi Matthieu,

    Thanks for all the feedback. We will take it into consideration when trying to represent "remaining unpaid balance".

    Regarding the other attributes, are the descriptions correct?

    Regarding "remainingAmount", what should this attribute represent then?

    Thanks in advance for your feedback,

    Linus



    ------------------------------
    Linus Chui
    LotusFlare
    ------------------------------



  • 11.  RE: TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Sep 27, 2024 09:15

    Hi,

    example to illustrate remainingAmount.

    Caveat: billing system may have different capabilities, TMF APIs are rather generic and they are some country-specific regulations.

    on 1st of September I renew my mobile subscription with 2-year contract. New price €30

    I also buy 3 optional products in the same cart/order (a new phone, screen protector, 2-year extended insurance)

    Total price for this order is €1,100,- (including €1070 to pay now and €30 every month)

    I pay €1070 now.

    Later I receive my invoice, it shows

     €30 recurring price
    it also show €1070 for my extra products

    in that case, the bottom of the invoice would show:

    amountDue.............. €1100

    AppliedPayment....... €1070 (array of one payment)

    remainingAmount.... €30

    the €30 is typically collected via Direct Debit every month



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Lyse Platform
    ------------------------------



  • 12.  RE: TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Sep 27, 2024 02:07
    Edited by kallem poshetty Sep 27, 2024 02:23

    yes correct.it is little confusing 

    At the customer level the total outstanding amount is always = (current invoice amount 0-30-current amount Due) + history of previous invoices outstanding amount i.e. (30-60/60-90/90-120/120-150/150-180 buckets with invoice id -Previous amount due) and based on customer payment we can allocate the amount from last invoice id 



    ------------------------------
    Poshetty.Kallem
    [TM]
    ------------------------------



  • 13.  RE: TMF678 amountDue vs remainingAmount

    TM Forum Member
    Posted Sep 20, 2024 04:25
    Edited by Linus Chui Sep 20, 2024 09:29

    Deleted since it was a double post