Theme customizations using ShipScout data

The definitive guide to updating shipping related copy and UI throughout your shop

Introduction

As you design your test, it's critical that you update the places in your shop that mention your shipping rate. Here's a list of places that merchants typically show shipping rate information:

• Top announcement banner

• Upsell modal

• Product detail page

• Cart and cart drawer

• Shipping policy page

• FAQ

Depending on the implementation of the copy or UI element, your approach to update it may differ. We offer two different ways to update your theme. Our goal is make it as easy as possible for you to make sure your customers see the right shipping information.

Please give us feedback at [e-mail] on how we can improve our developer SDK.

Using Javascript (Recommended approach)

If the area you're trying to update cannot be updated via liquid because it is rendered via javascript or by a different app, you can use our Javascript API to drive it.

Include the following JavaScript wherever you'd like (we recommend somewhere before the closing </head> tag). It will execute as soon as ShipScout has loaded and will inform you on which test the current user is in.

<script>
window._shipScout = window._shipScout || [];
_shipScout.push(function (response) {

    /*
        example response object
        {
            experimentId: 1,
            variant: 'B',
            isAssignmentManagedExternally: false,
            threshold: true,
            thresholdType: 'pricing',
            thresholdValue: 5000,
            thresholdValueUnit: 'cents',
            thresholdMetRateAmountCents: 0,
            shippingPriceCents: 1000,
            dynamicShipping: false,
            lineItemProperty: '0467e6f7-8d66-4610-a939-da76dd9f7a68_1_B',
            isNewAssignment: false
        }
    */
    
    //apply any exchange rates to currency if necessary
    var thresholdCents = (window.Shopify && Shopify.currency && Shopify.currency.rate) ? response.thresholdValue * Shopify.currency.rate : response.thresholdValue;
    var flatrateCents = (window.Shopify && Shopify.currency && Shopify.currency.rate) ? response.shippingPriceCents * Shopify.currency.rate : response.shippingPriceCents;

    
    //format currency
    var currencyFormat = ShipScoutGetCurrency();
    
    //get threshold amount with currency symbol
    var thresholdAmount = ShipScoutFormatMoney(thresholdCents, currencyFormat);

    //get flat rate amount with currency symbol
    var flatrateAmount = ShipScoutFormatMoney(flatrateCents, currencyFormat);

    //==== insert your code below to dynamically update elements ====//

    //example updating an element on the page dynamically with the threshold amount
    var el = document.getElementById("foo-bar");
    
    if(response.thresholdValue === 0) {
        el.innerHTML = "FREE!";
    } else {
        el.innerHTML = thresholdAmount;
    }
    
});
</script>

Here's a description of the properties and values to expect in the response object.

Property	Value Type	Example	Description
experimentId	integer	1	The experiment ID. 0 when previewing.
variant	string | undefined	A	The variant this visitor is assigned to. Undefined if no live experiment applies.
isAssignmentManagedExternally	boolean	false	True if your own targeting platform is responsible for assigning the variant. See Bring your own targeting platform.
threshold	boolean	true	True if there's a free shipping threshold for this visitor.
thresholdType	string | undefined	pricing	Either "pricing" (threshold based on cart subtotal) or "items" (threshold based on item count). Only present if threshold is true.
thresholdValue	integer | undefined	5000	Only present if threshold is true. The amount required to unlock the threshold rate, in the unit given by thresholdValueUnit.
thresholdValueUnit	string | undefined	cents	The unit thresholdValue is measured in (e.g. "cents" or "items").
thresholdMetRateAmountCents	integer | undefined	0	Only present if threshold is true. The shipping price, in cents, once the threshold amount is met.
shippingPriceCents	integer	1000	The shipping price, in cents, before any threshold is met.
dynamicShipping	boolean	false	True if the shipping price is calculated dynamically at checkout (e.g. carrier-calculated rates) rather than being a fixed value.
lineItemProperty	string | undefined	0467e6f7-8d66-4610-a939-da76dd9f7a68_1_B	The cart attribute value that should be attached to line items so ShipScout can attribute the conversion. Set automatically on themed stores; headless stores must set it manually.
isNewAssignment	boolean	true	True if the ShipScout response data changed during this page load. Useful for optimizing expensive effects.

If there's no live experiment but you do have a Default Shipping Rate set in ShipScout, the rate settings will still be returned by the JS SDK. experimentId will be 0 and variant will be undefined in that case.

Testing the SDK without a live test

You can append ?shipscout_preview=yes to any URL on your website to test your SDK integration without a live test. Appending this URL will simulate these hard-coded values for the SDK:

{
  experimentId: 0,
  variant: 'A',
  isAssignmentManagedExternally: false,
  threshold: true,
  thresholdValue: 0,
  thresholdValueUnit: 'cents',
  thresholdMetRateAmountCents: 500,
  shippingPriceCents: 500,
  dynamicShipping: false,
  isNewAssignment: true
}

If you need to overwrite these hard-coded preview values to simulate a different setup or variant you can do that like this:

window._shipScout = window._shipScout || [];
_shipScout.push(function (response) {

   //Temporarily overwrite the response for testing
   response = {
      ...response,
      thresholdValue: 5000,
      variant: 'B',
   }

})

Using liquid

If your copy and/or variables are primarily set in your theme, this is the best method for updating it.

Step 1 - update the places that refer to the shipping threshold value

In liquid, you can access the shipping rate threshold value from the cart object in liquid. This value will be updated to reflect the correct thresholdValue for the given user.

Here's a example code snippet that checks for the shipscout threshold value and has a default value in case that is not set. This pattern is great to ensure that uninstalling ShipScout doesn't impact the shop.

{%- if cart.attributes._sc_threshold_min_value %}
  {%- assign threshold_in_cents = cart.attributes._sc_threshold_min_value -%}
{%- else -%}
  {%- assign threshold_in_cents = SOMETHING_ELSE -%}
{%- endif -%}

Step 2 - Dynamically re-render sections using this variable after the variant data changes

When a customer visits your store for the first time, ShipScout will assign a variant to the customer after the page loads via javascript. This happens after the liquid page gets rendered. Since on this first page load, the liquid page was rendered based on no variant, the threshold value won't necessarily match the variant threshold value.

To dynamically render sections, add this code to the <head /> of your shop:

<script>
  window._shipScout = window._shipScout || [];
  _shipScout.push(async function (response) {
      // Only update section if assignment data is new
      if (response.isNewAssignment) {
          // Update header using shopify Section API
          const announcementBarID = "announcement_bar_section_id";
          let announcementBarHTML = await (await fetch(`?section_id=${announcementBarID}`)).text();
          document.getElementById('announcement-bar').innerHTML = announcementBarHTML;

          // Update cart using shopify Section API
          const cartID = "cart"
          let header = await (await fetch(`?cart=${cartID}`)).text()
          document.getElementById('cart').innerHTML = header

          // ...etc
      }
  });
</script>