Missing field shippingDetails: how to add shipping schema
What the missing field shippingDetails warning means in Search Console, and three documented fixes: offer markup, an organization shipping policy, or settings.
By Crawlito · 7 min read
In short
- Google lists shippingDetails as a recommended Offer property, so a missing value is a non-critical issue, not a reason the item is invalid.
- To be eligible for the shipping details enhancement, an OfferShippingDetails block needs shippingRate, shippingDestination and deliveryTime, and the rate currency must match the offer's currency.
- Free shipping is written as a shippingRate value of 0, and each different rate or destination needs its own shippingDetails entry.
- Google recommends one global shipping policy under Organization, which an Offer can reference with hasShippingService and only an @id.
- If you set shipping in Search Console and also mark it up, Google's shipping policy documentation says it uses only the Search Console information.
On this page
- Is a missing shippingDetails field a problem?
- Option 1: add OfferShippingDetails to each offer
- Option 2: one shipping policy under Organization
- Option 3: settings instead of markup
- Which source wins: Merchant Center, Search Console or markup?
- How to check the fix
- Frequently asked questions
- Check what your product pages publish
The "Missing field shippingDetails" issue in the Search Console Merchant listings report means your Offer markup has no shipping information. Google lists shippingDetails as a recommended property, not a required one, so the warning does not make your product pages invalid or stop them being eligible for merchant listings. To deal with it, either add OfferShippingDetails to each offer, publish one shipping policy under your Organization and reference it from offers, or set shipping in Merchant Center or Search Console instead of markup (in which case the warning may stay, but Google still has your shipping data).
This post covers how to tell whether you need to act, the exact properties each fix requires, how Google decides between markup and account settings, and how to check the result. For the rest of the product markup (price, images, identifiers, variants), see the Product schema guide.
Is a missing shippingDetails field a problem?
Search Console's rich result reports split issues into two kinds. Its rich result status report help describes critical issues, which make an item invalid and stop it appearing as a rich result, and non-critical issues, shown in the table labelled Improve item appearance. Only critical issues make an item invalid.
Google's merchant listing documentation lists shippingDetails among the recommended Offer properties and says OfferShippingDetails "isn't required". Its required properties only matter if you want shipping details to be eligible for the shipping details enhancement. Because the field is recommended, its absence is not a critical issue. So the honest answer is:
| Situation | What to do |
|---|---|
| You sell online and ship physical goods | Add shipping data. Shoppers see delivery cost and time, and the warning goes away. |
| Shipping is already set in Merchant Center or Search Console | The account setting is used. Markup is optional, and the warning can stay. |
| You only sell in store, or sell digital goods | Nothing to ship. You can leave the warning. |
| You cannot state one rate truthfully | Fix the policy page first. Do not invent a number to silence a warning. |
Google says it does not guarantee that features using structured data will show up in search results. Valid markup makes shipping details eligible; it does not guarantee they appear.
Option 1: add OfferShippingDetails to each offer
This is the offer-level fix: a shippingDetails object inside the Offer that each product page already outputs. Google's merchant listing documentation marks three properties as required when you use it:
| Property | Type | Notes from Google's documentation |
|---|---|---|
shippingRate | MonetaryAmount | One rate per entry. Give value or maxValue, plus currency, a three-letter ISO 4217 code that must match the offer's currency. |
shippingDestination | DefinedRegion | addressCountry is required, as an ISO 3166-1 alpha-2 code such as US or DE. |
deliveryTime | ShippingDeliveryTime | Holds handlingTime and transitTime. Only one deliveryTime per entry. |
Inside deliveryTime, handlingTime and transitTime are recommended QuantitativeValue objects. When you use them, Google requires both a minValue and a maxValue, each a non-negative whole number of days, and unitCode must be DAY or d.
Here is a flat-rate example for one country, with illustrative values:
{
"@type": "Offer",
"price": 49.00,
"priceCurrency": "USD",
"availability": "https://schema.org/InStock",
"shippingDetails": {
"@type": "OfferShippingDetails",
"shippingRate": {
"@type": "MonetaryAmount",
"value": 4.95,
"currency": "USD"
},
"shippingDestination": {
"@type": "DefinedRegion",
"addressCountry": "US"
},
"deliveryTime": {
"@type": "ShippingDeliveryTime",
"handlingTime": {
"@type": "QuantitativeValue",
"minValue": 0,
"maxValue": 1,
"unitCode": "DAY"
},
"transitTime": {
"@type": "QuantitativeValue",
"minValue": 2,
"maxValue": 5,
"unitCode": "DAY"
}
}
}
}Free shipping
Google's documentation says to set the rate's value to 0 for free shipping. Keep the currency (Google's own example writes the value as the string "0"; a number works too):
"shippingRate": {
"@type": "MonetaryAmount",
"value": 0,
"currency": "USD"
}If a string is used for the value, Google says to leave out currency symbols, thousands separators and spaces, so "0" is fine and "$0.00" is not.
Several countries or shipping speeds
Each OfferShippingDetails holds one rate. Google says to show multiple options, such as standard and express, with multiple shippingDetails entries. The same applies to countries with different rates: one entry per destination and rate, in an array.
"shippingDetails": [
{
"@type": "OfferShippingDetails",
"shippingRate": { "@type": "MonetaryAmount", "value": 0, "currency": "EUR" },
"shippingDestination": { "@type": "DefinedRegion", "addressCountry": "DE" },
"deliveryTime": {
"@type": "ShippingDeliveryTime",
"handlingTime": { "@type": "QuantitativeValue", "minValue": 0, "maxValue": 1, "unitCode": "DAY" },
"transitTime": { "@type": "QuantitativeValue", "minValue": 1, "maxValue": 3, "unitCode": "DAY" }
}
},
{
"@type": "OfferShippingDetails",
"shippingRate": { "@type": "MonetaryAmount", "value": 9.90, "currency": "EUR" },
"shippingDestination": { "@type": "DefinedRegion", "addressCountry": "FR" },
"deliveryTime": {
"@type": "ShippingDeliveryTime",
"handlingTime": { "@type": "QuantitativeValue", "minValue": 0, "maxValue": 1, "unitCode": "DAY" },
"transitTime": { "@type": "QuantitativeValue", "minValue": 3, "maxValue": 6, "unitCode": "DAY" }
}
}
]Two limits catch multi-country stores. First, the rate currency has to match the offer's priceCurrency, so a page priced in EUR cannot carry a GBP shipping rate. Second, regions inside a country are only partly supported: Google says addressRegion works for the US, Australia and Japan, and postalCode for Australia, Canada and the US, and you should not give both in one DefinedRegion. Without a region, the whole country is the destination.
Option 2: one shipping policy under Organization
Repeating the same rate table in every product page is fragile. Google's merchant shipping policy documentation recommends describing your standard policy once, on one page, as a ShippingService nested under Organization through hasShippingService. Offer-level markup is then for products whose shipping differs, or for sites with no standard policy.
The organization-level format is richer than the offer-level one. ShippingService requires shippingConditions, and each ShippingConditions can set a destination, an order value range, weight, number of items, a rate, a transit time, or doesNotShip. Times use ServicePeriod, with a duration plus optional businessDays and a cutoffTime for handling.
{
"@context": "https://schema.org",
"@type": "Organization",
"@id": "https://example.com/#organization",
"name": "Example Store",
"url": "https://example.com/",
"hasShippingService": {
"@type": "ShippingService",
"@id": "https://example.com/shipping#policy",
"name": "Standard shipping",
"fulfillmentType": "https://schema.org/FulfillmentTypeDelivery",
"handlingTime": {
"@type": "ServicePeriod",
"cutoffTime": "14:00:00-05:00",
"duration": { "@type": "QuantitativeValue", "minValue": 0, "maxValue": 1, "unitCode": "DAY" }
},
"shippingConditions": [
{
"@type": "ShippingConditions",
"shippingDestination": { "@type": "DefinedRegion", "addressCountry": "US" },
"orderValue": { "@type": "MonetaryAmount", "minValue": 0, "maxValue": 49.99, "currency": "USD" },
"shippingRate": { "@type": "MonetaryAmount", "value": 4.95, "currency": "USD" },
"transitTime": {
"@type": "ServicePeriod",
"duration": { "@type": "QuantitativeValue", "minValue": 2, "maxValue": 5, "unitCode": "DAY" }
}
},
{
"@type": "ShippingConditions",
"shippingDestination": { "@type": "DefinedRegion", "addressCountry": "US" },
"orderValue": { "@type": "MonetaryAmount", "minValue": 50, "currency": "USD" },
"shippingRate": { "@type": "MonetaryAmount", "value": 0, "currency": "USD" },
"transitTime": {
"@type": "ServicePeriod",
"duration": { "@type": "QuantitativeValue", "minValue": 2, "maxValue": 5, "unitCode": "DAY" }
}
},
{
"@type": "ShippingConditions",
"shippingDestination": { "@type": "DefinedRegion", "addressCountry": "MX" },
"doesNotShip": true
}
]
}
}This covers a free-shipping threshold, which the offer-level properties Google lists for merchant listings have no field for. Google adds two rules for overlaps: if several conditions apply to one product, it uses the lowest shipping cost, and on a tie, the fastest speed. A condition without a destination applies worldwide, and Google says to set a rate and transit time only when doesNotShip is absent or false.
Referencing the policy from each offer
To connect product pages to that policy, Google's merchant listing documentation shows hasShippingService inside OfferShippingDetails, using only the @id keyword:
{
"@type": "Offer",
"price": 49.00,
"priceCurrency": "USD",
"shippingDetails": {
"@type": "OfferShippingDetails",
"hasShippingService": { "@id": "https://example.com/shipping#policy" }
}
}The @id has to match the one on the ShippingService exactly, including host and fragment. The same reference pattern exists for return policies, which the return policy exceptions post covers, and connecting entities with @id explains how these references work across a graph.
Option 3: settings instead of markup
You do not have to use markup at all. Both Google pages list two alternatives: shipping (delivery) settings in Google Merchant Center, and account-level shipping policies in Search Console, which Google says are added to Merchant Center automatically. Google's Shopping reports and tools help says the Shipping and returns setting under Settings > Shopping appears only when a Merchant Center account is associated with the Search Console property, and only owners or full users of the property can use it.
Which source wins: Merchant Center, Search Console or markup?
Google documents an order of precedence, and the two pages differ slightly. The merchant listing page lists five sources, from strongest to weakest:
- Product-level feeds submitted in Merchant Center
- Content API for Shopping settings
- Settings in Merchant Center or Search Console
- Product-level merchant listing markup
- Organization-level markup
The shipping policy page lists the last four, starting with account-level Content API settings, and adds that if you provide both shipping policy markup and Search Console settings, Google uses only the Search Console information.
In practice, pick one source of truth. If Merchant Center already carries accurate shipping, markup changes nothing Google shows, and the Search Console warning is safe to leave. If markup is your source, make sure no older Merchant Center or Search Console setting overrides it with different numbers. The same reasoning about competing data applies to prices, as in Merchant Center price mismatches.
How to check the fix
- Run one product URL through the Rich Results Test and open the merchant listing item. Confirm
shippingDetailsappears with a rate, destination and delivery time, and that no shipping property is flagged. - Fetch the raw HTML with
curland confirm the JSON-LD is in the server response, not added later by JavaScript:
curl -s "https://example.com/products/blue-mug" | grep -c '"OfferShippingDetails"'- If you used the
@idreference, test the policy page too, and check the@idstring is identical in both places. - Compare the markup with the visible shipping page. Rates, thresholds and countries must match what a shopper reads. Common JSON-LD errors covers syntax problems that hide a block entirely.
- In the Merchant listings report, inspect a fixed URL to check the issue is gone, then request validation from the report. Google notes it can take several days after publishing for it to find and crawl a page.
Frequently asked questions
Does missing shippingDetails stop my products appearing in Google?
No. Google documents shippingDetails as recommended, so the item stays valid. You only lose eligibility for the shipping details enhancement unless shipping is supplied another way.
How do I mark up free shipping?
Set shippingRate.value to 0 with the offer's currency. For free shipping above an order value, use an organization-level ShippingConditions with an orderValue range.
Can I mark up shipping to several countries?
Yes. Add one OfferShippingDetails per destination and rate in a shippingDetails array, or list conditions per country in an organization-level ShippingService. The rate currency must match the offer's currency.
I set shipping in Merchant Center. Why does the warning remain?
The report is about the structured data on the page, and Google does not document it taking account settings into account. Google's precedence puts Merchant Center and Search Console settings above markup, so your account shipping data still applies and the warning can be left.
Check what your product pages publish
Shipping markup only helps if it reaches crawlers in the HTML and matches the page. Run the free check on a product page to see what a crawler receives, or book an audit to have product templates, structured data and the policy pages reviewed together with evidence.
Filed under Structure and schema. Topics: structured-data, ecommerce, json-ld, search-console, google