Adding and linking custom structured data to JSON-LD for SEO

By Ilana Davis

While JSON-LD for SEO tries to supply a complete set of data for all Shopify stores, sometimes you might need to supplement its data with something custom.

For new types of structured data, you can just add them anywhere in your Shopify theme and they'll work. JSON-LD is flexible like that.

Adding custom markup

If you want to modify the data types JSON-LD for SEO provides, here's how to do it.

1. Create a new block of JSON data

The first step is to create a new block of JSON data that you want to add. I like to write this in a text file so you can copy and paste it where it goes.

Let's say you want to add a field for the color and material of your product. We'll code that up like this

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Product",
  "color": "red",
  "material": "silk"
}
</script>

Adding that to the Schema Markup Validator shows that it works but it's not connecting to any other sets of data.

2. Link the data to JSON-LD for SEO

Now that you have the data you want to add, you need to link it to the main data. This uses the @id field and is what the LD part of JSON-LD means (Linked Data).

JSON-LD for SEO uses your product url as the @id with a suffix of #json-ld-for-seo-product. You can easily find the current @id by using Schema Markup Validator tool.

Adding the same @id to our data, we have this:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Product",
  "@id": "https://jsonldforseodemo.ilanadavis.com/products/bow-tie-product-with-variants#json-ld-for-seo-product",
  "color": "red",
  "material": "silk"
}
</script>

Some fields like color and material can only be applied at the product level.

We also now include a variant @id so that you can link custom data at the variant level. For variants, JSON-LD for SEO uses your product URL with the variant number in the @id with a suffix of #json-ld-for-seo-variant.

Using the variant @id, you can add custom data specific only to that variant. Let's say you're doing preorders and want to add an availability date for a specific variant.

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Offer",
  "@id": "https://jsonldforseodemo.ilanadavis.com/products/bow-tie-product-with-variants?variant=36298357769#json-ld-for-seo-variant",
  "availabilityStarts": "2024-01-21"
}
</script>

Shipping and Returns

There isn't a field in Shopify for us to pull your shipping or returns information. Additionally your shipping rates change so frequently, it's near impossible to make sure the data is accurate to comply with Google's requirements. That's why even Google recommends using Merchant Center rather than adding it to the structured data.

With that said and al though we don't recommend using this as an option, if your returns and shipping information is straightforward, you can add the custom code and link it with each variant Offer.

Note: You'll need to include the shipping and returns information for each variant so you may be better off adding this code to your theme files or the theme customizer so you can use liquid for the variant URL and then append our @id with #json-ld-for-seo-variant.

The following example shows free returns within 14 days.

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Offer",
  "@id": "https://jsonldforseodemo.ilanadavis.com/products/bow-tie-product-with-variants?variant=36298357769#json-ld-for-seo-variant",
  "hasMerchantReturnPolicy": {
    "@type": "MerchantReturnPolicy",
    "applicableCountry": "US",
    "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
    "merchantReturnDays": 14,
    "returnMethod": "https://schema.org/ReturnByMail",
    "returnFees": "https://schema.org/FreeReturn"
    }
}
</script>

The following example shows a flat shipping rate of $4.95 USD with a processing time of 1-2 days and 1-10 days for transit.

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Offer",
  "@id": "https://jsonldforseodemo.ilanadavis.com/products/bow-tie-product-with-variants?variant=36298357769#json-ld-for-seo-variant",
  "shippingDetails": {
    "@type": "OfferShippingDetails",
    "shippingRate": {
      "@type": "MonetaryAmount",
      "value": 4.95,
      "currency": "USD"
    },
    "deliveryTime": {
      "@type": "ShippingDeliveryTime",
      "handlingTime": {
        "@type": "QuantitativeValue",
        "minValue": 1,
        "maxValue": 2,
        "unitCode": "d"
      },
      "transitTime": {
        "@type": "QuantitativeValue",
        "minValue": 1,
        "maxValue": 10,
        "unitCode": "d"
      }
    }
  }
}
</script>

