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.

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",
          "json_ld": {
            "@context": "https://schema.org",
            "@type": "VideoObject",
            "@id": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456",
            "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",
            "embedUrl": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456",
            "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",
              "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"
            }
          }
        }
      ]
    }
  }
}

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, one blob per PDP URL, rather than on the video.

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 video file placed on that page (the JSON-LD's `contentUrl`).
`retailer`	string \| null	Retailer label, e.g. `Sam's Club`.
`json_ld`	object \| null	A schema.org `VideoObject` anchored to `pdp_url` — inject it directly into that page as structured data (see Embedding the JSON-LD). `null` if it hasn't been generated yet.

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[].json_ld is a complete schema.org VideoObject whose @id, embedUrl, and isPartOf all point at that entry's pdp_url. 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:

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",
  "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",
  "embedUrl": "https://www.samsclub.com/ip/hellmanns-avocado-oil-mayonnaise-32-oz/123456",
  "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",
    "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 ​