> ## Documentation Index
> Fetch the complete documentation index at: https://developer.dashsocial.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Product Page Galleries: API integration guide
> Build fully custom Product Page Galleries using the Dash Social API for product detail pages.
## Overview
Use Dash Social's API to build fully custom Product Page Galleries that match your brand's layout and infrastructure. The API gives you complete design control, avoids third-party JavaScript, and supports server-side caching for fast page loads. You can integrate it into any web or mobile stack.
For a quick, prebuilt option with minimal setup, see the Product Page Gallery Widget →
Embed product-linked media on PDPs using the Product Page Gallery widget.
## Before starting
To implement a product gallery, make sure:
* Your product feed is set up and synced in the Dash Library. [Set up your product feed](https://developer.dashsocial.com/guides/social-commerce/product-feed/product-feed-setup-guide).
* Your media is linked to products in the Library. [Learn how](https://help.dashsocial.com/hc/en-us/articles/4426716747789-Implementing-Product-Page-Galleries#h_01H9V4M3DA2TCEVE7MQ00DEMR1).
### Access requirements
* No API key or authentication required
* Rate limited per IP address
## Key concepts
* **`product_source_id`**: Unique product identifier (SKU) from your feed
* **`product_source_group_id`**: Shared ID used to group product variants into a single gallery
* **`hide_in_widget`**: Flag to exclude media from rendering. Filter these out before displaying the gallery
## Implementation
### Query media by product ID
#### Step 1: Find the product ID/SKU
This should match the product's ID in your e-commerce system and in your product feed.
#### Step 2: Make the API call
This query returns all media tagged to the product with `product_source_id = APPLE-001`, along with product metadata and localization fields:
```http theme={null}
GET https://library-backend.dashsocial.com/public/brands/{brand_id}/products/media?product_source_id=APPLE-001
```
For full parameter and response details, see the [API reference](/api-reference/library/product/retrieve-product-media).
### Querying media for multiple products
#### When to use
You have product variants like T-shirt Red, Yellow, and Blue but want to group them into a single gallery on your PDP.
#### Step 1: Add group ID to your feed
To group related products, add a group ID column in your product feed. Each variant should share the same group ID (e.g., `TSHIRT`).
| SKU | Group ID |
| ------------- | -------- |
| TSHIRT-RED | TSHIRT |
| TSHIRT-BLUE | TSHIRT |
| TSHIRT-YELLOW | TSHIRT |
This setup is required. The API won't return grouped media unless the group ID is present and consistent across variants in the feed.
Populate this column with the parent product's ID (e.g., `TSHIRT`) for each variant row.
#### Step 2: Query with product\_source\_group\_id
```http theme={null}
GET https://library-backend.dashsocial.com/public/brands/{brand_id}/products/media?product_source_group_id=TSHIRT
```
This fetches all media linked to product variants sharing the group ID `TSHIRT`.
### API behavior tips
#### Hidden media
* If a media item has `hide_in_widget: 1`, it has been marked as hidden from the product page gallery in the Dash UI.
* These media are still included in API responses.
* Filter them out before rendering the gallery.
#### TikTok media is returned as images
* Due to a technical limitation, TikTok media always appears with `"type": "IMAGE"` in API responses.
* Use the `tiktok.embed_url` field to render the playable video directly in your gallery.
### Sample response
```json theme={null}
[
{
"brand_id": "",
"duration": null,
"hide_in_widget": 0,
"image_sizes": {
"medium_square": {
"height": 640,
"url": "https://images.dashsocial.com/...",
"width": 640
},
"original": {
"height": 678,
"size": 486884,
"url": "https://cdn.dashsocial.com/...",
"width": 742
},
"original_converted": {
"height": 678,
"size": 54095,
"url": "https://cdn.dashsocial.com/...",
"width": 742
},
"small": {
"height": 400,
"url": "https://images.dashsocial.com/...",
"width": 437
},
"small_square": {
"height": 400,
"url": "https://images.dashsocial.com/...",
"width": 400
}
},
"media_group": "365399013",
"media_id": 368799697,
"media_type": "IMAGE",
"original_height": "678",
"original_width": "742",
"predictions": {
"eng": 0.33188
},
"products": [
{
"bounding_box": null,
"deleted": 0,
"description": "Fresh seasonal apple.",
"hide_in_widget": 0,
"id": 6124998,
"image_url": "https://cdn.dashsocial.com/products/original_images/...",
"product": {
"archived": false,
"availability": null,
"brand_id": "",
"currency_code": null,
"description": "Fresh seasonal apple.",
"id": 61448488,
"image_url": "https://cdn.dashsocial.com/products/original_images/...",
"is_disabled": 0,
"price": null,
"product_overrides": [
{
"currency_code": null,
"id": 2830105,
"override": "FR",
"price": null,
"source_id": "APPLE-001",
"title": "Pomme",
"url": null
}
],
"source_group_id": null,
"source_id": "APPLE-001",
"status": "READY_PROC",
"title": "Apple",
"url": "https://example.com/products/apple"
},
"product_groups": [
{
"country_code": null,
"description": "Fresh seasonal apple.",
"image_url": "https://cdn.dashsocial.com/products/original_images/...",
"source_id": "APPLE-001",
"title": "Apple",
"url": "https://example.com/products/apple"
}
],
"product_id": 61448488,
"source_id": "APPLE-001",
"title": "Apple",
"url": "https://example.com/products/apple",
"x": 0.532609,
"y": 0.47619
}
],
"source_data": null,
"type": "UPLOADED",
"urls": {
"640": "https://images.dashsocial.com/...",
"full": "https://cdn.dashsocial.com/...",
"original": "https://cdn.dashsocial.com/...",
"ratio": "https://images.dashsocial.com/...",
"thumbs": "https://images.dashsocial.com/..."
},
"video_sizes": {}
},
{
"brand_id": "",
"duration": null,
"hide_in_widget": 1,
"image_sizes": {
"medium_square": {
"height": 640,
"url": "https://images.dashsocial.com/...",
"width": 640
},
"original": {
"height": 1080,
"size": 312044,
"url": "https://cdn.dashsocial.com/...",
"width": 1080
}
},
"media_group": "412057891",
"media_id": 412057892,
"media_type": "IMAGE",
"original_height": "1080",
"original_width": "1080",
"predictions": {
"eng": 0.61204
},
"products": [
{
"bounding_box": null,
"deleted": 0,
"description": "Fresh seasonal apple.",
"hide_in_widget": 0,
"id": 6124999,
"image_url": "https://cdn.dashsocial.com/products/original_images/...",
"product": {
"archived": false,
"availability": null,
"brand_id": "",
"currency_code": null,
"description": "Fresh seasonal apple.",
"id": 61448488,
"image_url": "https://cdn.dashsocial.com/products/original_images/...",
"is_disabled": 0,
"price": null,
"product_overrides": [],
"source_group_id": null,
"source_id": "APPLE-001",
"status": "READY_PROC",
"title": "Apple",
"url": "https://example.com/products/apple"
},
"product_groups": [
{
"country_code": null,
"description": "Fresh seasonal apple.",
"image_url": "https://cdn.dashsocial.com/products/original_images/...",
"source_id": "APPLE-001",
"title": "Apple",
"url": "https://example.com/products/apple"
}
],
"product_id": 61448488,
"source_id": "APPLE-001",
"title": "Apple",
"url": "https://example.com/products/apple",
"x": 0.45,
"y": 0.52
}
],
"source_data": {
"caption": "Loving the new harvest season! #fresh #organic",
"hashtags": ["fresh", "organic"],
"id": "17854321098765432",
"image_url": "https://images.dashsocial.com/...",
"instagram_media_type": "IMAGE",
"instagram_user": {
"id": "987654321",
"username": "example_user"
},
"like_count": 284,
"timestamp": "2025-09-12T14:22:00+0000",
"type": "INSTAGRAM_UGC",
"url": "https://www.instagram.com/p/..."
},
"type": "INSTAGRAM_UGC",
"urls": {
"640": "https://images.dashsocial.com/...",
"full": "https://cdn.dashsocial.com/...",
"original": "https://cdn.dashsocial.com/...",
"ratio": "https://images.dashsocial.com/...",
"thumbs": "https://images.dashsocial.com/..."
},
"video_sizes": {}
}
]
```
## Server-side caching
To improve load speed and reduce API calls, cache Product Page Gallery data on your server instead of requesting it on every page load.
### Why cache API responses?
* **Faster PDP load times:** Serve gallery content instantly from your backend.
* **Lower API usage:** Avoid duplicate requests and hitting rate limits.
* **Consistent experience:** Cached content ensures pages load smoothly without waiting on a live API call.
### How long should you cache?
* The ideal cache duration depends on how frequently you update product media or information.
* If product media rarely changes, you can cache for **12–24 hours** or longer.
* If updates are frequent, use a shorter TTL (e.g., **1–2 hours**) to keep galleries fresh.
**Tip:** Choose a cache duration that matches your update frequency. This balances performance with content accuracy.