Get Product by SKU

Look up a product's content, videos, and PDP JSON-LD metadata by your own SKU. The lookup is scoped to your partner account, so the SKU is matched only within your catalog. Each entry in pdp_urls is one retailer product page for the product and carries a ready-to-embed schema.org VideoObject in its json_ld field, anchored to that page's URL.

SKUs belong to a page, not to the product

A SKU is registered against the specific retailer page that sells it, so one product can carry a different SKU on each of its PDP URLs. This endpoint therefore returns only the pages that carry the SKU you asked for — the pages you would actually embed that SKU's markup on. To retrieve every page for the product regardless of SKU, use Get Product by ID with the id returned here.

GET /api/v1/public/sku/:sku

Authentication

Requires an API key. See Authentication.

Path parameters

Parameter	Type	Description
`sku`	string	Your product SKU. 1–50 characters, and only letters, numbers, hyphens (`-`), underscores (`_`), and periods (`.`) — i.e. `^[A-Za-z0-9._-]+$`.

A SKU that is empty, longer than 50 characters, or contains any other character returns 400 invalid_sku.

Request

curlNode.js

bash

curl https://api.prod.thedesirecompany.com/api/v1/public/sku/ABC123 \
  -H "Authorization: Bearer dk_live_your_key_here"

const res = await fetch(
  'https://api.prod.thedesirecompany.com/api/v1/public/sku/ABC123',
  { headers: { 'X-API-Key': process.env.TDC_API_KEY } },
);
const { data } = await res.json();

Response

200 OK

json

{
  "data": {
    "sku": "HELL-AVO-32",
    "status": "active",
    "product": {
      "id": 9066,
      "title": "Hellmann's Purely 100% Avocado Oil Mayonnaise",
      "description": "A real mayonnaise made with 100% avocado oil…",
      "short_description": "Avocado Oil Mayo made with a squeeze of lime and a pinch of black pepper.",
      "image": "https://cdn.thedesirecompany.com/images/hellmanns-avocado-oil-mayo.avif",
      "what_text": "What it is…",
      "who_text": "Who it's for…",
      "why_text": "Why it matters…",
      "videos": [
        {
          "id": 3557,
          "name": "Sam's Club In-Store Digital Signage",
          "aspect_ratio": "16x9",
          "length": 20.02
        }
      ],
      "pdp_urls": [
        {
          "id": 412,
          "pdp_url": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456",
          "video_file_url": "https://cdn.thedesirecompany.com/videos/hellmanns-avocado-mayo-16x9.mp4",
          "retailer": "Sam's Club",
          "skus": ["HELL-AVO-32"],
          "videos": [
            {
              "video_id": 3557,
              "video_file_url": "https://cdn.thedesirecompany.com/videos/hellmanns-avocado-mayo-16x9.mp4",
              "json_ld": { "...": "the same VideoObject as json_ld below — one per video on the page" }
            }
          ],
          "json_ld": {
            "@context": "https://schema.org",
            "@type": "VideoObject",
            "@id": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456#video-3557",
            "name": "Hellmann's 100% Avocado Oil Mayonnaise at Sam's Club",
            "description": "This video showcases Hellmann's Purely 100% Avocado Oil Mayonnaise, highlighting its high-quality ingredients, Keto and Paleo certifications, and a subtle lime flavor. It encourages viewers to purchase the 32-ounce jar at Sam's Club for everyday meals.",
            "transcript": "Hellmann's purely 100% Avocado Oil Mayonnaise brings flavor to everyday meals with high quality ingredients. Keto and Paleo certified, it's flavorful and finished with a subtle hint of lime for a fresh, balanced taste. Pick up the 32-ounce jar at Sam's Club and keep it stocked in your kitchen.",
            "inLanguage": "en",
            "isFamilyFriendly": true,
            "contentUrl": "https://cdn.thedesirecompany.com/videos/hellmanns-avocado-mayo-16x9.mp4",
            "genre": ["Advertisement", "Product Showcase", "Food & Drink"],
            "keywords": ["Hellmann's", "Avocado Oil Mayonnaise", "Keto", "Paleo", "Sam's Club", "lime", "cooking"],
            "creator": {
              "@type": "Person",
              "name": "Alexandra Caspero",
              "jobTitle": "CEO/Founder - Wellness Expert - Dietician"
            },
            "publisher": { "@type": "Organization", "name": "Hellmann's" },
            "about": {
              "@type": "Product",
              "@id": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456#product",
              "brand": { "@type": "Brand", "name": "Hellmann's" },
              "additionalProperty": [
                { "@type": "PropertyValue", "name": "Oil Type", "value": "100% Avocado Oil" },
                { "@type": "PropertyValue", "name": "Certification", "value": "Keto certified" },
                { "@type": "PropertyValue", "name": "Certification", "value": "Paleo certified" },
                { "@type": "PropertyValue", "name": "Flavor Note", "value": "Subtle hint of lime" },
                { "@type": "PropertyValue", "name": "Size", "value": "32-ounce jar" }
              ]
            },
            "isPartOf": {
              "@type": "WebPage",
              "@id": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456",
              "url": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456"
            }
          },
          "page_json_ld": { "...": "every video on the page as one VideoObject block (an @graph when several)" }
        }
      ]
    }
  }
}

