Vizit Public APIAPI
Product Details

Submit a PDP by id

Create or update a PDP with caller-supplied image URLs and trigger scoring.

PUT/v1/pdps/id/{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 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.

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

id*string

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.

Length1 <= length <= 512

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

gtin?|

GTIN-8, GTIN-12 (UPC-A), GTIN-13 (EAN-13), or GTIN-14. Used only for category resolution; it is never echoed back. Leniently handled — a value that isn't 8/12/13/14 digits is ignored (treated as null), not rejected.

asin?|

Amazon ASIN — 10 uppercase alphanumeric characters. Used only for category resolution; it is never echoed back. Leniently handled — a value that isn't a valid ASIN is ignored (treated as null), not rejected.

hero_image_url*string

Publicly accessible URL to the hero image (HTTP/HTTPS, jpeg/png/webp, ≤25 MB)

Formaturi
Lengthlength <= 2048
carousel_image_urls?array<>

Ordered list of carousel image URLs. Order is preserved as carousel position. Upsert is name-based: same filename as an existing image on this PDP → reuse; different filename → replace.

Itemsitems <= 20
product_category_id?|

Category UUID the PDP belongs to. Must be one returned by List product categories — if it doesn't exist or the organization lacks ICP access, the request is rejected with CATEGORY_NOT_FOUND. Mutually exclusive with external_category_id.

Formatuuid
external_category_id?|

Your own category identifier, resolved to a Vizit category on your organization's behalf. Use instead of product_category_id when you track categories under your own IDs. Mutually exclusive with product_category_id.

Lengthlength <= 1024
integration_id?|

Identifier of the integration this PDP belongs to (integration clients only).

Formatuuid
hero_image_asset_id?|

Partner-side asset identifier for the hero image, echoed back so you can correlate the scored image with your own asset record.

Lengthlength <= 255
carousel_image_asset_ids?array<>

Partner-side asset identifiers for the carousel images, positionally aligned with carousel_image_urls. Must be empty or the same length as carousel_image_urls.

Itemsitems <= 20
name?|

Optional product display name.

retailer?|

Retailer region identifier. Must be a value present in the retailer_regions table. Defaults to amazon_us.

Default"amazon_us"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://ext.vizit.com/v1/pdps/id/SKU-12345" \  -H "Content-Type: application/json" \  -d '{    "hero_image_url": "https://cdn.example.com/products/abc/hero.jpg"  }'
{  "id": "SKU-12345",  "pdp_id": "2ed2d86b-85b6-49b8-bfaf-11ce19f11301",  "status": "PROCESSING",  "error_code": "string",  "score_url": "/v1/pdps/id/SKU-12345?retailer=amazon_us"}
{  "id": "SKU-12345",  "pdp_id": "2ed2d86b-85b6-49b8-bfaf-11ce19f11301",  "status": "PROCESSING",  "error_code": "string",  "score_url": "/v1/pdps/id/SKU-12345?retailer=amazon_us"}
{  "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"}
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"}

GETRetrieve PDP scores by id

Returns the current scores and processing state for a PDP submitted via [Submit a PDP by id](/api/product-details/upsertPdpById). Poll until `status` reaches a terminal `COMPLETED` or `ERROR`. During a rescore the previous 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 `retailer` query parameter to disambiguate the same id submitted under different retailers. The `score_url` returned by the PUT already includes it.

GETRetrieve PDP scores by ASIN

Returns the current scores and processing state for a PDP submitted via [Submit a PDP by ASIN](/api/product-details/upsertPdpByAsin). 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.