Liquid/Schema Help: Mapping Custom Shipping/Return Metafields to Google's Structured Data

SEO
,
1

I am trying to get my custom Shipping and Return Metafields to be recognized by Google for Rich Results/Google Shopping, but the structured data is failing the validation test.

I need the correct Liquid snippet to successfully map my metafields to the necessary Google Schema properties.

Details of the Issue

Goal: Add Shipping Details and Return Policy to my product’s JSON-LD Schema, and functions for all my product.

Code Location: I understand the code needs to be placed in the right block, but need to know if it should be put in main-product.liquid file? And the exact position is?

Failure: When I try to add the code myself, it fails Google’s Rich Results Test instantly, confirming the structure is incorrect.

Request for Code Could an experienced developer please provide the correct Liquid code snippet required to map the metafields to the JSON-LD?

Thank you in advance!

2

Hey pal @Steve2025 !

Google doesn’t read metafields directly, it only reads the final JSON-LD. So you need to inject your metafields inside the existing Product schema, not in a separate script.

Where to put it:

  • Go to Online Store → Themes → … → Edit code
  • Search for: type="application/ld+json" and "@type": "Product"
  • In most themes this is in a snippet (e.g. snippets/product-schema.liquid) or at the bottom of main-product.liquid.
  • You want to edit that existing Product JSON-LD block and add shipping/returns inside the "offers" object.

Key points:

  • Replace custom.shipping_details / custom.return_policy_url with your actual metafield namespace + key.
  • Keep everything dynamic wrapped in | json to avoid invalid JSON.
  • Don’t create a separate partial schema with only shippingDetails, keep it inside the main Product schema.

After saving, run the page through Google’s Rich Results Test again; if it still fails, it’s almost always a missing/extra comma or a wrong metafield handle.

Hope this helps!

3

Previously, themes included liquid code for structured metadata:

Starting with Dawn version 15 the themes are switching towards use of the built-in filter:

If you need to add more info, you can either switch back to the older code, or extend the new one.

Luckily, built-in filter uses IDs so you can reference them.

Here is an example of code output by the built-in filter:

[
  {
    "@context": "http:\/\/schema.org\/",
    "@id": "\/products\/absolut-vodka-700ml#product",
    "@type": "ProductGroup",
    "brand": {
      "@type": "Brand",
      "name": "SPIRITISM"
    },
    "description": "The Absolut Recycled",
    "hasVariant": [
      {
        "@id": "\/products\/absolut-vodka-700ml?variant=31297174437942#variant",
        "@type": "Product",
        "image": "https:\/\/bbkmarket.myshopify.com\/cdn\/shop\/products\/27720-2.png?v=1747407357\u0026width=1920",
        "name": "Absolut Vodka 700mL - Original",
        "offers": {
          "@id": "\/products\/absolut-vodka-700ml?variant=31297174437942#offer",
          "@type": "Offer",
          "availability": "http:\/\/schema.org\/InStock",
          "price": "29.93",
          "priceCurrency": "AUD",
          "url": "https:\/\/bbkmarket.myshopify.com\/products\/absolut-vodka-700ml?variant=31297174437942"
        },
        "sku": "Original SKU"
      }
    ],
    "name": "Absolut Vodka 700mL",
    "productGroupID": "4360466268214",
    "url": "https:\/\/bbkmarket.myshopify.com\/products\/absolut-vodka-700ml"
  },
  {
    "@context": "http:\/\/schema.org\/",
    "@id": "\/products\/absolut-vodka-700ml?variant=31297174437942#offer",
    "@type": "Offer",
    "shippingDetails": {
      "@id": "#shipping_policy"
    }
  },
  {
    "@context": "https://schema.org/",
    "@type": "OfferShippingDetails",
    "@id": "#shipping_policy",
    "shippingRate": {
      "@type": "MonetaryAmount",
      "value": 2.99,
      "currency": "USD"
    },
    "shippingDestination": {
      "@type": "DefinedRegion",
      "addressCountry": "US"
    },
    "deliveryTime": {
      "@type": "ShippingDeliveryTime",
      "handlingTime": {
        "@type": "QuantitativeValue",
        "minValue": 0,
        "maxValue": 1,
        "unitCode": "DAY"
      },
      "transitTime": {
        "@type": "QuantitativeValue",
        "minValue": 1,
        "maxValue": 5,
        "unitCode": "DAY"
      }
    }
  }
]

