Product Specifications API v2

The Product Specifications API allows you to manage entries relating a Specification Value with a Product.

A Product may be associated with any number of specification values. Whilst the same specification value may not be assigned to the same product more than once, a Product may have multiple values from the same specification heading (so long as the heading is not used by its variant settings). For example, a retailer selling bottled drinks may have products that have multiple values for Flavour. 

We've tried to make this API flexible, allowing you to create new specification headings and values on-the-fly. However, you cannot modify existing specification headings nor specification values using this API. Please use the respective Specifications API and Specification Values API for if you wish to modify the global headings and values.

Scopes

Access to the Product Specifications API requires that the client have the following scopes granted:

  • products - Permits write access to add, update or remove specifications.
  • products.readonly - Read only access to search or get specification data.

The Product Specification object

A Product Specification entry relates a Specification Value with a Product.

Unlike the global Specification Value object, the Product Specification entry object is not sequenced. 

id read-only
An unsigned 64-bit integer, which is unique across all Product Specifications and all Evance Accounts.
productId
An unsigned 64-bit integer representing the Product the specification is assigned to.
spec
A Specification object may be supplied as a string or object when you do not know the specId, or when adding a new Specification.
specId
An unsigned 64-bit integer representing the Specification. This ID is not required and may be ignored when supplying the valueId. You only need to supply the specId when supplying a new value object for the Specification.
value
A Specification Value may be supplied as a string or object instead of a valueId when adding a new specification value, and may be used in conjunction with spec or specId.
valueId
An unsigned 64-bit integer representing the Specification Value. The only ID required when assigning a Specification Value to a Product is the valueId, because the specId is inferred from the Specification Value.

Specification uniqueness

You should be aware that:

  • A Specification Value may not be assigned to the same product more than once.
  • A Product may have more than one Specification Value associated with the same Specification heading (except where the Specification heading is used as a variance).

For example, it would be perfectly legitimate for a food-based Product to have multiple flavours:

  • Flavour = Chocolate
  • Flavour = Orange

List Specifications for a Product

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

List specification values associated with a Product using a range of accepted query parameters.

URL parameters

productId required
The Product ID is required.


Query parameters

id:in
Return values for a specification by a comma-separated list of IDs.
id:min
Return values with an ID greater than or equal to that specified.
id:max
Return values with an ID less than or equal to that specified.
id:after
Return values with an ID greater than that specified.
id:before
Return values with an ID less than that specified.
specId:in
Return entries with a Specification ID within a comma-separated list.
valueId:in
Return entries with a Specification Value ID within a comma-separated list.


JSON response

Evance will return a JSON object containing the following properties:

success
A successful search request containing zero or more results will always return a true value.
status
An integer matching the HTTP response code. A successful request will have a status of 200.
data
An array containing zero or more Product Specification data objects including value (Specification Value) and spec (Specification) sub-objects (see example below for clarity).
pagination
Search results include a pagination object contain information about the current page, total pages, the limit per page and the total number of results available.
  • limit - the number of results to return per page
  • page - the current page number
  • total - the total number of available results
  • totalPages - the total number of available pages of results
links
An object containing links to traverse available search results.
  • self - the URL for the current search.
  • previous - a URL for the previous results page, or null if there isn't one.
  • next - a URL for the next results page, or null if there isn't one


Example JSON response

In the example below you're able to see examples of a Product with a colour and size specification.

