Vizit Public APIAPI
Product Details

Submit a PDP by GTIN

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

PUT/v1/pdps/gtin/{gtin}

Submitting a PDP by GTIN 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 GTIN to watch the scores come in. If nothing has changed, the PDP won't be processed and the response is 200 with status scored or error.

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

gtin*string

GTIN-8, GTIN-12 (UPC-A), GTIN-13 (EAN-13), or GTIN-14

Match^\d{8}$|^\d{12}$|^\d{13}$|^\d{14}$

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

hero_image_url?string

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

Formaturi
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*string
Length1 <= length
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
external_id?|

Your own identifier for this PDP. Stored and echoed back on the corresponding GET so you can correlate records.

Lengthlength <= 512
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"
hero_image_url?string

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

Formaturi
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?string

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*string
Length1 <= length
external_id?|

Your own identifier for this PDP. Stored and echoed back on the corresponding GET so you can correlate records.

Lengthlength <= 512
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

curl -X PUT "https://ext.vizit.com/v1/pdps/gtin/00012345678905" \  -H "Content-Type: application/json" \  -d '{    "hero_image_url": "https://cdn.example.com/products/abc/hero.jpg",    "product_category_id": "string"  }'
{  "gtin": "string",  "pdp_id": "2ed2d86b-85b6-49b8-bfaf-11ce19f11301",  "status": "processing",  "score_url": "/v1/pdps/gtin/00012345678905"}
{  "gtin": "string",  "pdp_id": "2ed2d86b-85b6-49b8-bfaf-11ce19f11301",  "status": "processing",  "score_url": "/v1/pdps/gtin/00012345678905"}
{  "detail": "string",  "status_code": 0,  "error_code": "INVALID_GTIN",  "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": "INVALID_GTIN",  "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": "INVALID_GTIN",  "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 GTIN

Returns the current scores and processing state for a PDP submitted via [Submit a PDP by GTIN](/api/product-details/upsertPdpByGtin). Poll until `status` moves from `processing` to `scored`. 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.

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` moves from `processing` to `scored`. 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.