API Reference
Back to QPilot.cloud

Annex C: Shipping

Shipping Rates

How Shipping Rates are applied in QPilot

QPilot will automatically apply the "best shipping rate" to a Scheduled Order. This means that anytime a Scheduled Order is changed, updated, or processed, QPilot will automatically review all possible Shipping Rates for a Scheduled Order and then automatically apply the rate that is the lowest cost.

QPilot follows this basic process to automatically calculate and apply a shipping rate to a Scheduled Order:

  1. Validate Shipping Rates for the Scheduled Order's Shipping Address
  2. Validate Shipping Rates for the Product(s) within the Scheduled Order
  3. Return all valid Shipping Rates for the Scheduled Order and apply the lowest cost rate.

How a Shipping Rate is Automatically Applied to Each Scheduled Order

All shipping rates follow "specificity", meaning that the most specific shipping rates will be validated for the Scheduled Order. You can think of this like a cascading set of rules:

First, these basic rules are applied to decide which Shipping Rates are valid and "match" the Scheduled Order:

  • If a country is defined on a shipping rate, it must match the shipping country of the Scheduled Order.
  • If both country and state are defined on a shipping rate, a match is made only if the shipping country and shipping state match the Scheduled Order.
  • Min cycles, min units, min subtotal, and minimum/maximum weight must be satisfied, as well as shipping class (product and shipping rate having exactly same class)

Then, the more specific rules are applied:

  • First, a match is searched for country, state, city, and postcode combination (shipping rates which have country, state, city, and postcode defined)
  • If none is found, a match is searched for country, state, and city combination (shipping rates which have only country, state, and city defined)
  • If none is found, a match is searched for country and state combination (shipping rates which have only country and state defined)
  • If none is found, a match is searched for country, state, and postcode combination (shipping rates which have only country, state, and postcode defined)
    If none is found, a match is searched for country and postcode combination (shipping rates which have only country and postcode defined)
  • If none is found, a match is searched for country (shipping rates which have only country defined)
  • If none is found, a match is searched that matches only the min cycles, min units, min subtotals and shipping class
  • If none is found, scheduled order fails, since there is no shipping possible for these item

Example 1: How to Setup Free Shipping for all Scheduled Orders

{
   "name":"Free Shipping",
   "shippingCarrier":"FlatRate",
   "basePrice":0 
}

Example 2: How to Setup Free Shipping for Scheduled Orders over $100

{
   "name":"Free Shipping",
   "shippingCarrier":"FlatRate",
   "basePrice":0,
   "minSubtotal": 100
}

Example 3: How to Setup Free Shipping for Scheduled Orders over $100 Only Within a Specific Country

{
   "name":"Free Shipping",
   "shippingCarrier":"FlatRate",
   "basePrice":0,
   "minSubtotal": 100,
   "country": "US"
}

Example 4: How to Setup a Flat Rate for "Heavy" Items (items weighing 75 Pounds or more) Shipped within a Country using Weight Restrictions

{
   "name":"Oversized",
   "shippingCarrier":"FlatRate",
   "basePrice": 49,
   "minWeight": 75,
   "weightUnitType": "Pounds",
   "country": "US"
}

Example 5: How to Setup a Flat Rate for "Heavy" Items shipped within a Country using Shipping Classes

{
   "name":"Oversized",
   "shippingCarrier":"FlatRate",
   "basePrice": 49,
   "shippingClass": "heavy",
   "country": "US"
}

Note: this shipping rate will match against items which contain products with the shippingClass field set to heavy

Shipping Carrier Integrations

Currently supported Shipping Carrier Integrations:

  • Flat Rate
  • USPS

Note: The USPS Shipping Integration requires to configure your USPS Web Tools account within QPilot

Units of Measurement

Shipping Methods - especially integrated API based shipping methods - require that your products have set values for dimensions and weights.

You can define units of measurement at the site level and at the product level. QPilot will use the more specific unit of measurement for conversions and calculations. e.g. if a product has a weight unit type set, QPilot will use that unit type instead of the site level weight unit type.