Images

Overview

The image API lets you:

• list every image of a specific product;
• walk the global image inventory of the catalog;
• tell enabled and disabled images apart;
• identify the image, small_image and thumbnail roles;
• work deterministically with store_id;
• run an initial load and a full reconciliation using cursor pagination;
• keep using the existing endpoints to create, update and delete images;
• remove every image of a product in a single call;
• remove specific images from several products in a single call.

Method map

OAuth2 permissions

Reading and writing images use different permissions. When configuring the OAuth2 client in the admin panel, grant only what the integration needs.

Look up a product's images New

Read-only operation: returns every image in a product's gallery, including disabled ones, with the roles and label in the context of the requested store.

GET /api2/products/imagem?type=sku&product_id=27.9353&store_id=1&limit=100
Authorization: Bearer {access_token}

Parameters

Response example

{
  "success": true,
  "product_id": 115973,
  "sku": "27.9353",
  "store_id": 1,
  "images": [
    {
      "image_id": "690992",
      "file": "/e/s/escova-robinson-taca-soft.jpg_1.jpg",
      "label": "Imagem 1",
      "position": 1,
      "types": [
        "image",
        "small_image",
        "thumbnail"
      ],
      "disabled": false,
      "url": "https://www.exemplo.com.br/media/catalog/product/e/s/escova-robinson-taca-soft.jpg_1.jpg"
    }
  ],
  "has_next": false,
  "next_cursor": null
}

Image fields

Image roles (types)

types lists the roles the image plays on the product. Possible values are image (base image), small_image and thumbnail.

"types": [
  "image",
  "small_image",
  "thumbnail"
]

An image can belong to the gallery without playing any of these roles:

"types": []

Disabled images

Read operations include disabled images. This is intentional: the integration can use disabled to correctly reconcile existing images that must not be shown as active.

{
  "image_id": "653867",
  "file": "/p/o/ponta-diamantada_58.jpg",
  "label": "Imagem 1",
  "position": 1,
  "types": [],
  "disabled": true,
  "url": "https://www.exemplo.com.br/media/catalog/product/p/o/ponta-diamantada_58.jpg"
}

Store and fallback

store_id=0 is the administrative/global scope. For storefront integrations, send the ID of the store used by the project explicitly — for example store_id=1. Multi-store environments may have store_id=1, store_id=2, store_id=3 and so on.

• Gallery fields (label, position, disabled) use the requested store context and may inherit values from the global scope when there is no store-specific override.
• The roles in types also follow the configuration of the requested context.
• store_id=1 is only a common example — it is not a universal value on the Yep Platform.

Existing product with no images

An existing product with no images returns HTTP 200 with an empty list:

{
  "success": true,
  "product_id": 116022,
  "sku": "25.5979",
  "store_id": 0,
  "images": [],
  "has_next": false,
  "next_cursor": null
}

Global image inventory New

Returns the catalog's image inventory, paginated by cursor. Intended for initial load and full reconciliation.

GET /api2/products/imagens?store_id=1&limit=100
Authorization: Bearer {access_token}

Parameters

Response example

{
  "success": true,
  "store_id": 1,
  "images": [
    {
      "image_id": "160031",
      "product_id": 98622,
      "sku": "25.0886",
      "file": "/b/r/broca-carbide-fg-36.jpg_10.jpg",
      "label": "Imagem 1",
      "position": 1,
      "types": [],
      "disabled": false,
      "url": "https://www.exemplo.com.br/media/catalog/product/b/r/broca-carbide-fg-36.jpg_10.jpg"
    }
  ],
  "has_next": true,
  "next_cursor": "160115"
}

Inventory semantics

The plural endpoint is an inventory of images, not of products. Therefore:

• a product with several images appears several times — each record is one image;
• products with no images do not appear in the inventory;
• disabled images appear with disabled=true;
• product status and visibility are not used as gallery filters.

Cursor pagination

Every listing that can exceed one page returns has_next and next_cursor. The integration advances by passing the received cursor back, without computing anything.

Recommended flow

