Remove Duplicate Product Images

POST 
/api/products/duplicate-images/remove

Remove duplicate images from a set of products in the background. Returns the id of the background job; poll it under Jobs to follow progress. For each product with two or more images, images not yet compared are read first, then each group of images showing the same picture keeps one image: the product's primary when it is in the group, otherwise the largest original. Images tagged as a variant swatch are never removed. Each product is changed on its own, so a cancelled job keeps what it finished.

Required scope: products:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Every removed image is backed up; when the job completes, its results carry an undo entry for Restore Duplicate Product Images.

Authentication: Requires Bearer token.

Body fields:

• ids (array of integers, required unless apply_to_all): the products to include
• apply_to_all (boolean, optional): true to include every product matching filters instead of ids
• filters (object, optional): the same filters List Products accepts, without the filter[...] wrapper (e.g. {"has_duplicate_images.is": true})

Requires permission: products.update

Request

Responses

200

OK

Response Headers

Content-Type

401

Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.

403

Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.

422

Validation failed — the body is a field → messages map (Laravel shape) or the platform envelope with a stable machine-readable code. Fix the payload and resubmit.

429

Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.