Hey Devs, is your calculated GST on Xero API generated invoice one cent off?

Is your system working with price items with value more than 2 decimal points long? Are you using rounding as a part of the calculating formula? Have you generated invoice from Xero API and later found out that the actual total on it is few cents off?

If answers on all of these question are yes, you are at the right place!

Well, you know this story … you have done all that hard work on building Xero API integration, happy with finishing project on time and with such a masterpiece level source code, and in first integration test run you discover that your invoice calculated data summary data are different from what Xero has generated in the invoice (ouch!):

Invoice line items total calculation with one cent off

And yes, something is not looking right and scratching the head does not seem to be helping much …

Well, the truth is that every system does invoice calculation of subtotal, total and GST differently. The same applies to Xero backend service (API) and therefor these two ways are good options to get you out of the trouble.

One way of doing it is to add an adjustment line as a part of the Xero API request payload and put the variation value into it to keep source data in alignment with Xero. Personally, I don’t really like this approach. The reason being is that you are going to end up with a more comprehensive solution for not much of added business value as appose to time spent on building it.

Another way is to follow the Xero calculation formula. Yep, you heard me right…

And the way I would rather suggest you go with. You may be asking why I would do that?

So let me explain my view on this.

Let’s assume that Xero as a business is on the market for several decades now. You may be getting some sense about the overall knowledge Xero as a company must have gained from such a long time history, providing comprehensive financial services to customers.

I also know that Xero has gone through several business validation iterations and internal system refactoring processes to build as much accurate tax calculation business logic on the API backend possible. All these company journeys supported by customer feedbacks and over time accumulating domain knowledge helped Xero build a great service reputation on the current market world-wide.

And the question is, why wouldn’t I use this knowledge in my advantage? And just btw – I am not participating on any affiliate programs running by Xero!

Do you have another thought about it? – leave me a comment below 😉

Ok, let’s go ahead and talk about the calculation formula…you can start to calculate GST from the prices either GST inclusive or exclusive. These are the types of line items on request payload.

Types of line items to be used in the invoice request payload

1. Line item price with GST exclusive

  1. Round line-item-price to 2 DP (decimal places)
    Round(line-item-price) => Round2DP(10.5456)
  2. Calculate line-item GST from rounded line-item-price, line-item-quantity and GST rate, and round result to 2 DP for each line-item
    Round(line-item-price * [GST rate] * line-item-quantity) => Round2DP(10.55*(0.155) *5)
  3. Sum-up the rounded line-item-price(s) as Subtotal
    (line-item-price * line-item-quantity)+…N(row)…+(line-item-price * line-item-quantity)
  4. Sum-up the line-item calculated GST (step2) as GST Total
    (step2)+…N(row)…+(step2)
  5. Add Subtotal and GST Total as invoice Total
    (step3)+(step4)

Feels difficult? That is ok. For simplicity and quick integration reasons I have created NuGet package XeroGSTTaxCalculation (NET 5) for you, free to use.

A short demonstration of how to use the XeroGSTTaxCalculation NuGet package:

class Program
    {
        static void Main(string[] args)
        {         

            IXeroTaxCalculationService service = new XeroTaxCalculationService();

            var data = new[] { 
                new LineItem { Code = "code_1", Price = 12m, Quantity = 10 }, 
                new LineItem { Code = "code_2", Price = 8.7998m, Quantity = 8 } 
            };

            var invoiceDetails = service.CalculateGSTFromPriceGSTExclusive(data, 0.25);

            Console.WriteLine(invoiceDetails);
            Console.ReadLine();
        }
    }

2. Line item price with GST inclusive

  1. Add 1 to GST rate
    1+[GST rate] => 1 + 0.15
  2. Calculate and Round to 2 DP line-item-price as line-item-price-total
    Round(line-item-price*line-item-quantity) => Round2DP(10.5456*5)
  3. Divide rounded line-item-price-total by GST rate (for each line-item) and round to 2 DP as line-item-price-lessTax
    Round(line-item-price-total/[GST rate] )=> Round2DP(52.73/1.15)
  4. Subtract line-item-price-lessTax from line-item-price-total as line-item-gst
    (line-item-price-total ) – (line-item-price-lessTax)
  5. Sum-up the line-item calculated GST (line-item-gst) as invoice GST total
    (step4)+…N(row)…+(step4)
  6. Sum-up line-item-price-total as invoice Total
    (step2)+…N(row)…+(step2)
  7. Subtract GST total from Total to get invoice Subtotal
    (step6) – (step5)

Feel free to use NuGet package XeroGSTTaxCalculation for this as shown in one code example from above. I bet you’re gonna need this saved time to spent on beer sessions with your mates instead .). Cheers!

For more information about rounding, visit Xero documentation site for developers.

Happy reading and leave me a comment below!

Software development principles and practices for solid Software Engineers

Although today’s way of software development is rapidly changing, having a good understanding of these principles and good practices may only help you become better in software development. Personally, I would recommend to every solid Software Engineers to get familiar with these practices if not already.

Coding practices

YAGNI

This principle came from Extreme Programming and states for very simple things: Don’t overthink the problem solution in the execution stage. Just write enough code for making things working!

DRY

This principle follows and states for: Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.

Basically, don’t replicate functionality in the system and do make your code reusable.

SOLID

