Yep Platform Logo
REST API · Yep Platform Technical documentation for certified integrations

Products

Create, update, query, link, attach images and delete products — with deterministic pagination, explicit store_id selection, configurable limit and opt-in pagination metadata.

REST JSON Bearer Token New in 2026

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.

200
Max limitPer page, when limit is set.
20
Default limitWhen limit is missing or invalid.
1+
Explicit storeDeterministic in multi-store setups.
opt
Metadatatotal, last_page, has_next under include_pagination=1.
POST/api2/products/

Create a configurable product.

JSONCatalog
{
  "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]
}
POST/api2/products/

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}
}
PATCH/api2/products/

Update a product.

{
  "type": "sku",
  "id": "novo_produto",
  "name": "New product name"
}
The update accepts partial success when parts of the payload are skipped due to invalid fields, attributes or values. The response details invalid_fields, invalid_attributes and invalid_attribute_values.
New: product updates can also create permanent redirects (HTTP 301) when the 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.
PATCH/api2/products/categoriesNew

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]
}
GET/api2/products/Updated

Fetch a product (single) or list with deterministic pagination.

?page=1&type=sku&id=novo_produto
The single lookup now returns human-readable references, a pricing summary and an inventory summary. Details in Single product lookup.
POST/api2/products/vincular

Link simple products to a configurable.

{
  "type": "sku",
  "configurable_id": "novo_produto",
  "simples": "novo_configuravel"
}
DELETE/api2/products/

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.

PATCH/api2/products/New parameter

Update the url_key while preserving the previous URL.

JSONproducts/write
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 Required
ID or SKU of the product to update.
type Optional
Identification type: id (default) or sku.
store_id Optional
Store ID used as the update context.
url_key To change the URL
New product URL key, without domain or leading slash.
create_url_redirect Optional
JSON boolean (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.
  • false or 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, 0 or null are rejected with HTTP 400. Use only the JSON booleans true and false.
  • 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

CodeSituation
200Product updated successfully.
400Invalid create_url_redirect, invalid JSON or missing id.
404Product not found.
409Data conflict, such as a URL already used by another product.
500Internal failure during the operation.
503Unavailability 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: true only when you want to keep the previous URL.
  • Avoid concurrent URL updates for the same product and handle 500 and 503 errors before retrying.
  • The feature keeps old URLs during new changes, but it does not rebuild missing history from changes made earlier.

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.

By SKU GET /api2/products?id=3291&type=sku
By ID GET /api2/products?id=2074&type=id
With explicit store GET /api2/products?id=3291&type=sku&store_id=1

Parameters

id Required
Product ID or SKU, according to type. Required only for the single lookup.
type Required
Defines how id is interpreted: id or sku. Required only for the single lookup.
store_id Optional
Store used as the read context. Recommended for any multi-store integration.

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

product_set New
Product attribute set, with id and name.
product_categories New
Categories linked to the product, with id and name in the requested store context.
product_websites New
Websites linked to the product, with id, code and name.
product_status New
Product status with value, code and label. Stable codes: enabled and disabled.
product_visibility New
Visibility with value, code and label. Stable codes: not_visible_individually, catalog, search and catalog_search.
The 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

ScenarioStatus
Success200
Invalid parameters400
Missing authentication or invalid token401
Not allowed403
Product not found404
Internal failure500
The single product lookup responds with 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.

store_id Optional New
Integer. ID of the store to be used as listing context. Recommended for any multi-store integration.

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.

include_pagination Optional New
Boolean flag (1 enables it). When active, includes total, last_page and has_next in the response.
total
Total number of products eligible for the current filter (only with include_pagination=1).
last_page
Last page number given the current limit.
has_next
Boolean indicating whether a next page exists. Useful to safely terminate sync loops.

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.

RuleValueBehavior
Default20Applied when limit is omitted.
Maximum200Hard 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.

Default listing GET /api2/products
Paginated GET /api2/products?page=2
Custom limit GET /api2/products?page=1&limit=100
Lookup by ID GET /api2/products?id=24404
Lookup by SKU GET /api2/products?id=ABC-123&type=sku
Explicit lookup by ID GET /api2/products?id=2074&type=id
Explicit store GET /api2/products?page=1&store_id=1
With metadata 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 page explicitly in pagination routines.
  • Use store_id whenever the integration needs deterministic results in a multi-store environment.
  • Prefer limit=50 or limit=100 for regular syncs.
  • Use limit=200 only when you actually need to reduce the number of calls.
  • Use include_pagination=1 to control pagination progress safely (loop based on has_next).

Avoid

  • Sending parameters as arrays in scalar fields — for example id[] or limit[].
  • 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.

Lookup by productGET /api2/products/imagem — images of a SKU or ID, with roles and disabled.
Global inventoryGET /api2/products/imagens — every catalog image, cursor-paginated.
Write operationsPOST, PUT and DELETE /api2/products/imagem — base64 upload, metadata and deletion. DELETE /api2/products/imagens — full or bulk deletion.