Products
Create, update, query, link, attach images and delete products — with deterministic pagination, explicit store_id selection, configurable limit and opt-in pagination metadata.
Overview
The /api2/products endpoint is an integration/administrative route. It is not limited to active storefront products — it exposes the catalog for syncing with ERPs, PIMs, marketplaces and internal routines. The route supports both paginated listing and single record lookup by id or sku.
limit is set.limit is missing or invalid.total, last_page, has_next under include_pagination=1.Create a configurable product.
{
"attribute_set_id": 4,
"type_id": "configurable",
"visibility": 4,
"store_id": 1,
"sku": "novo_configuravel",
"name": "novo configuravel",
"description": "Configurable product description",
"short_description": "Short description",
"price": 99.90,
"status": 1,
"tax_class_id": 2,
"categories": [54, 59, 128],
"website_id": [1],
"additional_attributes": {
"single_data": [
{"key": "color", "value": "AZUL"},
{"key": "ncm", "value": "5543"}
]
},
"configurable_attributes": [335]
}Create a simple product.
{
"type_id": "simple",
"attribute_set_id": 4,
"sku": "produto_teste",
"store_id": 1,
"name": "Test product",
"price": "2000",
"special_price": "150",
"weight": "0.5",
"status": 1,
"visibility": 4,
"categories": [54, 59, 128],
"website_id": [1],
"stock_data": {"qty": "99", "is_in_stock": 1}
}Update a product.
{
"type": "sku",
"id": "novo_produto",
"name": "New product name"
}invalid_fields, invalid_attributes and invalid_attribute_values.Fetch a product (single) or list with deterministic pagination.
?page=1&type=sku&id=novo_produtoLink simple products to a configurable.
{
"type": "sku",
"configurable_id": "novo_produto",
"simples": "novo_configuravel"
}Delete a product.
{
"type": "sku",
"id": "novo_produto"
}What's new in GET /api2/products
Three main improvements have been rolled out to the listing endpoint, making it more predictable in multi-store environments and more efficient for batch syncs.
5) Optional store_id support New
You can now pass store_id to make the result explicit and deterministic in multi-store scenarios. Without it, store selection follows the environment default; with it, your integration owns the decision.
Example
GET /api2/products?page=1&store_id=16) Optional pagination metadata New
Opt-in pagination fields have been added to the response body. They are only returned when include_pagination=1 is sent, avoiding overhead for syncs that don't need this metadata.
1 enables it). When active, includes total, last_page and has_next in the response.include_pagination=1).limit.Example
GET /api2/products?page=1&include_pagination=17) Optional limit support New
The endpoint now accepts limit to set the number of products per page. Invalid values (non-numeric, arrays, negative, zero or above the cap) are normalized to the default, ensuring no request breaks due to unexpected input.
| Rule | Value | Behavior |
|---|---|---|
| Default | 20 | Applied when limit is omitted. |
| Maximum | 200 | Hard ceiling to protect the route under heavy load. |
| Invalid | — | Invalid values are normalized to 20. |
Examples
GET /api2/products?page=1&limit=50
GET /api2/products?page=1&limit=200Supported usage patterns
Quick reference of the tested and certified combinations for GET /api2/products.
GET /api2/products
GET /api2/products?page=2
GET /api2/products?page=1&limit=100
GET /api2/products?id=24404
GET /api2/products?id=ABC-123&type=sku
GET /api2/products?page=1&store_id=1
GET /api2/products?page=1&limit=100&include_pagination=1
Integration recommendations
Consolidated best practices after the endpoint evolution. Following them reduces rework, prevents infinite pagination and guarantees determinism in multi-store setups.
Recommended
- Always send
pageexplicitly in pagination routines. - Use
store_idwhenever the integration needs deterministic results in a multi-store environment. - Prefer
limit=50orlimit=100for regular syncs. - Use
limit=200only when you actually need to reduce the number of calls. - Use
include_pagination=1to control pagination progress safely (loop based onhas_next).
Avoid
- Sending parameters as arrays in scalar fields — for example
id[]orlimit[]. - Assuming the endpoint returns only active storefront products. This is an integration/administrative route.
- Relying on implicit ordering across pages in multi-store scenarios without
store_id.
Sync tip
For periodic syncs, combine store_id + limit=100 + include_pagination=1. You get determinism, balanced throughput and a reliable stop condition (has_next=false).
Product images
Upload a base64-encoded image.
{
"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"]
}Update image metadata.
{
"type": "sku",
"product_id": "produtoteste",
"image_id": "70449",
"position": 999,
"label": "Updated image",
"types": ["image"]
}Delete a product image.
{
"type": "sku",
"product_id": "produtoteste",
"image_id": "70449"
}