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.
|
links
An object containing links to traverse available search results.
|
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
}
},
{
"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
valueIdor a newvalueobject/string. -
If
valueis supplied, thenspecIdor a newspecobject/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:
|
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
|
context
|
errors
Contains an array of error objects, each will have the following properties:
|
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
|