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.

During a refresh, previously computed scores remain visible alongside status: PROCESSING and the prior scored_at timestamp, so clients can keep showing the last known result while a new one is computed.

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": "2ed2d86b-85b6-49b8-bfaf-11ce19f11301",  "status": "PROCESSING",  "error_code": "string",  "name": "string",  "category": "string",  "pdp_score": 0,  "listing_score_at_ingest": 0,  "score_change": 0,  "vizit_certified": true,  "carousel_score": 0,  "hero": {    "image_id": "84c230fd-5520-4984-8119-37365b66fd80",    "image_url": "string",    "hero_score": 0.1,    "vizit_certified": true,    "hero_gs1_components": {      "four_ws.brand": 92,      "four_ws.product_type": 88,      "four_ws.variant": 74,      "four_ws.size_and_count": 75,      "image_quality.background_separation": 95,      "image_quality.product_centered": 90,      "image_quality.product_prominent": 93,      "image_quality.product_cropping": 97,      "image_quality.product_tilt": 98,      "image_quality.no_off_pack_text": 100,      "composition": 84,      "layout_staging": 81    },    "hero_gs1_component_statuses": {      "four_ws.brand": "PASS",      "four_ws.product_type": "REVIEW",      "four_ws.variant": "REVIEW",      "four_ws.size_and_count": "REVIEW",      "image_quality.background_separation": "REVIEW",      "image_quality.product_centered": "REVIEW",      "image_quality.product_prominent": "REVIEW",      "image_quality.product_cropping": "REVIEW",      "image_quality.product_tilt": "REVIEW",      "image_quality.no_off_pack_text": "PASS",      "composition": "HIGH",      "layout_staging": "HIGH"    },    "hero_gs1_group_statuses": {      "shopper_clarity": "REVIEW",      "image_quality": "REVIEW",      "composition": "HIGH",      "product_staging": "HIGH"    },    "agent_ready": true,    "mobile_ready": true,    "classification": "Lifestyle"  },  "carousel_images": [    {      "image_id": "84c230fd-5520-4984-8119-37365b66fd80",      "image_url": "string",      "position": 1,      "vizit_score": 0,      "vizit_certified": true,      "classification": "Lifestyle"    }  ],  "asset_mix": {    "total_images": 0,    "by_classification": {      "Packshot": 1,      "Lifestyle": 2,      "Feature highlight": 1    },    "ideal_by_classification": {      "Lifestyle": 2,      "Feature highlight": 1,      "Multi-Pack": 1    }  },  "images_matching_ideal_mix": 0,  "is_ideal_content_mix": true,  "score_penalty": true,  "image_count_penalty": true,  "image_mix_penalty": true,  "image_order_penalty": true,  "high_scoring_asset_count": 0,  "scored_at": "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"}
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. The previous scores remain visible alongside `status: PROCESSING` 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.