Add a Product Specification

POST /api/v2/products/{productId}/specifications.json

Add a Product Specification entry relating a Specification Value to a Product.

Scope

Requires the products OAuth scope.

Path parameters

Request body

Your request body must contain an object including:

Example: minimum requirements

The minimum requirement for assigning a Specification Value to a Product is the valueId.

{
    "data": {
        "valueId": 1423
    }
}

However, we’re aware that you may not always know the valueId, or you may want to add a new specification entirely. Instead of having to do that through multiple API calls to the Specifications API and the Specification Values API, the Product Specifications API allows you to add new Specifications or Values within the same API.

Evance will accept:

• The valueId or a new value object/string.
• If value is supplied, then specId or a new spec object/string is required.

Whilst you can add new spec or value objects in this manner, you cannot update an existing spec or value object. You should use the Specifications API and the Specification Values API to do this.

Example: create a new value for a known specId

Adding a new value string for a known specId. Let’s assume our specId relates to a "Colour" specification.

{
  "data": {
    "specId": 1,
    "value": "Red"
  }
}

Evance will attempt to find a “Red” value where specId = 1, if the value exists it’s ID will be assigned. Otherwise, a new Specification Value will be created and assigned. For a swatch based specification, you could also supply color as part of the request.
For full details of the available properties see Specification Values API.

{
  "data": {
    "specId": 1,
    "value": {
      "value": "Red",
      "color": "#FF0000"
    }
  }
}

Example: create a new spec and value

You can associate new/existing spec and value objects at the same time:

{
  "data": {
    "spec": "Colour",
    "value": "Red"
  }
}

When spec is supplied as a string Evance will check for a direct reference match, or a case-insensitive title match against existing specifications.

OR, you can be more explicit:

{
  "data": {
    "spec": {
      "title": "Colour",
      "reference": "color",
      "type": "swatch"
    },
    "value": {
      "value": "Red",
      "color": "#FF0000"
    }
  }
}

Success responses

If the Product Specification object was created successfully you should receive a response with a 201 status code. Evance will respond with the complete spec and value object:

{
    "success": true,
    "status": 200,
    "data": {
      "id": 1,
      "productId": 1,
      "spec": {
        "id": 1,
        "title": "Colour",
        "reference": "color",
        "description": null,
        "type": "swatch",
        "uri": null,
        "sequence": 1
      },
      "value": {
        "id": 1,
        "specId": 1,
        "value": "Red",
        "color": "#ff0000",
        "image": null,
        "maxValue": null,
        "sequence": 1
      }
    }
}

Error responses

If the Product Specification entry object could not be created you will encounter a response with a 422 status code: