XooCode(){

UnitPriceSpecification

UnitPriceSpecification is the PriceSpecification subtype you reach for whenever price depends on quantity or time: per-kilogram grocery pricing, per-seat SaaS licensing, per-kilowatt-hour utility rates, per-month subscriptions.

It adds 8 direct properties on top of PriceSpecification:

  • unitCode: UN/CEFACT code (KGM kilograms, MON months, C62 "one" / each, KWH kilowatt-hours).
  • unitText: human-readable label (falls back when unitCode is unfamiliar).
  • referenceQuantity: the quantity the price refers to (e.g. "$4.99 per 100 grams" is price = 4.99 with referenceQuantity.value = 100 and referenceQuantity.unitCode = GRM).
  • billingDuration: subscription billing period (Number of billingIncrement units).
  • billingIncrement: minimum chargeable quantity (e.g. parking in 30-minute increments).
  • billingStart: when billing starts (free-trial end).
  • priceType: a free-text qualifier ("ListPrice", "MSRP", "Regular", "Sale").
  • priceComponentType: distinguishes components inside a CompoundPriceSpecification.

Full example of schema.org/UnitPriceSpecification json-ld markup

The markup is verified as valid with Rich Results Test from Google.

Highlight legend:Required by GoogleRecommendedOptional
schema.org/UnitPriceSpecification
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Offer",
  "itemOffered": { "@type": "SoftwareApplication", "name": "XooStructured Enterprise" },
  "priceSpecification": {
    "@type": "UnitPriceSpecification",
    "price": 49.00,
    "priceCurrency": "USD",
    "unitCode": "MON",
    "unitText": "seat-month",
    "referenceQuantity": { "@type": "QuantitativeValue", "value": 1, "unitCode": "C62", "unitText": "seat" },
    "billingDuration": 1,
    "billingIncrement": 1,
    "billingStart": 14,
    "priceType": "ListPrice",
    "valueAddedTaxIncluded": false
  }
}
</script>

Subscription vs per-unit commodity

The same type covers both: a SaaS plan is a UnitPriceSpecification with unitCode: MON and a billingDuration; a grocery item uses unitCode: KGM or GRM and a referenceQuantity.

Minimal valid version

The smallest markup that still produces a valid UnitPriceSpecification entity. Use it as the floor. Reach for the advanced example above when you want search engines and AI agents to understand more about your content.

schema.org/UnitPriceSpecification (minimal)
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "UnitPriceSpecification",
  "price": 49.00,
  "priceCurrency": "USD",
  "unitCode": "MON",
  "billingDuration": 1
}
</script>

Google rich results this unlocks

Markup matching this example makes your page eligible for the following Google Search rich results. The primary target drives the required / recommended property classification in the advanced code block above.

  • Product / Offer rich result (via containing Offer)primary
    Google docs

Common UnitPriceSpecification mistakes

Mistakes that pass validation but silently fail to earn rich results or mislead consumers walking the graph. Avoid these and your markup will be ahead of most sites in the wild.

  1. 01

    unitText without unitCode

    Wrong
    "unitText": "per month" and no unitCode
    Right
    Always add the UN/CEFACT unitCode alongside unitText for machine consumers

    Google and most consumers match on unitCode; unitText is the human-readable fallback, not the primary signal.

  2. 02

    referenceQuantity.value = price for per-100g goods

    Wrong
    price 4.99, referenceQuantity.value 4.99
    Right
    price 4.99, referenceQuantity.value 100 (grams)

    referenceQuantity carries the quantity the price refers to, not the price itself.

  3. 03

    billingDuration as ISO 8601 string

    Wrong
    "billingDuration": "P1M"
    Right
    billingDuration: 1 and unitCode: MON (the period unit)

    billingDuration expects a Number of unitCode periods, not an ISO duration.

Schema properties in this example

UnitPriceSpecificationPriceSpecificationStructuredValueOfferitemOfferedSoftwareApplicationpriceSpecificationpricepriceCurrencyunitCodeunitTextreferenceQuantityQuantitativeValuebillingDurationbillingIncrementbillingStartpriceTypevalueAddedTaxIncluded

Also mentioned in 3 other examples

UnitPriceSpecification also appears in CompoundPriceSpecification, StructuredValue, and TaxiService. See the full UnitPriceSpecification schema page for every reference.

About the example data

XooStructured Enterprise priced as a per-seat monthly SaaS plan at $49 per seat per month, with a 14-day free trial.

Comments

Loading comments...

Leave a comment