Products

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.

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.

Parameters

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

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
}

HTTP responses

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.

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.

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.

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.

Product images

To query, reconcile, upload, update or delete product images, see Catalog › Images.