Formatting Prices (API Terminology Explained #12)

In one of my last blog posts, I told you about how to calculate product prices. The next question is certainly, how to format prices correctly in order to display them in your application. That is what I want to talk about in this blog post.

Preliminaries

When working with the Spreadshirt API and our platform, you will find prices everywhere. As described in my last blog post, print types, print colors and product types have prices attached that tell you how much needs to be payed when using them. Designs have commissions attached that are payed to the designer when using them. Articles also have prices that are calculated based on the actual product price and commissions on top of that, that are payed to the article owner for each sale.

Data about prices, commissions or costs are returned by the API in always the same price format. A price always consists of the following data:

  • price without VAT – price without value added tax (VAT), e.g. 0,42 €
  • price with VAT – price with value added tax (VAT), e.g. 0,50 €
  • VAT – value added tax (VAT) percentage, e.g. 19% in Germany
  • currency – the currency for which the price is given

You can see an example price for flex print type (print type 14) below:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<printType xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://api.spreadshirt.net"
           weight="2.0"
           xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/printTypes/14" id="14">
    <name>Flexdruck</name>
    ...
    <price>
        <vatExcluded>0.42</vatExcluded>
        <vatIncluded>0.50</vatIncluded>
        <vat>19.00</vat>
        <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1" id="1"/>
    </price>
</printType>

Please note, that prices are always returned in either a shop or a user context and currency and vat are selected based on that automatically.

Formatting Prices

For formatting prices, we need the following data:

  • thousands separator – . or , depending on the country
  • decimal point – , or . depending on the country
  • decimal count – 0 to 2 decimal counts depending on the currency
  • currency symbol – € or other depending on the currency
  • price pattern – currency symbol before or after price depending on the currency

Where do we get this data from? A shop, such as shop 205909, is actually configured for a specific country and currency. A sample payload is illustrated below:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<shop xmlns:xlink="http://www.w3.org/1999/xlink"
      xmlns="http://api.spreadshirt.net"
      xlink:href="http://api.spreadshirt.net/api/v1/shops/205909" id="205909">
    <user xlink:href="http://api.spreadshirt.net/api/v1/users/40000" id="40000"/>
    <country xlink:href="http://api.spreadshirt.net/api/v1/countries/1" id="1"/>
    <language xlink:href="http://api.spreadshirt.net/api/v1/languages/1" id="1"/>
    <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1" id="1"/>
    ...
</shop>

The currency, such as currency 1, defines the currency symbol, the price pattern and the decimal count.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<currency xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns="http://api.spreadshirt.net"
          xlink:href="http://api.spreadshirt.net/api/v1/currencies/1" id="1">
    <plain>EUR</plain>
    <isoCode>EUR</isoCode>
    <symbol>€</symbol>
    <decimalCount>2</decimalCount>
    <pattern>% $</pattern>
</currency>

The country, such as country 1, defines the thousands separator and the decimal point.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<country xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns="http://api.spreadshirt.net"
         xlink:href="http://api.spreadshirt.net/api/v1/countries/1" id="1">
    <isoCode>DE</isoCode>
    <thousandsSeparator>.</thousandsSeparator>
    <decimalPoint>,</decimalPoint>
    <length>
        <unit>cm</unit>
        <unitFactor>1.0</unitFactor>
    </length>
    <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1" id="1"/>
</country>

Having this data, you can format a price correctly. You use currency symbol and price pattern to display the right currency symbol in front of or behind the price and thousands separator, decimal point and decimal count to format the actual price correctly.

Example

The sample code for a Javascript PriceFormatter is illustrated below:

function PriceFormatter(format, decimalCount, centsSeparator, thousandsSeparator) {
    this.format = format;
    this.decimalCount = decimalCount;
    this.centsSeparator = centsSeparator;
    this.thousandsSeparator = thousandsSeparator;

    // format as price
    this.formatPrice = function(price, currency) {
        // formatting settings
        price = "" + price;

        // split integer from cents
        var centsVal = "";
        var integerVal = "0";
        if (price.indexOf('.') != -1) {
            centsVal = price.substring(price.indexOf('.') + 1, price.length);
            integerVal = price.substring(0, price.indexOf('.'));
        } else {
            integerVal = price;
        }

        var formatted = "";

        var count = 0;
        for (var j = integerVal.length - 1; j >= 0; j--) {
            var character = integerVal.charAt(j);
            count++;
            if (count % 3 == 0)
                formatted = (this.thousandsSeparator + character) + formatted;
            else
                formatted = character + formatted;
        }
        if (formatted.indexOf(0) == this.thousandsSeparator)
            formatted = formatted.substring(1, formatted.length);

        formatted += this.centsSeparator;

        for (var j = 0; j < this.decimalCount; j++) {
            if (j < centsVal.length) {
                formatted += "" + centsVal.charAt(j);
            } else {
                formatted += "0";
            }
        }

        var out = this.format;
        out = out.replace('%', formatted);
        out = out.replace('$', currency);
        return out;
    };
}

You can also find this PriceFormatter in the Simplomat code on GitHub.

Summary

In this blog post, I told you how our price data format looks like, which data you need in order to format prices and how you can use this data to format prices correctly. With this knowledge, you should be able to format and display prices in your applications.

Please also have a look at the other articles in the series “API Terminology Explained”:

——————————-
Martin Breest
Platform Evangelist

One Reply to “Formatting Prices (API Terminology Explained #12)”

Comments are closed.