Products::variants
Manage a product's variants (create, list, update, delete...)
Description
A Variant is always attached to a Product through its product_id
.
Although every field in a Variant can be used, the guideline is that most fields should be blanks, except the ones that are explicitely different from the parent Product.
For instance, assuming a Product has multiple variants for different colors, each with a different reference, the resources would look like:
product: {
id: 50,
reference: "10001"
name: "T-Shirt",
material: "Cotton"
}
variants: [{
id: 1,
product_id: 50,
reference: "10001-1",
name: "Blue T-Shirt",
color: "Blue"
}, {
id: 2,
product_id: 50,
reference: "10001-2",
name: "Green T-Shirt",
color: "Green"
}]
Params format (creation/update)
For this resource, all the params can be included in a key variant
.
For instance, creating a Variant for Product with ID 1 in XML (POST /api/v1/products/1/variants):
<variant>
<name>TestCreationVariant</name>
<reference>TestVariant-001</reference>
<color>Blue</color>
</variant>
In JSON, the root key is not necessary and the following body would be accepted:
{
"name": "TestCreationVariant",
"reference": "TestVariant-001",
"color": "Blue"
}
Variant base fields
All the fields of the Product are available, except the category
field.
It’s assumed that all variants of a Product are in the same category at the parent Product.
Variant associated resources
Custom values (LIST)
This array, sent in the key customs
contains an entry for each Custom Fields created in the Variant’s company that is attached to a Product.
For each of those custom fields, the following keys are provided:
id
: id of the Custom Fieldname
: name of the Custom FIeldvalue
: value for this Variant, if anyupdated_at
: Datetime of the update for the value, if any
Roles
There are no specific roles for a variant, they are all inherited from the product.
A variant can be deleted if the user can manage the product and the variant isn’t currently in use.
Supported Formats
JSON XMLGET /api/v1/products/:product_id/variants
Retrieve all the variants for a given product
Examples
{ "resource": { "type": "variant", "action": "list" }, "variants": [ { "id": 2215, "name": "VariantA", "reference": "TestProduct-001", "brand": null, "color": "BLUE", "size": null, "washcare": null, "material": null, "description": null, "theme": null, "collection": null, "dimensions": null, "px40": "/assets/fallback/default-product-px40.png", "px75": "/assets/fallback/default-product-px75.png", "px150": "/assets/fallback/default-product-px150.png", "px500": "/assets/fallback/default-product-px500.png", "archived": false, "customs": [ { "column": 85, "id": 85, "name": "TEST CUSTOM", "value": "ValueA" } ], "can_delete": true }, { "id": 2216, "name": "VariantB", "reference": "TestProduct-002", "brand": null, "color": "RED", "size": null, "washcare": null, "material": null, "description": null, "theme": null, "collection": null, "dimensions": null, "px40": "/assets/fallback/default-product-px40.png", "px75": "/assets/fallback/default-product-px75.png", "px150": "/assets/fallback/default-product-px150.png", "px500": "/assets/fallback/default-product-px500.png", "archived": false, "customs": [ { "column": 85, "id": 85, "name": "TEST CUSTOM", "value": "ValueB" } ], "can_delete": true } ] }
Params
Param name | Description |
---|---|
product_id optional |
parent product id Must be a Integer |
GET /api/v1/products/:product_id/variants/:id
Retrieve the details of a specific variant
Params
Param name | Description |
---|---|
product_id required |
Parent product id, name or source_id Must be a String or an Integer |
id required |
Variant id, name or source_id Must be a String or an Integer |
POST /api/v1/products/:product_id/variants
Create a new variant for the specified product
Params
Param name | Description |
---|---|
source_id optional |
ID in Customer’s source system (optional, max 255 char.) Must be a String |
reference optional |
internal reference - length must be 255 characters maximum and unique in the scope of the company Must be a String |
material optional |
material - length must be 255 characters maximum Must be a String |
brand optional |
brand - length must be 255 characters maximum Must be a String |
color optional |
color - length must be 255 characters maximum Must be a String |
size optional |
size - length must be 255 characters maximum Must be a String |
washcare optional |
washcare - length must be 255 characters maximum Must be a String |
description optional |
description Must be a String |
dimensions optional |
dimensions - length must be 255 characters maximum Must be a String |
theme optional |
theme - length must be 255 characters maximum Must be a String |
collection optional |
collection - length must be 255 characters maximum Must be a String |
formula optional |
formula - length must be 255 characters maximum Must be a String |
target_store_date optional |
target store date, format Y-m-d Must be a String |
owner optional |
Product’s owner. If not set, default to current user. Cannot be set if current user is not company admin (current user fallback) A Winddle User. Can be either a user ID (unique integer) or a user Email. |
image optional |
image displayed in product profile Multipart encoded file |
customs optional |
Custom values for the Product An array of Custom Values for the Product. Each element of this array should have the following format:
Not providing a value for a Field will leave it as blank or keep its current value if any has been set. |
status optional |
Default values OR own company product status id/name Must be one of:validated , draft , sample .
|
PUT /api/v1/products/:product_id/variants/:id
update any attribute of the specified variant
Params
Param name | Description |
---|---|
product_id required |
Parent product id, name or source_id Must be a String or an Integer |
id required |
Variant id, name or source_id Must be a String or an Integer |
source_id optional |
ID in Customer’s source system (optional, max 255 char.) Must be a String |
reference optional |
internal reference - length must be 255 characters maximum and unique in the scope of the company Must be a String |
material optional |
material - length must be 255 characters maximum Must be a String |
brand optional |
brand - length must be 255 characters maximum Must be a String |
color optional |
color - length must be 255 characters maximum Must be a String |
size optional |
size - length must be 255 characters maximum Must be a String |
washcare optional |
washcare - length must be 255 characters maximum Must be a String |
description optional |
description Must be a String |
dimensions optional |
dimensions - length must be 255 characters maximum Must be a String |
theme optional |
theme - length must be 255 characters maximum Must be a String |
collection optional |
collection - length must be 255 characters maximum Must be a String |
formula optional |
formula - length must be 255 characters maximum Must be a String |
target_store_date optional |
target store date, format Y-m-d Must be a String |
owner optional |
Product’s owner. If not set, default to current user. Cannot be set if current user is not company admin (current user fallback) A Winddle User. Can be either a user ID (unique integer) or a user Email. |
image optional |
image displayed in product profile Multipart encoded file |
customs optional |
Custom values for the Product An array of Custom Values for the Product. Each element of this array should have the following format:
Not providing a value for a Field will leave it as blank or keep its current value if any has been set. |
status optional |
Default values OR own company product status id/name Must be one of:validated , draft , sample .
|
PATCH /api/v1/products/:product_id/variants/:id/cancel
cancel the specified variant
Params
Param name | Description |
---|---|
product_id required |
Parent product id, name or source_id Must be a String or an Integer |
id required |
Variant id, name or source_id Must be a String or an Integer |
quotations optional |
Behavior for related quotations Must be one of:nothing , smart , remove , cancel .
|
projects optional |
Behavior for related projects Must be one of:nothing , smart , remove , cancel .
|
PATCH /api/v1/products/:product_id/variants/:id/uncancel
uncancel the specified variant
Params
Param name | Description |
---|---|
product_id required |
Parent product id, name or source_id Must be a String or an Integer |
id required |
Variant id, name or source_id Must be a String or an Integer |
POST /api/v1/products/:product_id/variant/batch
Create multiple new variants for the specified product
DELETE /api/v1/products/:product_id/variants/:id
Remove a variant from a Product
Variants can only be destroyed by a company admin or the variant’s owner.
They must also not currently be in use in any project line, archived or not.
Params
Param name | Description |
---|---|
product_id required |
Parent product id, name or source_id Must be a String or an Integer |
id required |
Variant id, name or source_id Must be a String or an Integer |