# Submit a PDP by GTIN

`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](/api/product-details/getPdpByGtin) 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](/api/product-details/upsertPdpByAsin).

## Request Body

### application/json

- **object** — Provide the category exactly one of two ways: `product_category_id` (a
Vizit category UUID) or `external_category_id` (your own category
identifier). Supplying both, or neither, is rejected.

  - `hero_image_url` (string, required) — Publicly accessible URL to the hero image (HTTP/HTTPS, jpeg/png/webp, ≤6 MB)
  - `carousel_image_urls` (array<string>) — 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.

    - items:
      - **string**
  - `product_category_id` (string) — Category UUID the PDP belongs to. Must be one returned by
[List product categories](/api/product-details/listProductCategories) —
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`.

  - `external_category_id` (any) — 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`.

  - `external_id` (any) — Your own identifier for this PDP. Stored and echoed back on the
corresponding GET so you can correlate records.

  - `integration_id` (any) — Identifier of the integration this PDP belongs to (integration clients only).
  - `hero_image_asset_id` (any) — Partner-side asset identifier for the hero image, echoed back so you
can correlate the scored image with your own asset record.

  - `carousel_image_asset_ids` (array<string>) — 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`.

    - items:
      - **string**
  - `name` (any) — Optional product display name.
  - `retailer` (any) — Retailer region identifier. Must be a value present in the retailer_regions table. Defaults to amazon_us.

## Responses

### 200 — Nothing changed, so the PDP won't be processed. The status is its
current value, scored or error.


**application/json**

- **object**
  - `gtin` (string, required)
  - `pdp_id` (string, required) — Internal identifier for the PDP (useful for support diagnostics)
  - `status` (enum: "processing" | "scored" | "error", required) — The PDP's status after the submission. If the PDP changed and will be
processed, the status is processing and the response is 202. If nothing
changed, the PDP won't be processed and the status is its current value,
scored or error, with a 200 response. Poll GET to follow a processing
PDP to its final status.

  - `score_url` (string, required) — Relative path to poll for scoring results

### 202 — The PDP changed and will be processed. The status is processing.


**application/json**

- **object**
  - `gtin` (string, required)
  - `pdp_id` (string, required) — Internal identifier for the PDP (useful for support diagnostics)
  - `status` (enum: "processing" | "scored" | "error", required) — The PDP's status after the submission. If the PDP changed and will be
processed, the status is processing and the response is 202. If nothing
changed, the PDP won't be processed and the status is its current value,
scored or error, with a 200 response. Poll GET to follow a processing
PDP to its final status.

  - `score_url` (string, required) — Relative path to poll for scoring results

### 400 — Validation or image-download error. Check `error_code` to
distinguish:
  - INVALID_GTIN — GTIN is not 8, 12, 13, or 14 digits
  - INVALID_RETAILER — retailer is not in retailer_regions
  - NO_DEFAULT_PORTFOLIO — org has no default portfolio
  - CATEGORY_NOT_FOUND — product_category_id is missing or outside the org's ICP
  - IMAGE_DOWNLOAD_FAILED — one or more images could not be downloaded; `extra.failed_urls` contains the per-URL reason


**application/json**

- **object** — Standardized error format for all `/v1/*` endpoints. `error_code` is a
stable SCREAMING_SNAKE_CASE identifier clients can switch on.

  - `detail` (string) — Human-readable error message
  - `status_code` (integer) — HTTP status code
  - `error_code` (string) — Stable machine-readable error code
  - `request_id` (any) — Request identifier for correlation
  - `extra` (any) — Endpoint-specific additional context. For example,
IMAGE_DOWNLOAD_FAILED populates extra.failed_urls with per-URL
failure reasons so clients can triage bulk submissions.

  - `timestamp` (string)

### 401 — Missing or invalid Bearer token

### 413 — Too many carousel images (>20)

**application/json**

- **object** — Standardized error format for all `/v1/*` endpoints. `error_code` is a
stable SCREAMING_SNAKE_CASE identifier clients can switch on.

  - `detail` (string) — Human-readable error message
  - `status_code` (integer) — HTTP status code
  - `error_code` (string) — Stable machine-readable error code
  - `request_id` (any) — Request identifier for correlation
  - `extra` (any) — Endpoint-specific additional context. For example,
IMAGE_DOWNLOAD_FAILED populates extra.failed_urls with per-URL
failure reasons so clients can triage bulk submissions.

  - `timestamp` (string)

### 429 — Rate limit exceeded for this organization

### 502 — Image upload to S3 failed

**application/json**

- **object** — Standardized error format for all `/v1/*` endpoints. `error_code` is a
stable SCREAMING_SNAKE_CASE identifier clients can switch on.

  - `detail` (string) — Human-readable error message
  - `status_code` (integer) — HTTP status code
  - `error_code` (string) — Stable machine-readable error code
  - `request_id` (any) — Request identifier for correlation
  - `extra` (any) — Endpoint-specific additional context. For example,
IMAGE_DOWNLOAD_FAILED populates extra.failed_urls with per-URL
failure reasons so clients can triage bulk submissions.

  - `timestamp` (string)