How to use Shipping Rules

What you’ll learn

In this article you’ll learn about the Shipping Rules Engine, specifically:

• What Shipping Rules are & who can use them
• The primary objects that make up Shipping Rules
• The queries that can be used to retrieve Shipping Rules

What are Shipping Rules?

Shipping Rules allow you to determine the rate you charge for a purchased item based on where you are going to send it (Shipping Zone) and an applicable Shipping Profile (e.g. Weight, size, delivery time slot etc.). The table below summarizes the entities that make up a Shipping Rule, along with some other information:

Creating Shipping Rules

An in-depth discussion of the various ways to create Shipping Rules is outside the scope of this article, detailed documentation can be found in the Marketplacer Knowledge base by searching for “Shipping Rules”. A worked example will however help in understanding how you can use Shipping Rules with GraphQL.

The worked examples will all be performed from the perspective of the Operator (Admin).

Step 1: Creating Shipping Zones

• Login to the Administrator Portal
• Navigate to: Configuration -> Shipping Settings

• Select “Shipping Zones” and “Create new shipping zone”

• Fill out Shipping Zone Name and Description
• Upload the CSV file containing all your Zip / Post codes for this zone
  • A CSV template is available to download from this page
• Click “Save Shipping Zone

You can of course create more zones, but let’s move on…

Step 2: Creating Shipping Rates

• Select “Shipping Rates” and “Create new shipping rate”
• Populate the Name for this Shipping Rate along with the Rate

• Click Save

You can of course create more rates, but let’s move on…

Step 3: Creating Shipping Profile

• Select “Shipping Profiles” and “Create new shipping profile”
• Populate the Name for this Shipping Profile along with the Description

• Click Save

You can of course create more profiles, but let’s move on…

Step 4: Define your Shipping Rules

• Select “Shipping Rules” and “Create new shipping rule”
• Populate the Name for this Shipping Rule, then specify 1 or more:
  • Shipping Zones
  • Shipping Profiles
  • Shipping Rates

• Click Save

You can of course create more rules, but let’s move on…

Step 5: Applying Shipping Profiles to Products

You can then assign a Shipping Profile to each of your Product Variants.

To assign a Shipping Profile to an existing Product using the Seller Portal, follow these steps:

• Login to a Seller Portal
• Navigate to: Products -> My Adverts
• Edit the Product (Advert)
• Select and Edit Variant you want to assign a profile to
• Select the Shipping Profile you want to assign to the Variant

• Save the Variant and Product to ensure Shipping Profile is Applied.

Using Shipping Rules with GraphQL

Option 1: Retrieving Shipping Rates & Zones with the Variant

The following advertSearch GraphQL query details how to pull back the shippingOptions (the applicable Shipping Rules) for Advert Variants, this includes the shippingRates and shippingZones. The Shipping Rules available are based on the Shipping Profile that was set on the Variant, so it’s possible that you have a number of rules available for a given variant.

    query 
    {
      advertSearch(attributes: {
        advertIds: ["QWR2ZXJ0LTEwMDAwMTkwMw=="] 
      }) {
        adverts (first: 200){   
          edges {
            node {
              id
              title
              variants{
                edges{
                  node{
                    label
                    id
                    published
                    countOnHand
                    shippingOptions{
                      totalCount
                      edges{
                        node{
                          id
                          name
                          shippingZones{
                            totalCount
                            edges{
                              node{
                                name
                                postcodes
                              }
                            }
                          }
                          shippingRates{
                            totalCount
                            edges{
                              node{
                                name
                                rateCents
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }

This Advert has 1 variant to which we applied the “Maximus Package (> 100Kg)” Profile:

Looking at the applicable rules that would apply for this profile:

We can see that 2 Rules would be applicable to this Variant:

• Outer Melbourne Rule
• Metro West Melbourne

The above query returns these 2 Rules as shippingOptions and we additionally pull back the relevant shippingZones and shippingRates:

Option 2: Retrieving Shipping Rule IDs only

To reduce the amount of data that you pull back for every Advert & Variant (as shown above) a 2nd approach is suggested in which you:

• Only return the shippingOption IDs with your Adverts & Variants
• Periodically query (e.g. daily) & cache all the shippingOptions including all shippingZones and shippingRules
• “Join” the cached shipping options on the shipping option Ids for each Variant

Examples of both these queries are provided below.

Advert Search

    query 
    {
      advertSearch(attributes: {
        advertIds: ["QWR2ZXJ0LTEwMDAwMTkwMw=="] 
      }) {
        adverts (first: 200){   
          edges {
            node {
              id
              title
              variants{
                edges{
                  node{
                    label
                    id
                    published
                    countOnHand
                    shippingOptions{
                      totalCount
                      edges{
                        node{
                          id
                          name
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }

Shipping Options

    query{
      shippingOptions{
        totalCount
        edges{node{
          id
          name
          shippingRates{
            totalCount 
            edges{
              node{
                id
                name
                rateCents
                rateFormatted
              }
            }
          }
          shippingZones{
            totalCount
            edges{node{
              name
              postcodes
            }
            }
          }
        }
        }
      }
    }