Variants

What is a Variant in ecartAPI?

A Variant is a specific purchasable version of a Product. If a product comes in multiple sizes, colors, or configurations, each combination is a separate variant. The variant is what the customer actually buys — it carries the price, SKU, inventory quantity, and dimensional data.

Every ecommerce platform handles product variations differently — some call them "Variants," others use "Offers" tied to child identifiers, "Variations" inside an item, or "Product Variations" with attributes. ecartAPI normalizes all of these into a single canonical variant shape.

The canonical model

ecartAPI's canonical variant includes:

A unique identifier tied to the parent product.
Up to three option values (e.g., option1: "Red", option2: "Large", option3: "Cotton").
Price and compare-at price.
SKU and barcode.
Inventory quantity (tracked per location).
Weight and dimensions for shipping.
Whether it requires shipping.
An associated image.

A product with no options still has exactly one default variant — this is important. The variant always carries the purchasable attributes, even if the product has no configurable options.

The product-variant hierarchy

Understanding this relationship is essential:

Product — the catalog entry: title, description, images, category.
Variant — the purchasable unit: price, SKU, inventory, dimensions.

A product contains one or more variants. You cannot buy a "product" directly — you buy a variant of that product. Even a simple product with no size/color options has one variant that holds its price and inventory.

Important: All variant endpoints are nested under a product. There is no standalone /api/v2/variants collection — you always need the productId in the URL.

API endpoints

Method	Path	Description
GET	`/api/v2/products/{productId}/variants`	List variants for a product.
GET	`/api/v2/products/{productId}/variants/count`	Count variants for a product.
GET	`/api/v2/products/{productId}/variants/{id}`	Get a single variant by id.
POST	`/api/v2/products/{productId}/variants`	Create a variant. Not available on all platforms.
PUT	`/api/v2/products/{productId}/variants/{id}`	Update a variant. Not available on all platforms.
DELETE	`/api/v2/products/{productId}/variants/{id}`	Delete a variant. Not available on all platforms.
POST	`/api/v2/products/{productId}/variants/batch`	Create multiple variants in batch.
PUT	`/api/v2/products/{productId}/variants/batch`	Update multiple variants in batch.

Note: The {productId} is the product's identifier on the connected platform. The {id} is the variant's identifier.

Query filters

When listing variants, you can pass query parameters to paginate results.

Parameter	Description
`limit`	Maximum number of variants per page.
`page`	Page token or page number for pagination.
`sinceId`	Return variants created after this id (cursor-based pagination).
`offset`	Numeric offset for pagination.

Note: Some platforms support additional filters (e.g., WooCommerce supports name, sku, and date ranges for variants) that are applied internally but are not part of the canonical filter schema.

Response shape

Every variant response follows the same canonical shape.

Root fields

Field	Type	Description
`id`	string	The variant's unique identifier on the platform.
`productId`	string	The parent product's identifier.
`productUserId`	string	The seller/user-defined product identifier.
`name`	string	Variant name or title.
`upc`	string	Universal Product Code.
`gtin`	string	Global Trade Item Number.
`price`	string	Variant price.
`currency`	string	Currency code (e.g., `USD`, `MXN`).
`sku`	string	Stock Keeping Unit.
`barcode`	string	Barcode value.
`imageId`	string	Associated image identifier.
`imageUrl`	string	Associated image URL.
`fulfillmentService`	string	Fulfillment service handling this variant.
`option1`	string	First option value (e.g., `"Red"`).
`option2`	string	Second option value (e.g., `"Large"`).
`option3`	string	Third option value (e.g., `"Cotton"`).
`requireShipping`	boolean	Whether this variant requires physical shipping.
`countryCodeOrigin`	string	Country of origin code.
`provinceCodeOrigin`	string	Province/state of origin code.
`harmonizedSystemCode`	string	HS code for customs/international shipping.
`countryHarmonizedSystemCode`	string	Country-specific HS code.
`ecartapiUrl`	string	ecartAPI URL for this variant resource.

Nested objects

`dimensions` / `units`

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

The dimensions object holds numeric values, and units holds the measurement units.

`inventory`

Field	Type	Description
`itemId`	string	Inventory item identifier.
`quantity`	string	Available quantity in stock. A value of `"0"` means out of stock (not `null`).

`status`

Field	Type	Description
`active`	string	Whether the variant is active (`true`/`false` as string).

`dates`

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

Important notes

Variants always belong to a product. There is no way to list all variants across all products — you must specify a productId.
Inventory quantity 0 is valid. A stock of 0 is mapped as "0", not null. A null quantity means the platform did not return inventory data.
Write support varies. Not all platforms support creating, updating, or deleting variants via API.
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.