Products

What is a Product in ecartAPI?

A Product is a sellable item listed in a connected store. It represents the catalog entry — the thing a customer sees, reads about, and decides to buy. Products carry the name, description, price, images, category, and other attributes that define what is being sold.

Every ecommerce platform has its own way of representing a product — some use "Products" with variants and options, others use "Listings" tied to unique identifiers, "Items" with variations, or entirely proprietary structures. Without ecartAPI, a developer building a multi-platform catalog app would need to learn and maintain a separate integration for each one.

ecartAPI solves this by mapping every platform's native product into a single canonical shape. When you call GET /api/v2/products, you get the same JSON structure regardless of which platform the connected store runs on.

The canonical model

ecartAPI's canonical product includes:

A unique identifier and a human-readable title.
A description (body HTML).
A product type and vendor.
One or more Variants — the purchasable versions (e.g., "Red / Large"). See Variants.
Options that define variant axes (e.g., "Color", "Size").
Images associated with the product.
A status (active, draft, archived) and visibility settings.
Pricing: base price, compare-at price, cost.
Inventory: tracked per variant, per location.
Tags and categories for organization.
Dates: when the product was created and last updated.

All platforms are normalized to this model. Some platforms have richer data in certain areas (e.g., ASIN and detailed condition info), and ecartAPI preserves that in dedicated fields. But the core shape is always the same.

Important: ecartAPI products support full CRUD on most platforms, but availability of create, update, and delete operations depends on each platform's API capabilities.

API endpoints

Method	Path	Description
GET	`/api/v2/products`	List products with filters.
GET	`/api/v2/products/count`	Count products matching the same filters.
GET	`/api/v2/products/{id}`	Get a single product by its platform id.
POST	`/api/v2/products`	Create a product. Not available on all platforms.
PUT	`/api/v2/products/{id}`	Update a product. Not available on all platforms.
DELETE	`/api/v2/products/{id}`	Delete a product. Not available on all platforms.
POST	`/api/v2/products/batch`	Create multiple products in batch.
PUT	`/api/v2/products/batch`	Update multiple products in batch.
DELETE	`/api/v2/products/batch`	Delete multiple products in batch.
GET	`/api/v2/products/{productId}/images`	List images for a product.
GET	`/api/v2/products/{productId}/images/{id}`	Get a single image.
POST	`/api/v2/products/{productId}/images`	Add an image to a product.
DELETE	`/api/v2/products/{productId}/images/{id}`	Delete an image.
GET	`/api/v2/products/{productId}/feedback`	Get product reviews/feedback.
POST	`/api/v2/products/{productId}/feedback`	Create product feedback.
GET	`/api/v2/catalog/search`	Search the platform's catalog.

Note: Variant endpoints (/api/v2/products/{productId}/variants/...) are documented separately in Variants.

Note: The {id} and {productId} parameters are the product's identifier on the connected platform. ecartAPI does not generate its own ids for products.

Query filters

When listing products, you can pass query parameters to filter, paginate, and sort results. ecartAPI translates these canonical filters into whatever the connected platform's API expects.

Parameter	Description
`ids`	Comma-separated list of product ids to retrieve.
`sku`	Filter by SKU.
`name`	Filter by product name/title.
`productType`	Filter by product type.
`categoryId`	Filter by category id.
`limit`	Maximum number of products per page. Default varies by platform (typically 50).
`page`	Page token or page number for pagination.
`sinceId`	Return products created after this id (cursor-based pagination).
`createdAt[from]`, `createdAt[to]`	Filter by creation date range. ISO 8601 strings recommended.
`updatedAt[from]`, `updatedAt[to]`	Filter by last-updated date range.
`status[visibility]`	Filter by visibility status.
`status[active]`	Filter by active status.
`status[status]`	Filter by platform-specific status.
`price[min]`, `price[max]`	Filter by price range.
`sort`	Sort direction: `asc` or `desc`.
`sortBy`	Field to sort by (platform-dependent).
`asc`	Alternative sort direction flag.
`searchType`	Type of search to perform.
`searchId`	Search by specific id.
`validate`	Validation flag for certain platforms.
`marketplaceId`	Filter by marketplace (for multi-marketplace platforms).

