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:
  • GTIN-12 - Universal Product Code (UPC), also called UPC-A.
  • GTIN-13 - European Article Number (EAN)
  • ISBN - International Standard Book Number (ISBN-10). ISBN-13 is covered under GTIN-13.
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:
  • new (default) 
  • used
  • refurbished
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:
  • true (default) - the product is enabled.
  • false - the product has been disabled.
A product's 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:
  • true the product has been discontinued and is unavailable for enquiry and purchase.
  • false (default) - the product is valid for enquiry or purchase (see isPurchasable).
When a product is discontinued, most Themes offer visitors a reason why (see 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:
  • true - featured
  • false (default) - not featured
The implementation of featured products may vary between Themes. Typically, featured products are flagged to appear on a website's homepage. Some Themes may display featured products differently at Category level.
isIndexable
A boolean value determining whether a Product should be indexed by external search engines:
  • true (default) - allow search engines to index the Product
  • false - the product should not be indexed by external search engines like Google.
When a Product is not indexable Evance will add a <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.
  • true - the Product is made-to-order.
  • false (default) - represents traditional retail/off-the-shelf products.
Products that are made-to-order will typically have longer lead times and might not have Inventory settings (see leadTimeMin/leadTimeMax).
isPurchasable
A boolean value indicating whether a visible product may be purchased online.
  • true (default) - the Product is available to purchase online.
  • false - the Product is cannot be purchased online, but user may be able to add the item to cart for an enquiry/quotation request (subject to store enquiry settings).
isSearchable
A boolean value indicating whether the Product can be found using the website's search facility.
  • true (default) - the Product is included in search results.
  • false - the Product excluded from search results.
isStockLimited
A boolean value indicating whether to suspend sales if the currentStock reaches zero due to limitations on stock availability.
  • true - Product inventory is limited to available stock. Orders are no longer permitted once stock is depleted.
  • false (default) - the Product can continue to be ordered when all available stock is sold, indicating that the item is easy to restock.
This setting is only applicable when a Product has Inventory/stock settings in one or more location, otherwise the 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:
  • buy (default) - traditional retail one-off purchases.
  • hire - the Product is rented for a fixed period of time.
  • subscription - recurring revenue model.
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 sku.

Learn more about Quickfind codes
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 null.

Learn more about SKUs
status read-only
There are only two statuses for a Product:
  • admin - the Product is only accessible by administrators.
  • public (default) - the Product is available to all.
A product's status is calculated and considered public if all statements below are true:
  1. the Product is active/enabled (see isActive)
  2. has no publish date, or a past publish date (see publishStartOn)
  3. has no expiry date, or an expiry date in the future (see publishEndOn)
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:
  • physical (default) - requires shipping
  • virtual - a digital product that does not require shipping
  • variant - a Basic Variant, which inherits most of its settings from a parent Product (see variantOf)
variantOf
A 64-bit integer indicating whether the Product is assigned as a variant of a master Product.
There are two types of variants:
  1. Basic Variant - has a Product type of variant and does not have its own page.
  2. Advanced Variant - has a Product type of physical or virtual, they are Products in their own right and variant by association only.
Defaults to 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:
  • admin - products only visible to site administrators.
  • public - products that are available for display to the public.
A product has a public status when it meets the following criteria:
  • The product is marked as active (isActive=true)
  • The product is published with a publishStartDate of null or with a date less than or equal to the current date.
  • The product is published with a publishEndDate of null or with a date in the future.
type
Return products matching the supplied type:
  • physical
  • virtual


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.
  • limit - the number of products 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 nullif there isn't one.
  • next - a URL for the next results page, or null if there isn't one

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:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string (e.g. error.not-unique if the alias supplied is already in use).


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
  • 400 may indicate that the ID was not provided.
  • 404 means Product could not be found by the ID provided.
  • 422 means the Product could not be updated due to errors in the Product data.
context
  • parameters means the error is with the required id URL parameter.
  • data indicates an error within the Product 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 (e.g. error.not-unique if the alias supplied is already in use).


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
  • 400 may indicate that the ID was not provided, or the Product could not be deleted for an unknown reason.
  • 404 indicates that the ID was provided, but the product could not be found.