Products API v2
The Product resource lets you get, create, update or remove products from an Account's product catalogue.
Scopes
Access to the Products API requires that the client have the following scopes granted:
products- Permits write access to add, update or remove products.products.readonly- Read only access to search or get product data.
The Product object
Product objects are the largest in Evance, but very few properties are required - making it easy to get started.
A sub-set of these properties are applicable to Basic Variants, which inherit most of their settings from their parent.
alias
required
The unique URL path to the Product page. Currently, the alias property must start with /product/.
|
averageRating
read-only
The average customer rating between 1 and 5 across
the total number of published reviews for the product in the countRating property.
A product with no reviews will have an average rating of null.
|
bandId
Products may optionally be assigned to one Product Band - typically used by merchants to group Products by profit margin. Defaults to null representing no Product Band assignment. |
barcode
The GTIN/ISBN reference number for the Product as a string up to 14 characters long. Accepts the following barcode standards:
|
commodityCode
Harmonized Commodity Description and Coding System - a six-digit code that categorises goods being traded internationally. The first two digits represent the chapter, the middle two digits represent the heading within the chapter, and last two digits represent the sub-heading within the heading. |
condition
The condition of the Product may be one of the following:
|
countRating
read-only
An integer representing the total number of published reviews associated with the Product. Defaults to 0. |
countryOfOrigin
An ISO 3166 alpha-2 country code representing the country of manufacture, production, design or brand origin. For example GBrepresenting United Kingdom.
Defaults to null. |
createdBy
read-only
An integer representing the Contact ID who created the Product. This may be set to null if the Product was created by an App or via import.
|
createdOn
read-only
The datetime in ISO-8601 format when the Product was created (e.g. 2026-11-18T13:50:41+00:00). |
currentStock
read-only
An integer representing the total available stock for the product across all Inventory Locations. When a Product has no inventory settings the value of current stock is set to null indicating
that the Product is not stocked. |
description
The short description for a product can have up to 255 characters (may not contain HTML). A product's short description is typically displayed at category-level and/or as a sales introduction on the product page. |
discontinuedBy
An integer representing the Contact ID who discontinued the Product. Defaults to null.
|
discontinuedOn
The datetime in ISO-8601 format when the Product was discontinued (e.g. 2026-11-18T13:50:41+00:00). Defaults to null.
Please note, unlike the publishStartDate you cannot schedule a Product to be
discontinued in the future.
|
discontinuedReason
Up to 255 characters (may not contain HTML) describing the reason why a Product was discontinued. Most themes will display the discontinuedReason publicly when the Product's
isDiscontinuedflag is set to true. |
id
read-only
The Product ID is an unsigned 64-bit integer, which is unique across all Products and all Evance Accounts - no other Product on our Platform will have the same id. |
isActive
A boolean value determining whether a Product is enabled or disabled:
isActive status contributes to the overall visibility
statusof a Product.
|
isDiscontinued
A boolean value determining whether a Product is discontinued and therefore no longer available for enquiry or purchase:
discontinuedReason)
and whether an alternative Product is available (see supersededBy). Being discontinued
does not affect the Product's visibility status.
|
isFeatured
A boolean value determining whether a Product should be featured:
|
isIndexable
A boolean value determining whether a Product should be indexed by external search engines:
<meta name="robots" content="noindex" />
meta tag to the Product's page. However, the Product will remain available to the Website's internal search engine (see
isSearchable).
|
isMadeToOrder
A boolean value indicating whether a product is manufactured/produced to order.
leadTimeMin/leadTimeMax). |
isPurchasable
A boolean value indicating whether a visible product may be purchased online.
|
isSearchable
A boolean value indicating whether the Product can be found using the website's search facility.
|
isStockLimited
A boolean value indicating whether to suspend sales if the currentStock reaches
zero due to limitations on stock availability.
isStockLimited flag is ignored and no limitations are placed on order quantities.
|
leadTimeMax
An integer greater than or equal to zero. Represents the number of days from point of order to dispatch when the Product is out of stock, or if no Inventory settings are available (not stocked). Set to 0to represent a same-day dispatch. The leadTimeMax should
be greater than or equal to the leadTimeMin setting.
|
leadTimeMin
An integer greater than or equal to zero. Represents the number of days from point of order to dispatch when the currentStock level is greater than 0. Set
to
0 to represent a same-day dispatch. The leadTimeMin should
be less than or equal to the leadTimeMax setting.
|
lowStockLevel
An integer at which the currentStock level is considered low. Defaults to
0.
Used by Themes to show a "Limit stock" notification to visitors on Product pages. |
manufacturerId
An integer representing the Manufacturer/Vendor ID associated with the Product. Defaults to null.
|
metaDescription
String up to 255 characters used for the Product's SEO meta description ( <meta name="description">) - may not contain HTML.
When a Product's metaDescription is empty, its short description will
be used.
|
metaKeywords
A string containing comma-separated SEO-friendly keywords to be included in the Product's <meta name="keywords"> tag.
|
metaTitle
A string up to 120 characters containing the Product's SEO-friendly page title. When a Product's metaTitle is empty, its title will
be used.
|
modifiedBy
read-only
An integer representing the Contact ID of the last user to modify the Product. |
modifiedOn
read-only
The datetime the Product was last modified in ISO-8601 format (e.g. 2026-11-18T13:50:41+00:00) |
model
A string up to 120 characters representing the Product's manufacturer model name or number (see also manufacturerIdand range).
|
orderQuantityMax
An integer greater than the orderQuantityMin or 0 representing
the maximum quantity that may be added to cart.
Defaults to 0 - represents unlimited.
|
orderQuantityMin
An integer greater than or equal to 1 representing the minimum quantity that
may be added to cart.
Defaults to 1.
|
packagedDepth
The outer depth/length in millimetres (mm) of the packaged Product - used in shipping calculations. |
packagedHeight
The outer height in millimetres (mm) of the packaged Product - used in shipping calculations. |
packagedWeight
The gross weight in kilograms (kg) of the packaged Product - used in shipping calculations. |
packagedWidth
The outer width in millimetres (mm) of the packaged Product - used in shipping calculations. |
partNumber
A string representing the manufacturer's part number for the product. |
priceType
Indicates the pricing model/strategy for the Product, which may be one of the follow:
|
publishEndOn
Accepts a date in ISO-8601 format (e.g. 2022-01-01) or null.
This setting allows merchants to schedule when products are no longer available - removing them from the
website. If a null value is supplied the Product will not expire.
Defaults to null.
|
publishStartOn
Accepts a date in ISO-8601 format (e.g. 2022-01-01) or null.
This setting allows merchants to populate their catalogue and schedule product releases in advance. If a
nullvalue is supplied the Product is assumed to have an immediate start date.
Defaults to null.
|
quickfind read-only
A Quickfind code is a unique sequential integer which identifies the Product within an Account (not globally unique across our Platform). Unlike Product id, Quickfind numbers always start
from 1 and increment with each new Product/Variant.
Originally, Quickfind numbers were implemented as a fallback reference number for Products missing an
|
range
A string up to 120 characters representing the Product's manufacturer range (see also manufacturerIdand model).
|
shippingClassId
An integer - the ID of the Shipping Classifier to use when calculating shipping costs at checkout. When set to null the Account's default Shipping Classifier will be used.
Defaults to null. Not applicable to virtual/digital products.
|
sku
A string up to 30 characters. The Product's unique Stock Keeping Unit (SKU) code is optional, but MUST be unique to the Account if set (including SKUs for Variants). We recommend SKUs should be kept as short as possible with only alpha-numeric characters, dashes and/or underscores. Defaults to |
status read-only
There are only two statuses for a Product:
status is calculated and considered public if
all statements below are true:
|
supersededBy
An optional Product ID representing an alternative or replacement to the current Product when it's discontinued (see isDiscontinued). Most Themes will use this setting to direct visitors
to newer product information instead of indexed Products resulting in 404 errors or unexpected 301 redirects.
Defaults to null.
|
taxClassId
An integer - the ID of the Tax Classifier to use when calculating taxation at checkout. When set to null the Account's default Tax Classifier will be used.
Defaults to null.
|
template
A string representing the Product Template reference defined in the Templates Config. This allows merchants the flexibility to display some Product pages differently to others. However, most sites only have a default ("index") Product layout. When set to null the default Product Template is assumed.
Defaults to null.
|
title
required
A string up to 120 characters. |
type
The following types of Product are currently available:
|
variantOf
A 64-bit integer indicating whether the Product is assigned as a variant of a master Product. There are two types of variants:
null.
|
List/search products
GET
/api/v2/products.json
Get or search for one or more products using a range of accepted query parameters.
Requires either the products or products.readonly OAuth scope.
Query parameters
bandId
Return products associated with a Band ID. Supplying an empty string will return products without an associated band. |
bandId:in
Return products associated with any Band ID supplied within a comma-separated list. |
barcode:in
Return products matching any barcode supplied within a comma-separated list. |
createdOn:min
Return products with a createdOn datetime greater than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:41+00:00) |
createdOn:max
Return products with a createdOn datetime less than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:41+00:00) |
createdOn:after
Return products with a createdOn datetime greater than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:41+00:00) |
createdOn:before
Return products with a createdOn datetime less than the datetime supplied in
ISO-8601 format (e.g. 2026-11-18T13:50:41+00:00)
|
id:in
Return products specified within a comma-separated list of Product IDs. |
id:min
Return products with an ID greater than or equal to that specified. |
id:max
Return products with an ID less than or equal to that specified. |
id:after
Return products with an ID greater than that specified. |
id:before
Return products with an ID less than that specified. |
manufacturerId
Return products associated with a Manufacturer ID. Supplying an empty value will return products without an associated Manufacturer. |
manufacturerId:in
Return products associated with any matching Manufacturer ID within a comma-separated list. |
modifiedOn:min
Return products with a modifiedOn datetime greater than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:41+00:00) |
modifiedOn:max
Return products with a modifiedOn datetime less than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:41+00:00) |
modifiedOn:after
Return products with a modifiedOn datetime greater than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:41+00:00) |
modifiedOn:before
Return products with a modifiedOn datetime less than the datetime supplied in
ISO-8601 format (e.g. 2026-11-18T13:50:41+00:00)
|
partNumber:in
Return products with a matching partNumber within a comma-separated list. |
quickfind:in
Return products specified within a comma-separated list of Quickfind codes. |
quickfind:min
Return products with a Quickfind code greater than or equal to that specified. |
quickfind:max
Return products with a Quickfind code less than or equal to that specified. |
quickfind:after
Return products with a Quickfind code greater than that specified. |
quickfind:before
Return products with a Quickfind code less than that specified. |
sku:in
Return products matching any SKU supplied within a comma-separated list (case-insenstive). We recommend SKUs only contain letters, numbers, dashes and underscores. However, if your SKU contains a comma you should encapsulate the string within double quotes. For example, sku:in=ABC-123,"CDE,F-456"
|
status
Return products matching the supplied status:
public status when it meets the following criteria:
|
type
Return products matching the supplied type:
|
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 data objects. |
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": 3066,
"type": "physical",
"priceType": "buy",
"variantOf": null,
"quickfind": 1,
"sku": "EX-D1",
"barcode": "",
"commodityCode": "",
"status": "public",
"isActive": true,
"title": "Unicorn Tears Gin Liqueur",
"alias": "/product/unicorn-tears-gin-liqueur",
"description": "The sweet tears of unicorns, bottled - juicy passion-fruit and tropical mango flavoured",
"metaTitle": "",
"metaDescription": "",
"metaKeywords": "",
"workflowId": null,
"manufacturerId": null,
"range": "",
"model": "",
"isMadeToOrder": false,
"partNumber": "",
"packagedWeight": 0.75,
"packagedWidth": 0,
"packagedHeight": 0,
"packagedDepth": 0,
"isDiscontinued": false,
"discontinuedOn": null,
"discontinuedBy": null,
"discontinuedReason": null,
"createdOn": "2019-11-09T01:02:00+00:00",
"createdBy": 213,
"modifiedOn": "2022-01-06T21:19:28+00:00",
"modifiedBy": 213,
"publishStartOn": null,
"publishEndOn": null,
"isStockLimited": false,
"lowStockLevel": 0,
"currentStock": null,
"taxClassId": 1,
"leadTimeMin": 0,
"leadTimeMax": 0,
"orderQuantityMin": 1,
"orderQuantityMax": 0,
"shippingClassId": null,
"bandId": null,
"supersededBy": null,
"isPurchasable": true,
"isSearchable": true,
"isFeatured": false,
"condition": "new",
"template": null,
"isIndexable": true,
"averageRating": null,
"countRating": 0
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"links": {
"self": "https://examples.evance.me/api/v2/products.json",
"previous": null,
"next": null
}
}
Get a single Product
GET
/api/v2/products/{id}.json
Retrieve a single Product using its ID.
Requires either the products or products.readonly OAuth
scope.
URL parameters
id
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 object. |
Example JSON response
{
"success": true,
"status": 200,
"data": {
"id": 3066,
"type": "physical",
"priceType": "buy",
"variantOf": null,
"quickfind": 1,
"sku": "EX-D1",
"barcode": "",
"commodityCode": "",
"status": "public",
"isActive": true,
"title": "Unicorn Tears Gin Liqueur",
"alias": "/product/unicorn-tears-gin-liqueur",
"description": "The sweet tears of unicorns, bottled - juicy passion-fruit and tropical mango flavoured",
"metaTitle": "",
"metaDescription": "",
"metaKeywords": "",
"workflowId": null,
"manufacturerId": null,
"range": "",
"model": "",
"isMadeToOrder": false,
"partNumber": "",
"packagedWeight": 0.75,
"packagedWidth": 0,
"packagedHeight": 0,
"packagedDepth": 0,
"isDiscontinued": false,
"discontinuedOn": null,
"discontinuedBy": null,
"discontinuedReason": null,
"createdOn": "2019-11-09T01:02:00+00:00",
"createdBy": 213,
"modifiedOn": "2022-01-06T21:19:28+00:00",
"modifiedBy": 213,
"publishStartOn": null,
"publishEndOn": null,
"isStockLimited": false,
"lowStockLevel": 0,
"currentStock": null,
"taxClassId": 1,
"leadTimeMin": 0,
"leadTimeMax": 0,
"orderQuantityMin": 1,
"orderQuantityMax": 0,
"shippingClassId": null,
"bandId": null,
"supersededBy": null,
"isPurchasable": true,
"isSearchable": true,
"isFeatured": false,
"condition": "new",
"template": null,
"isIndexable": true,
"averageRating": null,
"countRating": 0
}
}
Add a new Product
POST
/api/v2/products.json
Add a product to your product catalogue.
Requires the products OAuth scope.
Request body
Your request body must contain an object including:
data
required
Containing a Product object. |
Example JSON request
The minimum requirements for a product is a title. However, to avoid URL conflicts you should
supply a unique alias.
{
"data": {
"sku": "EX-D1",
"title": "Unicorn Tears Gin Liqueur",
"alias": "/product/unicorn-tears-gin-liqueur",
"description": "The sweet tears of unicorns, bottled - juicy passion-fruit and tropical mango flavoured"
}
}
Success response
If the Product was created successfully you should receive a response with a 201 status
code:
success
A boolean where a value of true means the Product was created successfully.
|
status
The HTTP status code e.g. 201 means the Product was created successfully. |
data
Contains the Product object you created including its new id. |
Error responses
If the Product could not be created you will encounter a response with a 422 status code:
success
A boolean where a value of false means the Product could not be created.
|
status
A response code of 422 means the Product 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
PUT
/api/v2/products/{id}.json
Update a product already within your product catalogue by its ID.
Requires the products OAuth scope.
URL parameters
id
required
The ID of your Product object |
Request body
Your request body must contain an object including:
data
required
Containing updates to your Product object. |
Example JSON request
You do not need to supply all properties and may choose to only supply properties that require modifying.
{
"data": {
"sku": "EX-D1",
"title": "Unicorn Tears Gin Liqueur",
"alias": "/product/unicorn-tears-gin-liqueur",
"description": "The sweet tears of unicorns, bottled - juicy passion-fruit and tropical mango flavoured"
}
}
Success response
If the Product was updated successfully you should receive a response with a 200 status
code:
success
A boolean where a value of true means the Product was updated successfully.
|
status
The HTTP status code e.g. 200 means the Product was updated successfully. |
data
Contains the Product object you updated. |
Error responses
If the Product 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 Product could not be updated.
|
status
|
context
|
errors
Contains an array of error objects, each will have the following properties:
|
Delete a Product
DELETE
/api/v2/products/{id}.json
Delete a product within your product catalogue by its ID.
Requires the products OAuth scope.
URL parameters
id
required
The ID of your Product object |
Request body
Does not require a payload
Success response
If the Product was deleted successfully you should receive a response with a 204 status
code and no body.
Error responses
If the Product 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 Product could not be deleted.
|
status
|