1. start without cursor;
2. process images;
3. if has_next=true, call again with cursor equal to next_cursor;
4. repeat;
5. stop when has_next=false and next_cursor=null.

Avoid

• Incrementing the cursor manually.
• Reusing an arbitrary cursor as if it were a page number.
• Sending page or offset.

Integration recommendations

HTTP responses of the lookups

Inputs that return 400

• limit=0, limit=201 or limit=abc
• page=2 or offset=10
• invalid cursor
• invalid store_id

Write operations

Creating, updating and deleting a single image remain available on the singular route, distinguished by HTTP method. They require the products/images permission. The GETs do not replace these operations. To remove several images at once, see full deletion and selective bulk deletion.

{
  "type": "sku",
  "product_id": "novo_produto",
  "position": 1,
  "label": "Image",
  "file_name": "my_image.png",
  "file_mime_type": "image/png",
  "file_content": "iVBORw0KGgoAAAANS...",
  "types": ["image"]
}

{
  "type": "sku",
  "product_id": "produtoteste",
  "image_id": "70449",
  "position": 999,
  "label": "Updated image",
  "types": ["image"]
}

{
  "type": "sku",
  "product_id": "produtoteste",
  "image_id": "70449"
}

Delete every image of a product New

Removes the entire global gallery of a single product in one request.

DELETE /api2/products/imagens
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "type": "sku",
  "product_id": "PRODUTO-001",
  "delete_all": true
}

{
  "type": "id",
  "product_id": 12345,
  "delete_all": true
}

Parameters

• store_id is not accepted: the cleanup is global for the product's gallery.
• delete_all and items are mutually exclusive modes in the same request.

Response example

{
  "success": true,
  "product_id": 12345,
  "sku": "PRODUTO-001",
  "deleted_count": 3
}

A product that already has no images responds 200 with deleted_count: 0:

{
  "success": true,
  "product_id": 12345,
  "sku": "PRODUTO-001",
  "deleted_count": 0
}

Delete specific images in bulk New

Removes specific images from one or several products in a single call. SKU and ID identification can be mixed in the same batch.

{
  "items": [
    {
      "type": "sku",
      "product_id": "PRODUTO-001",
      "image_ids": ["10001", "10002"]
    },
    {
      "type": "id",
      "product_id": 12346,
      "image_ids": ["10003"]
    }
  ]
}

Payload rules

• items must be a non-empty array.
• Each item requires type, product_id and image_ids.
• type accepts only sku or id.
• image_ids must be a non-empty array.
• Each existing image_id must belong to the product given in the same item.

• The same product cannot appear twice, even if one entry uses SKU and the other uses ID.
• The same image_id cannot be repeated in the batch.
• store_id is not accepted: the deletion is global.
• items and delete_all cannot be sent together.

Response example

{
  "success": true,
  "products_processed": 2,
  "requested_count": 3,
  "deleted_count": 2,
  "already_absent_count": 1,
  "results": [
    {
      "product_id": 12345,
      "sku": "PRODUTO-001",
      "requested_count": 2,
      "deleted_count": 2,
      "already_absent_count": 0
    },
    {
      "product_id": 12346,
      "sku": "PRODUTO-002",
      "requested_count": 1,
      "deleted_count": 0,
      "already_absent_count": 1
    }
  ]
}

Response fields

Bulk delete guarantees

Validation before deleting

The batch is validated before any deletion is applied. Missing products, wrong ownership, duplicates or an invalid payload never cause a partial deletion of the other items: the whole request is rejected and no image is removed.

Duplicate images and roles

Two gallery associations can point to the same file. If only one image_id is removed and another association of the same product still uses the same file, the image, small_image and thumbnail roles remain valid.

Roles are cleared only when the last association of that file no longer exists on the product.

Operational recommendations

For gallery reconciliation:

1. query the images or the inventory;
2. group the deletions by product;
3. build batches of up to 50 products and 500 image_ids;
4. send one batch;
5. wait for the response;
6. only then send the next one.

HTTP responses of write operations