Get Product by ID

Look up a product's content and video JSON-LD metadata by its Desire Company ID. The product is returned only if it is associated with your partner account. Each returned video includes a ready-to-embed schema.org VideoObject in its json_ld field.

GET /api/v1/public/products/:id

Authentication

Requires an API key. See Authentication.

Path parameters

Parameter	Type	Description
id	integer	The product's Desire Company ID. Must be a positive integer.

A non-numeric or non-positive id returns 400 invalid_product_id. You can obtain a product's id from the data.product.id field of any Get Product by SKU response.

Request

curl

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

Node.js

const res = await fetch(
  'https://api.prod.thedesirecompany.com/api/v1/public/products/123',
  { headers: { Authorization: `Bearer ${process.env.TDC_API_KEY}` } },
);
const { data } = await res.json();

Response

200 OK

{
  "data": {
    "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.status	string	active or inactive. inactive means the product has been deactivated in TDC.
data.product	object	The product content and its videos — identical shape to Get Product by SKU.

The data.product object contains exactly: id, title, description, short_description, image, what_text, who_text, why_text, and videos. Each entry in videos has id, name, aspect_ratio, length, and json_ld — see Get Product by SKU → Response fields and Embedding the JSON-LD. Internal metadata is never exposed.

Errors

Status	error	When
400	invalid_product_id	id is not a positive integer
401	missing_api_key	No API key supplied
401	invalid_api_key	Key is unknown or revoked
404	product_not_found	No product with this ID in your partner catalog
429	rate_limit_exceeded	Over 100 requests/minute
500	internal_error	Unexpected server error — retry later

Example:

{ "error": "product_not_found", "message": "No product found for this ID." }

See Errors for the full reference.