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 Field
name: name of the Custom FIeld
value: value for this Variant, if any
updated_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 XML

>>>

GET /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: `{ field: The Winddle ID or the Name of the Custom Field value: The value for this field }` 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: `{ field: The Winddle ID or the Name of the Custom Field value: The value for this field }` 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
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