Products

Manage my company products (create, list, update, delete...)

Description

Products come in two flavors, base product (Product hereafter) and product variant (Variant hereafter).

Variants are always linked to a single Product (parent product) and represents some minor modification on the Product.

This resource is only concerned with Products and will contain the list of associated Variants. To create/update Variants, please refer to the Products/Variant resource.

Products can also have multiple files attached and those files will be made available for viewing within the Project line using this Product.

Params format (creation/update)

For this resource, all the params can be included in a key product.

For instance, creating a Product in XML (POST /api/v1/products):

<product>
  <name>TestCreationProduit</name>
  <reference>TestProduit-001</reference>
  <color>Blanc</color>
</product>

In JSON, the root key is not necessary and the following body would be accepted:

{
  "name": "TestCreationProduit",
  "reference": "TestProduit-001",
  "color": "Blanc"
}

Product base fields

NameType
idInteger (unique)
nameString (2..100 chars)
source_idString (max 255 chars)
referenceString (unique, max 255 chars)
materialString (max 255 chars)
brandString (max 255 chars)
colorString (max 255 chars)
sizeString (max 255 chars)
washcareString (max 255 chars)
descriptionString (max 255 chars)
dimensionsString (max 255 chars)
themeString (max 255 chars)
collectionString (max 255 chars)
formulaString (max 255 chars)
target_store_dateDate
px40String
px75String
px150String
px500String
archivedBoolean
showcasedBoolean
statusString (max 255 chars)
created_atDatetime
updated_atDatetime

Product associated resources

When receiving a Product from Winddle, the following data may also be available.

To retrieve all of it for a given product, please use the GET /:id service.

The associated resources marked with a (LIST) are also available when listing Products with the GET / service.

Sizesets (LIST)

The sizesets assigned to a product are sent in the key sizesets.

This list of sizesets will contain all the sizesets that could apply to this Product, as defined in the Company settings.

Category (LIST)

A product can be assigned to one (and only one) Product Category.

There are 2 keys related to Product Category in the Product resource response:

  • category : it contains the category assigned to the Product, not present when none has been set. The fields available for the category are at least id, source_id and label.

  • categories: it’s an array containing the category assigned to the product as well as all its ancestor up to the root node of the product categories hierarchies. This field allows to conveniently rebuild the full-subtree of the used category for a given product.

Variants (LIST)

The variants are sent with the key variants as an array of Variants.

Each Variant has roughly the same fields as a Product (the Product base fields).

For more details, you may refer to the Variants service.

Custom values (LIST)

This array, sent in the key customs contains an entry for each Custom Fields created in the Product’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 Product, if any
  • updated_at: Datetime of the update for the value, if any

Projects (LIST)

This array, sent in the key projects will contain the last 3 projects which contain at least one project line the token owner can access and which is using this product.

For each of those projects, the name and the id will be provided.

Attachments

The files attached to a product are sent with the key attachments.

For more details, you may refer to the Attachments service.

Roles

There are 2 roles sent with each Product:

  • can_delete: can the Token owner delete this product? (it will be set to False if the product is still in use, regardless of who the owner is)

  • can_manage: can the Token owner edit fields, manage variants or archive this product?

Supported Formats

JSON XML

GET /api/v1/products

Retrieve the basic details of your company products

Params

Param name Description
filter
optional

Filters to apply on the list of Products to return

Param for filters

Filter your company products

Params

Param name Description
filter
optional

Filters to apply on the list of Products to return

Param for filters

GET /api/v1/products/:id

Full details of the requested product (see resource format)

Params

Param name Description
id
required

Product id, name or source_id

Must be a String or an Integer

POST /api/v1/products

Create a new product

Params

Param name Description
source_id
optional

ID in Customer’s source system (optional, max 255 char.)

Must be a String
season
optional

Product season

Must be a String or an Integer
category
optional

Product category id or label, 0 or null will reset the Product category

Must be a String or an Integer
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.
name
required

name - length must be between 3 and 100 characters

Must be a String

PUT /api/v1/products/:id

Update some product attributes (one or more attributes)

Params

Param name Description
id
optional

Product id, name or source_id

Must be a String or an Integer
name
optional

name - length must be between 3 and 100 characters

Must be a String
remove_image
optional

Product image will be removed if this is set to true

Boolean (true/false)
source_id
optional

ID in Customer’s source system (optional, max 255 char.)

Must be a String
season
optional

Product season

Must be a String or an Integer
category
optional

Product category id or label, 0 or null will reset the Product category

Must be a String or an Integer
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.

DELETE /api/v1/products/:id

Destroy a product permanently from Winddle

Products can only be destroyed by a company admin or the product’s owner.

They must also not currently be in use in any project line, archived or not.

Params

Param name Description
id
required

Product id, name or source_id

Must be a String or an Integer

PUT /api/v1/product/:id/archive

Archive a product

Products can only be archived by a company admin or the product’s owner.

Params

Param name Description
id
required

Product id, name or source_id

Must be a String or an Integer

PUT /api/v1/product/:id/unarchive

Unarchive a product

Products can only be unarchived by a company admin or the product’s owner.

Params

Param name Description
id
required

Product id, name or source_id

Must be a String or an Integer

PATCH /api/v1/product/:id/cancel

Cancel and archive a product

PATCH /api/v1/product/:id/uncancel

Uncancel a product

PATCH /api/v1/product/:id/like

Like the product (current user)

PATCH /api/v1/product/:id/unlike

Unlike the product (current user)

PATCH /api/v1product/:id/showcase

Showase the product (current user)

PATCH /api/v1showcase/:id/unshowcase

Showcase the product (current user)