Response fields

Field	Type	Description
`data.sku`	string	The SKU you requested.
`data.status`	string	`active` or `inactive`. `inactive` means the product has been deactivated in TDC.
`data.product`	object	The product content and its videos (see below).

`data.product`

Field	Type	Description
`id`	number	The product's Desire Company ID (use it with Get Product by ID).
`title`	string	Product title.
`description`	string \| null	Full marketing description.
`short_description`	string	Short summary for cards/previews.
`image`	string	Primary product image URL.
`what_text`	string	Expert copy — what the product is.
`who_text`	string	Expert copy — who it's for.
`why_text`	string	Expert copy — why it matters.
`videos`	array	The product's published videos (see below). Empty array if the product has no published videos.
`pdp_urls`	array	The product's retailer PDP URLs, each with embeddable JSON-LD (see below). Empty array if no PDP URLs are configured.

`data.product.videos[]`

Field	Type	Description
`id`	number	The video's ID.
`name`	string \| null	Video name.
`aspect_ratio`	string	e.g. `16x9`, `9x16`, `1x1`.
`length`	number	Duration in seconds.

`data.product.pdp_urls[]`

A product can be sold on several retailer product pages, and each page needs structured data anchored to its own URL — so JSON-LD lives here, per PDP URL, rather than on the video. A page can carry more than one of the product's videos: videos lists each one with its own VideoObject, while video_file_url and json_ld keep the original single-video shape (the first video on the page) so existing integrations keep working.

