Get Product by SKU

Look up a product's content and video 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 returned video includes a ready-to-embed schema.org VideoObject in its json_ld field.

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,
          "json_ld": {
            "@context": "https://schema.org",
            "@type": "VideoObject",
            "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,
            "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",
              "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" }
          }
        }
      ]
    }
  }
}

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, each with embeddable JSON-LD (see below). Empty array if the product has no published videos.

`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.
`json_ld`	object	A schema.org `VideoObject` — inject it directly into your PDP as structured data (see Embedding the JSON-LD).

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

Embedding the JSON-LD

Each video.json_ld is a complete schema.org VideoObject. Serialize it into a <script type="application/ld+json"> tag on your 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",
  "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,
  "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",
    "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" }
}
</script>

Generating it server-side from the API response:

const { data } = await res.json();
const blocks = data.product.videos
  .map((v) => `<script type="application/ld+json">${JSON.stringify(v.json_ld)}</script>`)
  .join('\n');
// inject `blocks` 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[] ​

Embedding the JSON-LD ​

Errors ​