Vizit Public APIAPI
Product Details

Retrieve PDP scores by ASIN

Fetch the current state and scores for an ASIN-ingested PDP.

GET/v1/pdps/asin/{asin}

Returns the current scores and processing state for a PDP submitted via Submit a PDP by ASIN. Poll until status reaches a terminal COMPLETED or ERROR.

While status is PROCESSING, including during a refresh, 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 region query parameter to disambiguate between regional storefronts when the same ASIN has been ingested under multiple regions in your organization. The score_url returned by the PUT response already includes this parameter.

Authorization

bearerAuth
Authorization<token>

Short-lived access token issued by Create a token. Send it on every request as Authorization: Bearer <token>.

In: header

Path Parameters

asin*string

Amazon Standard Identification Number — 10 characters, uppercase letters and digits only. Validated at the router; a mismatch returns 400 INVALID_ASIN before any retailer call is made.

Match^[A-Z0-9]{10}$

Query Parameters

region?string

Amazon storefront region (e.g., us, uk, de, ca). Defaults to us.

Default"us"

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://ext.vizit.com/v1/pdps/asin/B07XVTRJKX"

{  "asin": "B07XVTRJKX",  "region": "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://m.media-amazon.com/images/I/example-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://m.media-amazon.com/images/I/example-lifestyle-1.jpg",      "position": 1,      "vizit_score": 56,      "vizit_certified": false,      "classification": "Lifestyle"    },    {      "image_id": "c2f1d8e3-5b4a-4f9c-8d7e-3a2b1f0c9d82",      "image_url": "https://m.media-amazon.com/images/I/example-feature-1.jpg",      "position": 2,      "vizit_score": 55,      "vizit_certified": false,      "classification": "Feature/Benefit"    },    {      "image_id": "d3a2e9f4-6c5b-4a0d-9e8f-4b3c2a1d0e93",      "image_url": "https://m.media-amazon.com/images/I/example-lifestyle-2.jpg",      "position": 3,      "vizit_score": 50,      "vizit_certified": false,      "classification": "Lifestyle"    },    {      "image_id": "e4b3f0a5-7d6c-4b1e-8f9a-5c4d3b2e1fa4",      "image_url": "https://m.media-amazon.com/images/I/example-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"}
Empty
{  "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"}

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).

PUTSubmit a PDP by Amazon ASIN

Submitting an ASIN runs Vizit's standard Amazon scrape-and-score pipeline server-side: ASIN lookup and validation, category inference with ICP check, retailer scrape, image ingest, and scoring. Unlike [Submit a PDP by id](/api/product-details/upsertPdpById), the caller does not supply images or a category — both are derived from the scrape. **Upsert semantics.** If a PDP already exists for this ASIN in your organization (and region), this call refreshes it — same behavior as the in-product "refresh" action. While it is `PROCESSING`, the score fields are `null` until the new scores land. The response returns immediately with a `score_url`, normally with `status: PROCESSING`. Use [Retrieve PDP scores by ASIN](/api/product-details/getPdpByAsin) (with the same `region`) to watch the scores come in. Score availability is bounded by the scrape and scoring pipeline — expect tens of seconds for typical Amazon ASINs. **Common errors.** `INVALID_ASIN` if the path parameter is not 10 uppercase alphanumeric characters; `ASIN_NOT_FOUND_AT_RETAILER` if Amazon does not return the listing; `CATEGORY_NOT_IN_ORG_ICP` if the scraped category is outside your organization's ICP; `NO_VALID_CATEGORY` if the retailer returned no usable category data.