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.url_key changes. To do so, send the optional parameter create_url_redirect: true. See Permanent redirect (301) when updating URLs for examples and usage rules.Add or remove specific categories of a product without replacing the others.
{
"id": "SKU-123",
"type": "sku",
"add_category_ids": [60],
"remove_category_ids": [55]
}
Fetch a product (single) or list with deterministic pagination.
?page=1&type=sku&id=novo_produto
Link simple products to a configurable.
{
"type": "sku",
"configurable_id": "novo_produto",
"simples": "novo_configuravel"
}
Delete a product.
{
"type": "sku",
"id": "novo_produto"
}
Permanent redirect (301) when updating URLs New
The Yep Platform REST API can create permanent redirects (HTTP 301) when the URL key (url_key) of an existing product changes.
This lets ERP, PIM and other integrations update product URLs while keeping previous addresses reachable, when eligible, reducing broken links and 404 errors.
The feature uses the native URL history mechanism of the Yep Platform and works even when automatic redirect creation is disabled in the global catalog settings.
Update the url_key while preserving the previous URL.
PATCH /api2/products/
Authorization: Bearer {access_token}
Content-Type: application/json
{
"id": "SKU-123",
"type": "sku",
"store_id": 1,
"url_key": "produto-nova-url",
"create_url_redirect": true
}
Parameters
id (default) or sku.true or false). When true, requests that the URL history be kept when the URL effectively changes.Response example — HTTP 200
{
"success": true,
"partial_success": false,
"message": "Produto atualizado com sucesso."
}
Redirect behavior
Take a product with the original address https://loja.exemplo.com/produto-antigo. After an update with create_url_redirect: true, its new URL may become https://loja.exemplo.com/produto-nova-url.
If the history can be created by the native mechanism, the previous address responds with HTTP 301 pointing to the new URL.
Successive changes are supported too. Historical addresses can be updated to point straight to the latest URL, avoiding unnecessary redirect chains.
Rules
true: requests the permanent history when the URL effectively changes.falseor missing parameter: keeps the previous API behavior, without explicitly requesting a redirect.- Unchanged URL: no URL history is created.
- Multi-store: rewrite generation follows the native mechanism, including attribute inheritance and URL settings of the linked stores.
- Invalid type: values such as
"true","false",1,0ornullare rejected with HTTP 400. Use only the JSON booleanstrueandfalse. - Product creation: the parameter applies only to the PATCH of existing products. It is ignored on the create POST.
{
"error": "create_url_redirect deve ser um booleano JSON."
}
HTTP 200 does not certify the 301 record
Creating the history depends on previously recorded URLs and on the native conflict-resolution rules. An HTTP 200 response confirms that the update and the requested processing finished without exceptions, but it does not certify individually that a 301 record exists.
Relevant HTTP responses
| Code | Situation |
|---|---|
200 | Product updated successfully. |
400 | Invalid create_url_redirect, invalid JSON or missing id. |
404 | Product not found. |
409 | Data conflict, such as a URL already used by another product. |
500 | Internal failure during the operation. |
503 | Unavailability or processing lock related to the URL update. |
Failure after saving
If a failure happens after saving, the product may already have its URL updated without the redirect being confirmed. In that case the 500 or 503 response carries the message "O produto pode já ter sido salvo, mas o redirecionamento 301 não foi confirmado." Before retrying, check the current URL and the existing history.
Integration recommendations
- For bulk updates, send one PATCH request per product, using
create_url_redirect: trueonly when you want to keep the previous URL. - Avoid concurrent URL updates for the same product and handle
500and503errors before retrying. - The feature keeps old URLs during new changes, but it does not rebuild missing history from changes made earlier.
Incremental product category links New
The Yep Platform REST API can add or remove specific categories of a product without replacing or changing its other existing associations.
This is especially suited to ERP, PIM and external integrations that sync product categories, preserving storefront, campaign and menu categories managed directly in the Yep Platform.
Traditional versus incremental update
PATCH /api2/products/When a valid category list is sent in categories or category_ids, the API uses that list to replace the product associations. Categories missing from the list may be removed.PATCH /api2/products/categoriesThe API changes only the links given in add_category_ids and remove_category_ids. All other categories stay linked to the product, regardless of their position in the tree or how they were registered.Authentication and permissions
The operation requires Bearer Token authentication and the product write permission (products/write) in the integration ACL.
Add and/or remove links between a product and categories.
PATCH /api2/products/categories
Authorization: Bearer {access_token}
Content-Type: application/json
Accepted parameters
type.id (default) or sku.- At least one of the lists must contain an ID. You can send only additions, only removals, or both in the same request.
- Category IDs must be positive integers or integer numeric strings. The given categories must exist in the catalog.
store_idis not accepted, because direct product–category links are global.- Fields other than the four above are rejected with HTTP 400.
Example 1 — Add and remove at the same time
{
"id": "SKU-123",
"type": "sku",
"add_category_ids": [60],
"remove_category_ids": [55]
}
The API adds category 60 and removes category 55, keeping every other association.
Success response — HTTP 200
{
"success": true,
"changed": true,
"product_id": 12345,
"added_category_ids": [60],
"removed_category_ids": [55]
}
Example 2 — Add only
{
"id": "SKU-123",
"type": "sku",
"add_category_ids": [60, 61]
}
The API adds the given categories when they are not linked yet. No existing category is removed.
Example 3 — Remove only
{
"id": "SKU-123",
"type": "sku",
"remove_category_ids": [55, 56]
}
Only the given categories are unlinked. All other associations stay intact.
Idempotency and avoiding needless changes
- Adding a category that is already linked does not create a duplicate.
- Removing a category that is not linked does not cause an error.
- Repeated IDs are normalized before processing.
- When no association needs to change, the product is not saved again.
added_category_ids and removed_category_ids list only the links that actually changed. Response without changes — HTTP 200:
{
"success": true,
"changed": false,
"product_id": 12345,
"added_category_ids": [],
"removed_category_ids": []
}
Whole-request validation
Unlike the generic product update, this operation does not accept partial validation success. Before changing the product, the API checks the received fields, the IDs and that the categories exist. The request is rejected as a whole when there are invalid or conflicting values.
{
"id": "SKU-123",
"type": "sku",
"add_category_ids": [60],
"remove_category_ids": [60]
}
Response — HTTP 400
{
"error": "Uma categoria não pode ser adicionada e removida na mesma requisição."
}
In this case no association is changed.
HTTP responses
| Code | Meaning |
|---|---|
200 | Operation completed, with or without an effective change. |
400 | Invalid payload, missing category, conflicting IDs or fields not accepted. |
401 | Missing, invalid or expired authentication. |
403 | Integration lacks permission for the operation. |
404 | Product not found. |
405 | HTTP method other than PATCH. |
500 | Internal failure or failure after a persistence attempt. |
503 | Operation temporarily blocked by concurrency or unavailability. |
Failure after saving
If a failure happens after saving, the associations may already be persisted even with an error response. Check the current product state before retrying.
Indexing, cache and storefront display
The operation uses the native product save of the Yep Platform, keeping the existing indexing and catalog update mechanisms. When there is an effective change, the product associations are processed and the native indexing mechanisms run, following the modes configured in the environment.
The API also requests targeted cache invalidation for the affected categories and their relevant ancestors. In environments with manual or locked indexers, the storefront may only show the changes after those indexes are processed.
Categories and stores
- Links are applied directly to the product and are not specific to a store view.
- Adding a subcategory does not automatically add its ancestors as direct links. Anchor categories may show products through the normal indexing rules.
- For configurable products, a link on the parent product is not propagated automatically to the related simple products.
- Actual storefront display also depends on website, category tree, status, visibility and storefront settings.
Integration recommendations
- For bulk syncs, send one request per product with only the category IDs that need to be added or removed.
- Avoid concurrent category updates of the same product by different systems.
- To check the categories linked to a product, use
GET /api2/productswith its ID or SKU. The response contains thecategoriesandproduct_categoriesfields.
Protection limited to this endpoint
The endpoint keeps the associations it does not mention, but a traditional update that replaces the full category list, made in the Admin or by another integration, can still overwrite existing links. The concurrency protection coordinates calls to the incremental endpoint itself; it does not block other product maintenance processes.
Links, not the tree
This endpoint changes links between products and categories. It does not create, delete, rename or move categories in the tree. For those operations, see Categories.
Single product lookup Updated
GET /api2/products still serves the listing when used without a single-record identifier. To fetch one product, send id and type. In this usage the response now includes human-readable references (attribute set, categories, websites, status and visibility), plus a pricing summary and an inventory summary.
GET /api2/products?id=3291&type=sku
GET /api2/products?id=2074&type=id
GET /api2/products?id=3291&type=sku&store_id=1
Parameters
type. Required only for the single lookup.id is interpreted: id or sku. Required only for the single lookup.Response example — simple product
{
"success": true,
"product": {
"product_id": "2074",
"sku": "3291",
"name": "União Ristretto Coffee Capsules 10 units",
"set": "4",
"product_set": {
"id": "4",
"name": "Default"
},
"type": "simple",
"categories": ["122", "124"],
"product_categories": [
{"id": "122", "name": "Compatible Capsules"},
{"id": "124", "name": "Coffee"}
],
"websites": ["1"],
"product_websites": [
{"id": "1", "code": "cafe", "name": "Main Website"}
],
"status": "1",
"product_status": {
"value": "1",
"code": "enabled",
"label": "Enabled"
},
"visibility": "4",
"product_visibility": {
"value": "4",
"code": "catalog_search",
"label": "Catalog, Search"
},
"created_at": "2025-12-01T12:02:21-03:00",
"updated_at": "2025-12-01 19:57:58",
"pricing": {
"price": "28.9000",
"special_price": "25.9000",
"final_price": "25.9000",
"currency": "BRL"
},
"inventory": {
"inventory_manage_stock": true,
"inventory_qty": "38.0000",
"inventory_stock_availability": "in_stock",
"inventory_stock_availability_label": "In Stock",
"inventory_is_salable": true
}
}
}
Backward compatibility
Historical fields remain present with the same semantics: set, categories, websites, status and visibility. The objects product_set, product_categories, product_websites, product_status, product_visibility, pricing and inventory are additive.
- Existing integrations can keep using only the historical fields, with no changes at all.
- New integrations should prefer the enriched objects whenever they need a name, code or label without a manual admin lookup.
Enriched references
id and name.id and name in the requested store context.id, code and name.value, code and label. Stable codes: enabled and disabled.value, code and label. Stable codes: not_visible_individually, catalog, search and catalog_search.label and name fields are meant for display and may follow the language and configuration of the Yep Platform. For integration logic, prefer id, value and code.Pricing summary
The pricing block gives a quick view of the product price in the requested context.
{
"price": "28.9000",
"special_price": "25.9000",
"final_price": "25.9000",
"currency": "BRL"
}
Inventory summary
The inventory block gives a quick view of availability.
{
"inventory_manage_stock": true,
"inventory_qty": "38.0000",
"inventory_stock_availability": "in_stock",
"inventory_stock_availability_label": "In Stock",
"inventory_is_salable": true
}
When to use the dedicated endpoints
The summaries above cover most syncs. For the full pricing detail (group prices, tier prices, tax class, MSRP) use GET /api2/price. For the full stock configuration (backorders, increments, config inheritance) use GET /api2/stock.
HTTP responses
| Scenario | Status |
|---|---|
| Success | 200 |
| Invalid parameters | 400 |
| Missing authentication or invalid token | 401 |
| Not allowed | 403 |
| Product not found | 404 |
| Internal failure | 500 |
200. The 201 statuses used when creating resources remain unchanged.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=1
6) 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=1
7) 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=200
Supported 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?id=2074&type=id
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
To query, reconcile, upload, update or delete product images, see Catalog › Images.
GET /api2/products/imagem — images of a SKU or ID, with roles and disabled.GET /api2/products/imagens — every catalog image, cursor-paginated.POST, PUT and DELETE /api2/products/imagem — base64 upload, metadata and deletion. DELETE /api2/products/imagens — full or bulk deletion.