So you should be able to add your info like below.
Of course, the actual code for OfferShippingDetails you need to construct yourself.
Here it is referenced, but you can obviously inline it too.

Also, you can use “Custom liquid” section added to the product template, no need to edit theme code for this.

<!-- extend built-in product structured data with shipping info -->
<script type="application/ld+json">
[
 {% for v in product.variants %}
  {
    "@context": "http:\/\/schema.org\/",
    "@id": {{ v.url | append: '#offer' | json }},
    "@type": "Offer",
    "shippingDetails": {
      "@id": "#shipping_policy"
    }
  } {% unless forloop.last %},{% endunless %}
 {% endfor %}
]
</script>
<!-- since shipping is the same, can reference single object -->
<script type="application/ld+json">
  {
    "@context": "https://schema.org/",
    "@type": "OfferShippingDetails",
    "@id": "#shipping_policy",
    "shippingRate": {
      "@type": "MonetaryAmount",
      "value": 2.99,
      "currency": "USD"
    },
    "shippingDestination": {
      "@type": "DefinedRegion",
      "addressCountry": "US"
    },
    "deliveryTime": {
      "@type": "ShippingDeliveryTime",
      "handlingTime": {
        "@type": "QuantitativeValue",
        "minValue": 0,
        "maxValue": 1,
        "unitCode": "DAY"
      },
      "transitTime": {
        "@type": "QuantitativeValue",
        "minValue": 1,
        "maxValue": 5,
        "unitCode": "DAY"
      }
    }
  }
</script>

Resulting code validates properly:

Contact me if you need help implementing it in your store.

if my post is helpful, please like it ♡ and mark as a solution -- this will help others find it
4

Nice, this is a good use case. You can definitely pull metafield values into your JSON-LD.

The schema properties you want are shippingDetails for shipping and hasMerchantReturnPolicy for returns.

Something like this in product.liquid:


"shippingDetails": {
  "@type": "OfferShippingDetails",
  "deliveryTime": {
    "@type": "ShippingDeliveryTime",
    "handlingTime": {
      "@type": "QuantitativeValue",
      "maxValue": {{ product.metafields.custom.shipping_days | default: 5 }},
      "unitCode": "d"
    }
  }
},
"hasMerchantReturnPolicy": {
  "@type": "MerchantReturnPolicy",
  "merchantReturnDays": {{ product.metafields.custom.return_days | default: 30 }}
}

Make sure your metafield values are numbers, not strings like “5 days.”

Test it with Google’s Rich Results Test before going live. Schema errors can be tricky to debug.

For blog content specifically (Article schema), I built auto-injection into an app called ObsessAI: ObsessAI ‑ Retail Agent - Obsess AI - AI Blog Writer & SEO Tool for... | Shopify App Store

But for product schema with custom metafields, you’ll probably want to customize the Liquid yourself since every store’s metafields are different. Happy to help debug if you run into issues.

6

To add Shipping Details and Return Policy to your product’s JSON-LD Schema, you should place the Liquid code snippet in themain-product.liquidfile. Here is the correct Liquid code snippet to map your metafields to the necessary Google Schema properties:

liquid {% if product.metafields.custom.shipping_details %} “shippingDetails”: { “description”: “{{ product.metafields.custom.shipping_details }}” }, {% endif %}

{% if product.metafields.custom.return_policy %} “returnPolicy”: { “description”: “{{ product.metafields.custom.return_policy }}” } {% endif %}

Make sure to replacecustom.shipping_detailsandcustom.return_policywith the actual namespace and key of your metafields.