This principle has its own space in OOP. The SOLID mnemonic acronym represents these five design principles:

  1. Single-responsibility
    Design your classes in structural business entity/domain hierarchy, so only one class encapsulates only logic related to it.
  2. Open-closed
    Entities should be open for extension but closed for modification.
    In the development world, any class/API with publicly exposed methods or properties should not be modified in their current state but extended by other features as needed.
  3. Liskov substitution
    This principle defines the way how to design classes when it comes to inheritance in OOP.
    The simplified base definition says that if class B is a subtype of class (super) A, then objects of A may be replaced with objects of type B without altering any of the desirable properties of the program.
    In other words, if you have a (super) class of type Vehicle and subclass of type Car, you should be able to replace any objects of Vehicle with the objects Car in your application, without braking application behavior or its runtime.
  4. Interface segregation
    In OOP is recommended using Interfaces as an abstracted segregation level between the producer/consumer modules. This creates an ideal barrier preventing coupling dependencies and exposing just enough functionality to the consumer as needed.
  5. Dependency inversion
    The principle describes a need for abstract layer incorporation between the modules from top to bottom hierarchy. In brief, a high module should depend on an abstract layer (interface) and a lower module with dependency on the abstract layer should inherit/implement it.

KISS

Acronym for Keep it simple, stupid – and my favorite over the last years!

The principle has a very long history but getting forget by many Devs many times from my professional experience. Avoiding non-necessary complexity should be in every solid Software Engineer DNA. This keeps the additional development cost down for further software maintenance, new human resources onboarding, and the application/system additional organic growth.

BDD

Behavior-Driven Development is becoming more and more desirable practice to follow from the Agile oriented business environments. The core of these principles is coming from FDD. The BDD applies a similar process at the level of features (usually set of features). One’s tests build the application/system is getting a return on investment in form of automated QA testing for its lifetime. And therefore this way of working is very economically efficient in my opinion.

The fundamental idea of this is to engage QAs (BAs) into the development process right from the beginning.

This is a great presentation of the principle from the beginning to the end of the release lifecycle: Youtube

TDD

The software development process gained its popularity over time in test automatization. Basics are coming from the concept of starting the test-first and follow with the code until the test runs successfully.

Leveraging Unit test frameworks for this such as xUnit, NUnit (or similar), if you are .NET developers, helps to build a code coverage report very easily in MS Visual Studio (Enterprise edition) for example, which helps to build QA confidence over the code which last long time over the code releases.

FDD

Well know approach how to deliver the small blocks (features) in an Agile running environment. In other words, if you have a load of work to deliver is better to slice it down to individual blocks (features) which can be developed, tested and delivered independently.

The whole FDD methodology has 5 stages:

  1. Develop a model of what is needed to build
  2. Slice this model into small, testable blocks (features)
  3. Plan by feature (development plan – who is going to take that ownership)
  4. Design by feature (selects the set of features team can deliver within the given time frame)
  5. Build by feature (build, test, commit to the main branch, deploy)

The beauty of this development methodology approach is that deployment features such as Feature toggling can be integrated with relatively minimal complexity overhead. With this integration in place, the production team can move forward only on one main branch, unfinished feature development state regardless. An enterprise-level production team will appreciate this advantage, no doubt about it.

Summary

By following these principles and practices production team will produce maintainable code, with high test coverage and human resources high utilization over the SDLC (ROI).

Immutable data types after .NET 5 release

Just couple weeks ago, Microsoft released RC of .NET 5 which is (unfortunately) not going to be an LTS (Long Term Support) release but on the other hand, it’s coming with some great features in it (yep yep).

One of them comes as a part of the new release of C# 9.0 (part of the .NET 5 release) which is Immutable Objects and Properties (records and init-only properties). Quite a smart concept in my opinion …

Recap on immutable data type

The immutable data type is basically data type of the variable of which the value cannot be changed after creation.

How does it look in reality?

Well, once immutable data typed object is created then only way how to change its value is to create a new one with a copied value of the previous instance.

What are the current immutable (and mostly used) data types from .NET CLR?

Primitive types

  • Byte and SByte
  • Int16 and UInt16
  • Int32 and UInt32
  • Int64 and UInt64
  • IntPtr
  • Single
  • Double
  • Decimal

Others

  • All enumeration types (enum, Enum)
  • All delegate types
  • DateTime, TimeSpan and DateTimeOffset
  • DBNull
  • Guid
  • Nullable
  • String
  • Tuple<T>
  • Uri
  • Version
  • Void
  • Lookup<TKey, TElement>

As you can see, we have quite a few to choose from already. How this list is going to look like after .NET 5 full release in November 2020?

Well, it’s going to be a revolutionary change in my 2 cents.

Principally, any object using .NET 5 runtime (and C# 9.0) can be immutable and also implement its own immutable state – and that is HOT feature.

The syntax of the immutable properties looks like in this example:

public class ObjectName
{
    public string FirstProperty { get; init; }
    public string SecondProperty { get; init; }
}

On the other hand, the syntax of immutable object (called a record) looks this:

public record class ObjectName
{
    public string FirstProperty { get; init; }
    public string SecondProperty { get; init; }
}

As you can see, the syntax is very clear and intuitive to use.

More details about new C# 9.0 features can be found here https://docs.microsoft.com/en-us/dotnet/csharp/whats-new/csharp-9#record-types.