It is not recommended to link the shipping and returns information with structured data. Please use Merchant Center whenever possible and ignore the dumb non-critical issues in Search Console. Search Console is annoying and sends you warnings for things that don't really matter.

Site Name Alternative

For Shopify stores, your site name is usually the store name that you've assigned in the Store Details setting.

You can set an alternative site name, but it's not built into Shopify.

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type" : "WebSite",
  "@id": "https://jsonldforseodemo.ilanadavis.com#website"
  "alternateName" : "The JSON-LD for SEO Shopify App"
}
</script>

Local Business

Let's say you want to add custom structured data about a specific store location. The following is an example where the location is not the same as the main address associated with your Shopify account. Notice I use a different @id as #local. I made up the id so that it wouldn't try to mix with the other org data.

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "LocalBusiness",
  "@id": "https://jsonldforseodemo.ilanadavis.com/pages/hq#org",
  "department": [ 
    {
    "@context": "https://schema.org",
    "@type": "LocalBusiness",
    "@id": "https://jsonldforseodemo.ilanadavis.com/pages/hq#local",
    "logo": "https://cdn.shopify.com...",
    "image": "https://cdn.shopify.com...",
    "name": "JSON-LD for SEO HQ",
    "telephone": "123456789",
    "address": {
      "@type": "PostalAddress",
      "streetAddress": "123 SE Main St",
      "addressLocality": "Portland",
      "addressRegion": "",
      "postalCode": "97127",
      "addressCountry": "US"
    },
    "openingHoursSpecification": [
      {
        "@type": "OpeningHoursSpecification",
        "dayOfWeek": ["Monday", "Wednesday"],
        "opens": "14:00",
        "closes": "18:00"
      },
      {
        "@type": "OpeningHoursSpecification",
        "dayOfWeek": "Sunday",
        "opens": "11:00",
        "closes": "15:00"
      }
    ]
    }	
  ]   
}
</script>

3. Adding the new JSON-LD data to the Shopify theme

The last step is to add that new block of data to your theme.

You'll want to put it into different places depending on what data you're adding.

Adding data for a specific product, blog post, or page? Add the script into the description using Shopify's editor in HTML mode.

Screenshot of Shopify's product editor highlighting the button to show html

Adding data for all products? You'll want to add the script to your product template in Shopify's theme editor.

Adding data for every page? Add the script to your theme's layout template.

List of IDs provided by JSON-LD for SEO

To help you out, here's a list of the IDs used by the major data types.

  • Organization/Store/Local Business - your store url with the suffix of #org.
  • Website - your store url with the suffix of #website.
  • Product Group (for stores using the ProductGroup data for variants) - your product's canonical url with the suffix of #json-ld-for-seo.
  • Product (There may be two different @ids depending on your setup. Contact support if you're not sure)
    1. - your product's canonical url with the suffix of #json-ld-for-seo.
    2. - your product's canonical url with the suffix of #json-ld-for-seo-product. (Used for everyone on the ProductGroup markup)
  • Variant - your variant url with the suffix of #json-ld-for-seo-variant.
  • Blog posts - your blog post's canonical url with the suffix of #article.
  • Shopify pages - your page's canonical url with the suffix of #article.
  • Videos - your page's canonical url with the suffix of #video.
  • Recipes - your page's canonical url with the suffix of #recipe.
  • FAQs - your page's canonical url with the suffix of #faq.
  • How-To - your page's canonical url with the suffix of #howto.

That's it. That's the entire process to add custom JSON-LD structured data to your Shopify store by piggybacking on JSON-LD for SEO.

JSON-LD for SEO

Get more organic search traffic from Google without having to fight for better rankings by utilizing search enhancements called Rich Results.

Linking Llama

Link discontinued products to their best substitute. Keep discontinued products published on your website and continue to benefit from traffic to these pages.