Contents

Widgets

Read-only widgets for product pages, served with the same public key, origin check and consent rules as the events.

Base URL, authentication and conventions of this API are on the Collector API page.

get/size/{product}

Get size advice for a product

Powers a size selector on the product page: the sizes the product is sold in, how it fits (from size swaps observed across shoppers, the same for everyone) and, when every condition below holds, the size recommended to the shopper who is looking.

The personal advice appears only if:

  1. a customer reference signed by your store is supplied and verifies (a plain id is ignored);
  2. the visitor has granted consent including the personalisation purpose (recorded via POST /consent or an events batch);
  3. the customer has enough purchase history.

Otherwise the answer stays impersonal and why says which condition was missing. A failed verification is never an error. The response never contains the customer's size profile or purchase list, and the call is not logged against the customer.

Only published products answer with sizes: a draft, archived or status-less product (or an unknown id) answers like a product without sizes (why: "no-sizes"), so the widget can hide itself.

Same key and origin rules as the other operations (for this GET, Referer is accepted when Origin is absent). From a browser, pass key, visitor and customer as query parameters: custom headers trigger a CORS preflight that the Collector does not answer. The customer reference is short-lived (15 minutes by default), so it is harmless in access logs.

Rate limits. Shared with all Collector operations: 120 requests per minute per IP, 20,000 per minute per key.

GET https://api-catalog.nucleoplatform.com/api/collect/v1/size/{product}
Authentication: key query parameter or X-Nucleo-Key header
Rate limit: 120 requests per 1m, per IP

Path parameters

  • productintegerrequired

    The Nucleo Catalog product id (numeric), not the Shopify product id.

    min 1
    Example: 4821

Query parameters

  • visitorstring

    The visitor id used in the events batches. Used only to read the visitor's consent.

    max length 64
    Example: 8b1f0c2e9d7a4b3c6e5f1a2b3c4d5e6f
  • customerstring

    The signed customer reference (see CustomerReference). Ignored when the X-Nucleo-Customer-Ref header is present.

    max length 512
    Example: v1.12.7012345678.1791104400.9c1e4b7a2f0d3c6e8b5a1f4d7c0e3b6a9d2f5c8e1b4a7d0c3f6e9b2a5d8c1f4e

Headers

  • X-Nucleo-Customer-Refstring

    The signed customer reference, for server-side callers. Takes precedence over customer (max 512 characters).

    max length 512
  • Originstringrequired

    Required. Browsers set it; servers and tools must send it (on GET, Referer is accepted instead). Its host must equal one of the installation's domains, or be a subdomain of a wildcard domain (*.acme.example matches shop.acme.example and eu.shop.acme.example, not acme.example). A wildcard must sit under your own registrable domain: it is refused on a public suffix (*.com, *.co.uk) and on shared platforms where every subdomain belongs to someone else (for example *.myshopify.com, *.vercel.app, *.netlify.app, *.github.io); such a wildcard saved earlier matches nothing. Register those hosts by their exact name. null is accepted only when the installation has the Web Pixel enabled. An origin that does not match answers 403.

    Example: https://shop.acme.example
  • Refererstring

    On GET operations only, used for the origin check when Origin is absent.

    Example: https://shop.acme.example/products/classic-tee-black