Field	Type	Description
`id`	number	The PDP URL entry's ID.
`pdp_url`	string	The retailer product page URL this entry describes.
`video_file_url`	string \| null	Direct URL of the first video file placed on that page (that video's `contentUrl`). Same as `videos[0].video_file_url`.
`retailer`	string \| null	Retailer label, e.g. `Sam's Club`.
`skus`	array of string	The SKUs registered against this specific page, sorted alphabetically. Empty array if none.
`videos`	array	Every one of the product's videos placed on this page, in the order they were added: `video_id` (matches `data.product.videos[].id`), `video_file_url`, and `json_ld` — that video's schema.org `VideoObject` anchored to `pdp_url` (`null` until generated). Empty when no video has been placed on the page yet.
`json_ld`	object \| null	The first video's `VideoObject` — same as `videos[0].json_ld` — for integrations that inject one block per page (see Embedding the JSON-LD). `null` if it hasn't been generated yet.
`page_json_ld`	object \| null	The one block for the page: every video on it as a schema.org `VideoObject` (a single video is a plain node, several are an `@graph`), each pointing at the page's product through `about`. TDC's videos carry transcripts; the page's other videos are described from what is visible (name, poster, duration, file). Never a `Product` node: the page already has its own. `null` until generated, or while no video in it passes Google's required-field check.

Only these fields are returned; internal metadata is never exposed.

JSON-LD is kept fresh — re-fetch periodically

json_ld is not static: TDC regenerates it when the underlying video's transcript is added or refined (better names, descriptions, and keywords over time), and an entry that is null today may be populated once its video content ships. Fetch at render/build time or on a daily cache rather than embedding a one-time snapshot.

Embedding the JSON-LD

Each pdp_urls[].videos[].json_ld (and pdp_urls[].json_ld, the first of them) is a complete schema.org VideoObject anchored to that entry: its isPartOf is the pdp_url, its @id is that URL plus #video-<video_id>, and its contentUrl is the video's video_file_url — the video file you placed on the page. Serialize it into a <script type="application/ld+json"> tag on that product page so search engines can index the video for video rich results. A page with several of the product's videos gets one block per entry in videos — or inject page_json_ld, which carries them all (and the page's other videos) as one @graph beside the page's own Product markup:

html

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "@id": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456#video-3557",
  "name": "Hellmann's 100% Avocado Oil Mayonnaise at Sam's Club",
  "description": "This video showcases Hellmann's Purely 100% Avocado Oil Mayonnaise, highlighting its high-quality ingredients, Keto and Paleo certifications, and a subtle lime flavor. It encourages viewers to purchase the 32-ounce jar at Sam's Club for everyday meals.",
  "transcript": "Hellmann's purely 100% Avocado Oil Mayonnaise brings flavor to everyday meals with high quality ingredients. Keto and Paleo certified, it's flavorful and finished with a subtle hint of lime for a fresh, balanced taste. Pick up the 32-ounce jar at Sam's Club and keep it stocked in your kitchen.",
  "inLanguage": "en",
  "isFamilyFriendly": true,
  "contentUrl": "https://cdn.thedesirecompany.com/videos/hellmanns-avocado-mayo-16x9.mp4",
  "genre": ["Advertisement", "Product Showcase", "Food & Drink"],
  "keywords": ["Hellmann's", "Avocado Oil Mayonnaise", "Keto", "Paleo", "Sam's Club", "lime", "cooking"],
  "creator": {
    "@type": "Person",
    "name": "Alexandra Caspero",
    "jobTitle": "CEO/Founder - Wellness Expert - Dietician"
  },
  "publisher": { "@type": "Organization", "name": "Hellmann's" },
  "about": {
    "@type": "Product",
    "@id": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456#product",
    "brand": { "@type": "Brand", "name": "Hellmann's" },
    "additionalProperty": [
      { "@type": "PropertyValue", "name": "Oil Type", "value": "100% Avocado Oil" },
      { "@type": "PropertyValue", "name": "Certification", "value": "Keto certified" },
      { "@type": "PropertyValue", "name": "Certification", "value": "Paleo certified" },
      { "@type": "PropertyValue", "name": "Flavor Note", "value": "Subtle hint of lime" },
      { "@type": "PropertyValue", "name": "Size", "value": "32-ounce jar" }
    ]
  },
  "isPartOf": {
    "@type": "WebPage",
    "@id": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456",
    "url": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456"
  }
}
</script>

Generating it server-side from the API response — pick the entry whose pdp_url matches the page you're rendering:

const { data } = await res.json();
const pageUrl = 'https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456';
// Only inject the entry anchored to the page you're rendering — a JSON-LD
// blob is tied to its own pdp_url, so never inject one from another page.
const entry = data.product.pdp_urls.find((u) => u.pdp_url === pageUrl);
if (entry && entry.json_ld) {
  const block = `<script type="application/ld+json">${JSON.stringify(entry.json_ld)}</script>`;
  // inject `block` into your PDP <head> or near the video player
}

Errors

Status	`error`	When
`400`	`invalid_sku`	SKU is empty, over 50 chars, or has disallowed characters
`401`	`missing_api_key`	No API key supplied
`401`	`invalid_api_key`	Key is unknown or revoked
`404`	`sku_not_found`	No product with this SKU in your partner catalog
`429`	`rate_limit_exceeded`	Over 100 requests/minute
`500`	`internal_error`	Unexpected server error — retry later

Example:

json

{ "error": "sku_not_found", "message": "No product found for this SKU." }

See Errors for the full reference.

Get Product by SKU ​

Authentication ​

Path parameters ​

Request ​

Response ​

Response fields ​

data.product ​

data.product.videos[] ​

data.product.pdp_urls[] ​

Embedding the JSON-LD ​

Errors ​