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
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