The Shipping Type Model (API Terminology Explained #13)

In my blog posts in the series “API Terminology Explained”, I already told you about some of our data models, like the product type model, the product model or the basket model.
In this blog post, I will add another data model you should be familiar with, the shipping type model. Understanding the shipping type model allows you to display the right shipping countries, regions and prices for shops and to calculate correct shipping prices for baskets and orders.

Understanding the Shipping Type Model

In our terminology, a shipping type defines the way Spreadshirt delivers an ordered item to a customer. Depending on whether the customer ordered a real item, like a t-shirt, or a virtual item, like a gift certificate, we either need to ship the item using a standard carrier, like Deutsche Post or UPS, or we can send it using e-mail.

A shipping type has right now the following characteristics:

  • Core Data: Each shipping type has a name and a description, that can be used for displaying shipping type information in a client application. For shipping types that denote a shipping of a real item with a standard carrier, there are the available shipping countries and the shipping regions with the shipping costs for different order values defined.
  • Shipping Country: A shipping country is a country that Spreadshirt ships items to using the specified standard carries, like UPS. A shipping country has a name that can be used for displaying country information in a client application. It also links to a specific shipping region that contains the actual shipping costs for different order values.
  • Shipping Region: A shipping region contains the shipping costs for different order value ranges for a set of shipping countries, like France or United Kingdom if your country of delivery is Germany. Each order value range defines a from order value (lower bound), like 0.00 €, and might define a to order value (upper bound), like 24.89 € or unbound (undefined). Depending on the order value of the order, the shipping costs of the matching order value range apply.

Retrieving Shipping Type Data

Knowing how the shipping type model works, I will now tell you, how to retrieve the data required for creating own applications. For each shipping type, we provide an XML description. As described in Spreadshirt API v1 Explained, you can use the Data API to retrieve the XML descriptions.

  • XML description: To retrieve a shipping type XML description, you can for example use a URL similar to the following one: http://api.spreadshirt.net/api/v1/shops/205909/shippingTypes/1. Using that URL, you will receive an XML description similar to the one below:
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <shippingType xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns="http://api.spreadshirt.net" weight="1.0"
        xlink:href="http://api.spreadshirt.net/api/v1/shops/205909/shippingTypes/1"
        id="1">
        <name>Standard</name>
        <description>You have selected standard shipping. Your order will be sent by DHL or
                     Deutsche Post. Shipping usually takes 3-7 days (Ireland up to two weeks).
        </description>
        <shippingCountries>
           ...
           <shippingCountry id="153">
              <name>France</name>
              <shippingRegion id="3"/>
           </shippingCountry>
           <shippingCountry id="148">
              <name>Germany</name>
              <shippingRegion id="1"/>
           </shippingCountry>
           ...
           <shippingCountry id="178">
              <name>United Kingdom</name>
              <shippingRegion id="3"/>
           </shippingCountry>
           <shippingCountry id="86">
              <name>United States</name>
              <shippingRegion id="5"/>
           </shippingCountry>
        </shippingCountries>
        <shippingRegions>
           <shippingRegion id="1">
              <shippingCosts>
                 <shippingCost>
                    <orderValueRange>
                       <from>0.00</from>
                       <to>24.89</to>
                       <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1"
                                 id="1"/>
                    </orderValueRange>
                    <cost>
                       <vatExcluded>2.44</vatExcluded>
                       <vatIncluded>2.90</vatIncluded>
                       <vat>19.00</vat>
                       <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1"
                                 id="1"/>
                    </cost>
                 </shippingCost>
                 <shippingCost>
                    <orderValueRange>
                       <from>24.89</from>
                       <to>59.99</to>
                       <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1"
                                 id="1"/>
                    </orderValueRange>
                    <cost>
                       <vatExcluded>3.28</vatExcluded>
                       <vatIncluded>3.90</vatIncluded>
                       <vat>19.00</vat>
                       <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1"
                                 id="1"/>
                    </cost>
                 </shippingCost>
                 <shippingCost>
                    <orderValueRange>
                       <from>59.99</from>
                       <to>500.00</to>
                       <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1"
                                 id="1"/>
                    </orderValueRange>
                    <cost>
                       <vatExcluded>0.00</vatExcluded>
                       <vatIncluded>0.00</vatIncluded>
                       <vat>19.00</vat>
                       <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1"
                                 id="1"/>
                    </cost>
                 </shippingCost>
                 <shippingCost>
                    <orderValueRange>
                       <from>500.00</from>
                       <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1"
                                 id="1"/>
                    </orderValueRange>
                    <cost>
                       <vatExcluded>0.00</vatExcluded>
                       <vatIncluded>0.00</vatIncluded>
                       <vat>19.00</vat>
                       <currency xlink:href="http://api.spreadshirt.net/api/v1/currencies/1"
                                 id="1"/>
                    </cost>
                 </shippingCost>
              </shippingCosts>
           </shippingRegion>
           ...
        </shippingRegions>
    </shippingType>

Determining Shipping Costs

Understanding both, how the shipping type model works and how to retrieve the required XML descriptions, the question is: How do I calculate the right order value from the products or articles that are in the basket or order?
The answer is actually quite simple. The order value for the shipping cost calculation is always calculated based on product types and product type prices.  As you already know from the product model, each article and product is created based on a product type and links the product type in the XML description. Each product type also has a shipping factor between 0 and 1 (0-100%) that defines to which part the product type price is used to calculate the order value. 0 means it is not used and 1 means the full product type price is used for order value calculation. With the calculated order value, we now only need to find the right shipping region for the country we want to ship to and identify the shipping costs by finding the matching order value range for the shipping region.

Example

Let’s assume we have an order with 2 x Bud Spencer t-shirts from our marketplace that we want to ship from Germany to Germany with the standard shipping type, which means we use shipping type 1, shipping country 148 and shipping region 1. The Bud Spencer t-shirt is based on our classic mens t-shirt, which costs 12.90 € on the German marketplace. The shipping factor is 1 for that product type as we ship a real item. Based on that data the order value calculation is as follows:

  2 (quantity) x 1.0 (shipping factor) x 12.90 € Buds Spencer T-Shirt
---------------------------------------------------------------------
= 25.80 €

Using the shipping cost order value ranges defined for shipping region 1, which are

  0.00 € -  24.89 €    -> 2.90 €
 24.89 € -  59.99 €    -> 3.90 €
 59.99 € - 500.00 €    -> 0.00 €
500.00 € -             -> 0.00 €

the shipping costs for the basket in our example are 3.90 €.

Summary

In this blog post, I explained how our shipping type model works and how you can retrieve the required XML descriptions from our API. I also told you how to calculate the order value of your basket or order and how to determine the right shipping cost for it.

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

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

2 Replies to “The Shipping Type Model (API Terminology Explained #13)”

Comments are closed.