Place this code within the existing JSON-LD script in themain-product.liquidfile, ensuring it is correctly formatted as part of the schema.

More Details here!

7

Good question, so now adding to what Tim and others shared, since the most common reason metafield-based schema fails validation is the data type, not the structure.

Three things usually break it:

  1. Number metafields stored as text. If your shipping_days metafield is “single line text” with value 5 days, validation fails because deliveryTime expects an integer. Either change the metafield type to integer, or force it with | times: 1 in Liquid.

  2. Missing currency on shippingRate. Even for free shipping you need a full MonetaryAmount with value: 0 and currency. Empty object breaks it.

  3. returnPolicyCategory must be a schema.org enum. Plain text like “30 day returns” fails. It has to be one of: MerchantReturnFiniteReturnWindow, MerchantReturnUnlimitedWindow, or MerchantReturnNotPermitted.

Working metafield-based code. Place inside your existing offers object in main-product.liquid (or in product-schema.liquid snippet if your theme separates it):

liquid

"shippingDetails": {
  "@type": "OfferShippingDetails",
  "shippingRate": {
    "@type": "MonetaryAmount",
    "value": {{ product.metafields.custom.shipping_rate | default: 0 }},
    "currency": {{ cart.currency.iso_code | json }}
  },
  "shippingDestination": {
    "@type": "DefinedRegion",
    "addressCountry": {{ localization.country.iso_code | json }}
  },
  "deliveryTime": {
    "@type": "ShippingDeliveryTime",
    "handlingTime": {
      "@type": "QuantitativeValue",
      "minValue": 0,
      "maxValue": 1,
      "unitCode": "DAY"
    },
    "transitTime": {
      "@type": "QuantitativeValue",
      "minValue": {{ product.metafields.custom.min_delivery_days | default: 2 | times: 1 }},
      "maxValue": {{ product.metafields.custom.max_delivery_days | default: 5 | times: 1 }},
      "unitCode": "DAY"
    }
  }
},
"hasMerchantReturnPolicy": {
  "@type": "MerchantReturnPolicy",
  "applicableCountry": {{ localization.country.iso_code | json }},
  "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
  "merchantReturnDays": {{ product.metafields.custom.return_days | default: 30 | times: 1 }},
  "returnMethod": "https://schema.org/ReturnByMail",
  "returnFees": "https://schema.org/FreeReturn"
}

Replace custom.shipping_rate, custom.min_delivery_days, etc. with your actual metafield namespace and keys. Run through Google’s Rich Results Test after saving. If it still errors, it’s almost always one of the three things above or a stray comma.

If you’re managing this across hundreds of products with different shipping rules per region, the Liquid approach gets messy fast since you have to maintain it across theme updates.

I built Webrex AI SEO Schema (free plan available) which handles ShippingDetails and hasMerchantReturnPolicy automatically without theme edits, but for a single shipping policy across the catalog, the Liquid above works fine.

8

{
“@context”: “https://schema.org”,
“@type”: “Product”,
“name”: {{ product.title | json }},
“offers”: {
“@type”: “Offer”,
“price”: {{ product.price | money_without_currency | json }},
“priceCurrency”: “{{ shop.currency }}”,

"shippingDetails": {
  "@type": "OfferShippingDetails",
  "shippingRate": {
    "@type": "MonetaryAmount",
    "value": {{ product.metafields.custom.shipping_price | json }},
    "currency": "{{ shop.currency }}"
  },
  "shippingDestination": {
    "@type": "DefinedRegion",
    "addressCountry": "{{ product.metafields.custom.shipping_country }}"
  }
},

"hasMerchantReturnPolicy": {
  "@type": "MerchantReturnPolicy",
  "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
  "merchantReturnDays": {{ product.metafields.custom.return_days | json }},
  "returnFees": "https://schema.org/FreeReturn"
}

}
}

9

Just use TinySEO :slight_smile: You can add shipping details and return policies with the app and not worry about coding