Important: Not every filter works on every platform. If a filter is not supported by the connected platform, it is silently ignored. The most universally supported filters are limit, page, and createdAt.

Response shape

Every product response follows the same canonical shape. Below is a detailed explanation of each field.

Root fields

Field	Type	Description
`id`	string	The product's unique identifier on the platform.
`productUserId`	string	The seller/user-defined identifier, if the platform supports it.
`groupId`	string	Group identifier for product variations (e.g., Amazon parent ASIN).
`sku`	string	Stock Keeping Unit — the seller's internal identifier.
`name`	string	The product title/name.
`subName`	string	Subtitle or secondary name.
`upc`	string	Universal Product Code.
`asin`	string	Amazon Standard Identification Number.
`gtin`	string	Global Trade Item Number.
`description`	string	Full product description (may contain HTML).
`currency`	string	Currency code (e.g., `USD`, `MXN`).
`productType`	string	Product type or category classification.
`quantity`	string	Total available quantity (aggregated across variants/locations).
`price`	string	Base price.
`salePrice`	string	Sale/compare-at price.
`cost`	string	Cost of goods (seller's cost).
`discount`	string	Discount amount or percentage.
`tags`	string/array	Product tags for organization.
`condition`	string	Product condition (new, used, refurbished).
`link`	string	URL to the product on the store.
`vendor`	string	Product vendor/brand.
`sellOutStock`	boolean	Whether the product can be sold when out of stock.
`imageUrl`	string	Main product image URL.
`variants`	array	Array of Variant objects.
`options`	array	Product options (e.g., Color, Size).
`images`	array	Product image objects.
`associatedItems`	array	Related or bundled items.
`locations`	array	Location-specific data.
`internationalShipment`	object	International shipping configuration.

Nested objects

`status`

Field	Type	Description
`id`	string	Platform-specific status id.
`visibility`	string	Visibility state (e.g., `visible`, `hidden`).
`active`	string	Whether the product is active (`true`/`false` as string).
`status`	string	Platform-native status value.
`ecartapiId`	string	ecartAPI-normalized status id.
`ecartapi`	string	ecartAPI-normalized status name.
`hasOptions`	boolean	Whether the product has configurable options.
`inStock`	boolean	Whether the product is currently in stock.

`dates`

Field	Type	Description
`createdAt`	string	ISO 8601 creation timestamp.
`updatedAt`	string	ISO 8601 last-updated timestamp.

`dimensions` / `units`

Field	Type	Description
`width`	string	Product width.
`height`	string	Product height.
`length`	string	Product length/depth.
`weight`	string	Product weight.

The dimensions object holds numeric values, and units holds the measurement units (e.g., cm, kg).

`category`

Field	Type	Description
`id`	string	Category identifier.
`name`	string	Category name.
`all`	array	Full category path/breadcrumb.

Important notes

Read support is universal. All integrated platforms support listing and getting products.
Write support varies. Create, update, and delete operations depend on each platform's API. If a platform does not support an operation, ecartAPI returns 400 with "The resource is not available for this ecommerce".
Batch operations allow creating, updating, or deleting multiple products in a single request. Availability is platform-dependent.
Images are a sub-resource of products. Not all platforms support image management through the API.
Catalog search (/api/v2/catalog/search) searches the platform's catalog and may return results in a different format than the standard product listing.
Response fields are platform-dependent. Not all fields listed in the response shape are available for every ecommerce platform. Some properties may be absent or returned as null depending on what the connected platform's API provides.
Variants are documented separately in Variants. Products and variants are tightly coupled — a product always has at least one variant.