Retrieve PDP scores by id
Fetch the current state and scores for a PDP submitted by id.
/v1/pdps/id/{id}Returns the current scores and processing state for a PDP submitted
via Submit a PDP by id.
Poll until status reaches a terminal COMPLETED or ERROR.
While status is PROCESSING, including during a rescore, the
score fields are null until the new scores land.
score_method tells you whether pdp_score is a FORMULA score,
broken down in score_breakdown, or a LEGACY score. See
How the score is computed for how
to read the breakdown.
Use the optional retailer query parameter to disambiguate the same id
submitted under different retailers. The score_url returned by the PUT
already includes it.
Authorization
bearerAuth Short-lived access token issued by Create a token.
Send it on every request as Authorization: Bearer <token>.
In: header
Path Parameters
Arbitrary caller-supplied PDP identifier — a stable id from your own system (for example a SKU or PIM id). Any non-empty string up to 512 characters; it is not a GTIN and is not format-validated. It must not contain a slash.
1 <= length <= 512Query Parameters
Retailer the id was submitted under. Disambiguates the same id
across retailers. Defaults to amazon_us.
"amazon_us"Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://ext.vizit.com/v1/pdps/id/SKU-12345"{ "id": "SKU-12345", "retailer": "amazon_us", "pdp_id": "9b0a0c4e-3c1d-4b9e-9f08-2c7e3a1f1d77", "status": "COMPLETED", "error_code": null, "name": "Example Omega-3 Fish Oil, 120 Softgels", "category": "Fish Oil Supplements", "pdp_score": 64, "listing_score_at_ingest": 58, "score_change": 6, "vizit_certified": false, "carousel_score": 52.25, "hero": { "image_id": "3f6c2a1e-8b4d-4c7a-9e21-5d0b7f3a9c10", "image_url": "https://cdn.example.com/products/sku-12345/hero.jpg", "hero_score": 72, "vizit_certified": false, "hero_gs1_components": null, "hero_gs1_component_statuses": null, "hero_gs1_group_statuses": null, "agent_ready": null, "mobile_ready": null, "classification": "Hero Image" }, "carousel_images": [ { "image_id": "b1e0c7d2-4a3f-4e8b-9c6d-2f1a0e9b8c71", "image_url": "https://cdn.example.com/products/sku-12345/lifestyle-1.jpg", "position": 1, "vizit_score": 56, "vizit_certified": false, "classification": "Lifestyle" }, { "image_id": "c2f1d8e3-5b4a-4f9c-8d7e-3a2b1f0c9d82", "image_url": "https://cdn.example.com/products/sku-12345/feature-1.jpg", "position": 2, "vizit_score": 55, "vizit_certified": false, "classification": "Feature/Benefit" }, { "image_id": "d3a2e9f4-6c5b-4a0d-9e8f-4b3c2a1d0e93", "image_url": "https://cdn.example.com/products/sku-12345/lifestyle-2.jpg", "position": 3, "vizit_score": 50, "vizit_certified": false, "classification": "Lifestyle" }, { "image_id": "e4b3f0a5-7d6c-4b1e-8f9a-5c4d3b2e1fa4", "image_url": "https://cdn.example.com/products/sku-12345/size-1.jpg", "position": 4, "vizit_score": 48, "vizit_certified": false, "classification": "Size and Scale" } ], "asset_mix": { "total_images": 5, "by_classification": { "Hero Image": 1, "Lifestyle": 2, "Feature/Benefit": 1, "Size and Scale": 1 }, "ideal_by_classification": { "Lifestyle": 2, "Feature/Benefit": 2, "Multi-Pack": 1, "Size and Scale": 1 } }, "images_matching_ideal_mix": 4, "is_ideal_content_mix": false, "score_penalty": true, "image_count_penalty": true, "image_mix_penalty": false, "image_order_penalty": false, "high_scoring_asset_count": 0, "scored_at": "2026-09-25T14:05:32Z", "score_method": "LEGACY", "scoring_version": null, "formula_version": null, "score_breakdown": null, "unavailable_reason": null, "withheld_reason": null}{ "detail": "string", "status_code": 0, "error_code": "IMAGE_DOWNLOAD_FAILED", "request_id": "266ea41d-adf5-480b-af50-15b940c2b846", "extra": { "failed_urls": [ { "url": "https://cdn.example.com/broken.jpg", "reason": "IMAGE_DOWNLOAD_TIMEOUT" }, { "url": "https://cdn.example.com/icon.svg", "reason": "UNSUPPORTED_IMAGE_FORMAT" } ] }, "timestamp": "2019-08-24T14:15:22Z"}{ "detail": "string", "status_code": 0, "error_code": "IMAGE_DOWNLOAD_FAILED", "request_id": "266ea41d-adf5-480b-af50-15b940c2b846", "extra": { "failed_urls": [ { "url": "https://cdn.example.com/broken.jpg", "reason": "IMAGE_DOWNLOAD_TIMEOUT" }, { "url": "https://cdn.example.com/icon.svg", "reason": "UNSUPPORTED_IMAGE_FORMAT" } ] }, "timestamp": "2019-08-24T14:15:22Z"}{ "detail": "string", "status_code": 0, "error_code": "IMAGE_DOWNLOAD_FAILED", "request_id": "266ea41d-adf5-480b-af50-15b940c2b846", "extra": { "failed_urls": [ { "url": "https://cdn.example.com/broken.jpg", "reason": "IMAGE_DOWNLOAD_TIMEOUT" }, { "url": "https://cdn.example.com/icon.svg", "reason": "UNSUPPORTED_IMAGE_FORMAT" } ] }, "timestamp": "2019-08-24T14:15:22Z"}GETList product retailers
Lists the retailer regions you can use to scope product category discovery. Pass a returned retailer's `id` (e.g. `amazon_us`, `walmart_us`) as the `retailer` query parameter on [list product categories](/api/product-details/listProductCategories).
PUTSubmit a PDP by id
Submitting a PDP by id sends its hero and carousel images for scoring. If the submission changes the PDP, it will be processed and the response is 202 with status PROCESSING. Use [Retrieve a PDP by id](/api/product-details/getPdpById) to watch the scores come in. If nothing has changed, the PDP won't be processed and the response is 200 with status COMPLETED or ERROR. The `id` in the path is your own stable identifier and is echoed back on the corresponding GET so you can correlate records. Optionally supply `gtin` or `asin` in the body to help Vizit resolve the product category; they are used only for category resolution and are never echoed back. Subsequent submissions are reconciled by filename: a filename already on the PDP is reused (no re-download, no re-score), while a new filename replaces the previous image in that slot. An identical payload is a no-op. Use this endpoint when you can supply your own image URLs (for example, from a PIM). To have Vizit scrape an Amazon listing instead, use [Submit a PDP by ASIN](/api/product-details/upsertPdpByAsin).