Responses

  • 200Always answered, with or without a personal recommendation.
    Headers
    • Access-Control-Allow-Origin Echoes the request Origin when it was present and allowed.
    • Vary Always Origin.
    • dataobjectrequired
      Child attributes
      • productobjectrequired
        Child attributes
        • idinteger
        • sizesarray of string

          Sizes the product is sold in, in wearing order. Empty for one-size, unpublished or unknown products.

      • readingSizeReading | nullrequired
        SizeReading
        • directionstring
          One ofruns_largeruns_smallas_expected
        • basisstring

          product this item's own swaps; otherwise items of the same segment, fit (and type).

          One ofproductgender-fit-typegender-fit
        • peopleinteger

          Shoppers whose swaps back the reading (at least 8 for a product, 40 for a family).

        • sharenumber

          Share of swaps towards the larger size.

        • basenumber

          The same share for the whole segment, for comparison.

        • fitstring | null

          The product's fit attribute value.

        • segmentstring

          The product's gender segment (unknown when not set).

          Example: man
        • saysstring

          A ready-made English sentence.

      • adviceSizeAdvice | nullrequired
        SizeAdvice
        • sizestring
          Example: M
        • usualstring

          The shopper's usual size on this segment and scale.

          Example: L
        • stepinteger

          Steps from the usual size (never more than one).

          One of-101
        • segmentstring
          Example: man
        • scalestring

          Size scale identifier.

          Example: alpha
        • basisstring
          One ofproductgender-fit-typegender-fitnone
        • peopleinteger
        • sharenumber | null
        • basenumber | null
        • fitstring | null
        • confidentboolean

          Whether the usual size is settled (an unsettled size is never adjusted).

        • keptinteger

          Items kept in the usual size.

        • seeninteger

          Items considered.

        • reasonstring
          One ofalignedstepunsettledgapno-largerno-smallerno-fit-data
        • saysstring

          A ready-made English sentence (third person, for staff or UI copy).

      • personalisedbooleanrequired
      • whystring | nullrequired

        Why the answer is not personal: anonymous no customer reference · unverified the reference did not verify · no-consent the visitor has not granted personalisation · no-history not enough purchase history · no-sizes the product has no sizes (or is not published). null when personalised.

        One ofanonymousunverifiedno-consentno-historyno-sizesnull
  • 403The installation is paused, or the origin is not one of its domains. Both answer the same body; the exact reason is visible to the merchant in Catalog › Shoppers › Test events.
    • messagestringrequired
  • 404The key is missing, malformed or unknown (no detail is given on purpose).
    • messagestringrequired
  • 409The store behind the key is not provisioned yet.
    • messagestringrequired
  • 422A query parameter is too long (standard validation error shape).
    • messagestringrequired
    • errorsobjectrequired
  • 429Rate limit exceeded (120 requests per minute per IP, or 20,000 per minute per key). Nothing is written.
    Headers
    • Retry-After Seconds to wait before retrying.
    • X-RateLimit-Limit Requests allowed per minute for the client IP.
    • X-RateLimit-Remaining Always 0 on a 429.
    • X-RateLimit-Reset Unix timestamp at which the window resets.
    • messagestringrequired
Request
curl -X GET "https://api-catalog.nucleoplatform.com/api/collect/v1/size/4821?key=$NUCLEO_COLLECTOR_KEY&visitor=8b1f0c2e9d7a4b3c6e5f1a2b3c4d5e6f&customer=v1.12.7012345678.1791104400.9c1e4b7a2f0d3c6e8b5a1f4d7c0e3b6a9d2f5c8e1b4a7d0c3f6e9b2a5d8c1f4e" \
  -H 'Origin: https://shop.acme.example' \
  -H 'Referer: https://shop.acme.example/products/classic-tee-black' \
  -H 'Accept: application/json'
Response
{
  "data": {
    "product": {
      "id": 4821,
      "sizes": [
        "XS",
        "S",
        "M",
        "L",
        "XL"
      ]
    },
    "reading": {
      "direction": "runs_large",
      "basis": "product",
      "people": 64,
      "share": 0.297,
      "base": 0.512,
      "fit": "oversize",
      "segment": "man",
      "says": "Runs large: 70% of the 64 shoppers who swapped size on this item kept the smaller one. Most people do better one size down from their usual."
    },
    "advice": {
      "size": "M",
      "usual": "L",
      "step": -1,
      "segment": "man",
      "scale": "alpha",
      "basis": "product",
      "people": 64,
      "share": 0.297,
      "base": 0.512,
      "fit": "oversize",
      "confident": true,
      "kept": 6,
      "seen": 7,
      "reason": "step",
      "says": "Take M instead of their usual L: 70% of the 64 shoppers who swapped size on this item kept the smaller one."
    },
    "personalised": true,
    "why": null
  }
}
Was this page helpful?