Skip to main content
GET
/
api
/
v1
/
domains-pdp
# Plain URL
curl --request GET \
  --url 'https://api.firmly.work/api/v1/domains-pdp?url=https://staging.luma.gift/radiant-tee.html' \
  --header 'x-firmly-authorization: YOUR_AUTH_TOKEN'

# URL with query parameters (encoded)
curl --request GET \
  --url 'https://api.firmly.work/api/v1/domains-pdp?url=https%3A%2F%2Fstaging.luma.gift%2Fhero-hoodie.html%3Fvariant%3D123' \
  --header 'x-firmly-authorization: YOUR_AUTH_TOKEN'

{
  "base_sku": "WS12",
  "title": "Radiant Tee",
  "handle": "radiant-tee",
  "description": "A comfortable and stylish tee perfect for any occasion",
  "product_type": "Tees",
  "images": [
    {
      "url": "https://cdn.staging.luma.gift/products/radiant-tee-main.jpg",
      "type": "default"
    }
  ],
  "variant_option_values": [
    {
      "display_name": "Size",
      "property_accessor": "size",
      "position": 0,
      "option_values": [
        {
          "display_name": "Medium",
          "value": "M",
          "available": true
        }
      ]
    }
  ],
  "variants": [
    {
      "handle": "radiant-tee-xs-orange",
      "sku": "WS12-XS-Orange",
      "title": "Radiant Tee - XS Orange",
      "display_name": "XS / Orange",
      "add_to_cart_ref": {
        "variant_id": "WS12-XS-Orange"
      },
      "price": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      },
      "available": true,
      "variant_option_list": ["XS", "Orange"]
    }
  ],
  "reviews": {
    "total_reviews": 127,
    "average_rating": 4.5
  }
}

Documentation Index

Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt

Use this file to discover all available pages before exploring further.

Retrieves product information from a merchant’s product detail page (PDP) URL. This endpoint extracts and returns the same detailed product data as the Get a Product endpoint.

​
Query Parameters

​
url
string
required
The full merchant product page URL. Can be plain or URL-encoded.Examples:
  • https://staging.luma.gift/radiant-tee.html
  • https://staging.luma.gift/hero-hoodie.html?variant=123
If the URL contains query parameters, encode it with percent encoding according to HTTP standards.
​
postal_code
string
Postal code to customize pricing, inventory, or availability, based on location

​
Response

Returns the same Product Details structure as the Get a Product endpoint, including:
  • Base product information
  • Variants with pricing and availability
  • Images and variant options
  • Review information

​
Expected Errors

​
ProductUrlNotImplemented
404
The merchant’s platform doesn’t support product extraction from URLs
# Plain URL
curl --request GET \
  --url 'https://api.firmly.work/api/v1/domains-pdp?url=https://staging.luma.gift/radiant-tee.html' \
  --header 'x-firmly-authorization: YOUR_AUTH_TOKEN'

# URL with query parameters (encoded)
curl --request GET \
  --url 'https://api.firmly.work/api/v1/domains-pdp?url=https%3A%2F%2Fstaging.luma.gift%2Fhero-hoodie.html%3Fvariant%3D123' \
  --header 'x-firmly-authorization: YOUR_AUTH_TOKEN'

{
  "base_sku": "WS12",
  "title": "Radiant Tee",
  "handle": "radiant-tee",
  "description": "A comfortable and stylish tee perfect for any occasion",
  "product_type": "Tees",
  "images": [
    {
      "url": "https://cdn.staging.luma.gift/products/radiant-tee-main.jpg",
      "type": "default"
    }
  ],
  "variant_option_values": [
    {
      "display_name": "Size",
      "property_accessor": "size",
      "position": 0,
      "option_values": [
        {
          "display_name": "Medium",
          "value": "M",
          "available": true
        }
      ]
    }
  ],
  "variants": [
    {
      "handle": "radiant-tee-xs-orange",
      "sku": "WS12-XS-Orange",
      "title": "Radiant Tee - XS Orange",
      "display_name": "XS / Orange",
      "add_to_cart_ref": {
        "variant_id": "WS12-XS-Orange"
      },
      "price": {
        "currency": "USD",
        "value": 22.00,
        "number": 2200,
        "symbol": "$"
      },
      "available": true,
      "variant_option_list": ["XS", "Orange"]
    }
  ],
  "reviews": {
    "total_reviews": 127,
    "average_rating": 4.5
  }
}

​
Use Cases

This endpoint is particularly useful for:

Browser Extensions

Extract product data when users browse merchant sites

Social Commerce

Handle shared product links from social media

Universal Wishlists

Save products from any supported merchant

Price Tracking

Monitor product prices across different stores

​
Example: URL-Based Product Import

// User provides a product URL
const productUrl = 'https://staging.luma.gift/hero-hoodie.html';

// Fetch product details from URL
const response = await fetch(
  `https://api.firmly.work/api/v1/domains-pdp?url=${encodeURIComponent(productUrl)}`,
  {
    headers: {
      'x-firmly-authorization': authToken
    }
  }
);

const product = await response.json();

// Display product information
console.log(`Product: ${product.title}`);
console.log(`Price: ${product.variants[0].price.symbol}${product.variants[0].price.value}`);

// Add to cart using the variant_id
const variantId = product.variants[0].add_to_cart_ref.variant_id;
await addToCart(variantId);