{
    "success": true,
    "status": 200,
    "data": [
        {
            "id": 1,
            "productId": 1,
            "spec": {
                "id": 1,
                "title": "Colour",
                "reference": "color",
                "description": null,
                "type": "swatch",
                "unit": null,
                "sequence": 8
            },
            "value": {
                "id": 1,
                "specId": 1,
                "value": "Red",
                "color": "#ff0000",
                "image": null,
                "maxValue": null,
                "sequence": 1
            }
        },
        {
            "id": 2,
            "productId": 1,
            "spec": {
                "id": 2,
                "title": "Size",
                "reference": "size",
                "description": null,
                "type": "string",
                "uri": null,
                "sequence": 2
            },
            "value": {
                "id": 56,
                "specId": 2,
                "value": "L",
                "color": null,
                "image": null,
                "maxValue": null,
                "sequence": 3
            }
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 100,
        "total": 2,
        "totalPages": 1
    },
    "links": {
        "self": "https://examples.evance.me/api/v2/products/1/specifications.json",
        "previous": null,
        "next": null
    }
}

Get a Product Specification

GET /api/v2/products/{productId}/specifications/{id}.json

Retrieve a single Product Specification object for a Product using its ID.

URL parameters

id required
The ID of the Product Specification is supplied as a path parameter.
productId required
The ID of the Product is supplied as a path parameter.


Response

Returns an object with the following properties:

success
A boolean where a value of true represents a successful request.
status
The HTTP status code e.g. 200 for a successful request.
data
Contains the Product Specification object with the spec and valueproperties containing the Specification and Specification Value sub-objects respectively.


Example JSON response

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


Add a Product Specification

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

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

URL parameters

productId required
The ID of the Product is supplied as a path parameter.


Request body

Your request body must contain an object including:

data required
Containing a Product Specification object based on your available data.


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 response

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

success
A boolean where a value of true means the object was created successfully.
status
The HTTP status code e.g. 201 means the object was created successfully.
data
Contains the Product Specification object you created including its new id and the complete spec and value objects.


Error responses

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

success
A boolean where a value of false means the object could not be created.
status
A response code of 422 means the object could not be created and you should check the errors property for further information.
context
The context property indicates where the error occurred. For a 422 error this will typically contain a value of data, indicating that there was an error with the data object supplied.
errors

Contains an array of error objects, each will have the following properties:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string, which may be used for translations.


Update a Product Specification

PUT /api/v2/products/{productId}/specifications/{id}.json

Update an existing Product Specification object by its ID.

Allows you to change the assigned specification value against a Product. This operates much the same as Adding a single Product Specification.

Requires the products OAuth scope.

URL parameters

id required
The ID of your Product Specification object.
productId required
The ID of your Product.


Request body

Your request body must contain an object including:

data required
Containing updates to your Product Specification object.
This operates much the same as Adding a single Product Specification.


Example JSON requests

For examples see Adding a single Product Specification.

Success response

If the Product Specification was updated successfully you should receive a response with a 200 status code:

success
A boolean where a value of true means the object was saved successfully.
status
The HTTP status code e.g. 200 means the object was updated successfully.
data
Contains the Product Specification object including the complete spec and value objects.


Error responses

If the object could not be updated you will encounter a response with either a 400, 404 or 422status code:

success
A boolean where a value of false means the object could not be updated.
status
  • 400 may indicate that the ID was not provided.
  • 404 means the Specification or Specification Value could not be found by the IDs provided.
  • 422 means the object could not be updated due to errors in the data.
context
  • parameters means the error is with the required id URL parameter.
  • data indicates an error within the object data.
  • data.spec indicates an error within the spec object data.
  • data.value indicates an error within the value object data.
errors

Contains an array of error objects, each will have the following properties:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string.


Delete a Product Specification

DELETE /api/v2/products/{productId}/specifications/{id}.json

Deleting a Product Specification entry by its ID will remove the association between the Product and the global specification value, but will leave the global specification and global specification value untouched.

Requires the products OAuth scope.

URL parameters

id required
The ID of your Product Specification object
productId required
The ID of your Product object


Request body

Does not require a payload

Success response

If the object was deleted successfully you should receive a response with a 204 status code and no body.

Error responses

If the object could not be deleted you may encounter a response with a 400, or 404 status code:

success
A boolean where a value of false means the object could not be deleted.
status
  • 400 may indicate that the ID was not provided, or the object could not be deleted for an unknown reason.
  • 404 indicates that the ID was provided, but the object could not be found.