Product Prices API v2
Manage current product prices, maintain product price history or schedule upcoming price changes to products.
Evance supports a number of features for pricing products, which mean Price data is separated from Product and may appear significantly different from data returned in front-end APIs.
Scopes
Access to the Product Prices API requires that the client have the following scopes granted:
products- Permits write access to add, update or remove prices.products.readonly- Read only access to search or get price data.
The Product Price Object
Define historical, current or future pricing for a Product.
accessRoleId
Restrict the price to users with an Access Role. Defaults to null.
|
currency
The ISO-4217 currency code for the price. Defaults to the default currency for the Account. |
geozoneId
Restrict the price to a Zone (one or more Countries). Defaults to null.
|
id
read-only
An unsigned 64-bit integer, which is unique across all Prices and all Evance Accounts. |
isLowestInClass
read-only
A calculated property, which is used in conjunction with inClassCount to
determine whether a price may be used as an effect "from as low as..." price. Applicable to stores
with volume/quantity pricing.
|
isTaxIncluded
A boolean indicating whether the price,
standardPrice and rrp properties
include sales tax (
true) or exclude sales tax (false).
|
minimumUnits
An integer, defaults to 1.
Applicable when type is hire or subscription.
Allows you to set the minimum term for rentals or memberships.
|
price
The current/effective price. May be less than or equal to the standardPrice.
Considered a special offer when less than standardPrice.
May be set to null to represent Price on Application.
|
productId
A unsigned 64-bit integer referencing the Product the Price is associated with. |
quantity
An integer, which defaults to the Product's Minimum Order Quantity when adding new prices. Represents the quantity in cart at which the price becomes effective, allowing for explicit quantity/volume pricing. |
rrp
Defaults to null. May be a decimal value representing the Recommended Retail Price.
|
standardPrice
A decimal value representing the standard catalogue price for the product. May be set to null to represent Price on Application.
|
startOn
The effective date of the price. Defaults to the current date when adding new prices. |
status
read-only
A price's status is calculated internally and may be one of the following:
|
type
Also known as the price mechanism. Defaults to the Product's Price Type/Mechanism when adding new prices.
|
unit
The unit is dependent upon the type.
|
List/search product prices
GET
/api/v2/products/{productId}/prices.json
Get or search for one or more product prices for a single product using a range of accepted query parameters.
URL parameters
productId
required
The product ID is required. |
Query parameters
accessRoleId:in
Filter results by one or more Access Roles in a comma-separated list of IDs. |
currency
Filter results by ISO-4217 currency code (e.g. GBP). |
geozoneId:in
Filter results by one or more Geozones in a comma-separated list of IDs. |
id:in
Return prices for a product by a comma-separated list of IDs. |
id:min
Return product prices with an ID greater than or equal to that specified. |
id:max
Return product prices with an ID less than or equal to that specified. |
id:after
Return product prices with an ID greater than that specified. |
id:before
Return product prices with an ID less than that specified. |
quantity
Filter results by quantity threshold. |
startOn:min
Return product prices with an effective start date greater than or equal to the date supplied in Y-m-d format. |
startOn:max
Return product prices with an effective start date less than or equal to the date supplied in Y-m-d format. |
startOn:after
Return product prices with an effective start date greater than the date supplied in Y-m-d format. |
startOn:before
Return product prices with an effective start date less than the date supplied in Y-m-d format. |
status
Return product prices by status:
|
type
Return product prices by 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 Price 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": 48646,
"productId": 3066,
"status": "current",
"type": "buy",
"quantity": 1,
"price": 9.99,
"unit": "each",
"minimumUnits": 1,
"rrp": null,
"standardPrice": 9.99,
"isTaxIncluded": true,
"isLowestInClass": true,
"inClassCount": 1,
"currency": "GBP",
"startOn": "2022-04-19",
"accessRoleId": null,
"geozoneId": null
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"links": {
"self": "https://examples.evance.me/api/v2/products/3066/prices.json",
"previous": null,
"next": null
}
}
Get a single Product Price
GET
/api/v2/products/{productId}/prices/{id}.json
Retrieve a single Product Price using its ID.
URL parameters
id
required
The ID of the Price 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 Price object. |
Example JSON response
{
"success": true,
"status": 200,
"data": {
"id": 48646,
"productId": 3066,
"status": "current",
"type": "buy",
"quantity": 1,
"price": 9.99,
"unit": "each",
"minimumUnits": 1,
"rrp": null,
"standardPrice": 9.99,
"isTaxIncluded": true,
"isLowestInClass": true,
"inClassCount": 1,
"currency": "GBP",
"startOn": "2022-04-19",
"accessRoleId": null,
"geozoneId": null
}
}
Add a Product Price
POST
/api/v2/products/{productId}/prices.json
Add a Product Price to your product catalogue.
Requires the products OAuth scope.
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 Price object. |
Example: minimum requirements
The
minimum requirement for a product price, which is not on offer is a price decimal
value. All other properties (such as type, currency and
isTaxIncluded) will have defaults based upon the Product or Account settings.
{
"data": {
"price": 9.99
}
}
Example: scheduling an offer
Let's say you want to schedule a special offer or price change in a month's time:
{
"data": {
"price": 9.99,
"standardPrice": 10.99,
"startOn": "2026-12-18",
"isTaxIncluded": true
}
}
Success response
If the Product Price was created successfully you should receive a response with a 201 status
code:
success
A boolean where a value of true means the Price was created successfully.
|
status
The HTTP status code e.g. 201 means the Price was created successfully. |
data
Contains the Product Price object you created including its new id. |
Error responses
If the Price could not be created you will encounter a response with a 422 status code:
success
A boolean where a value of false means the Price could not be created.
|
status
A response code of 422 means the Price 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 Price
PUT
/api/v2/products/{productId}/prices/{id}.json
Update an existing Product Price by its ID.
Requires the products OAuth scope.
URL parameters
id
required
The ID of your Product Price object |
productId
required
The ID of your Product object |
Request body
Your request body must contain an object including:
data
required
Containing updates to your Product Price object. |
Example JSON request
To update a Product Price you must PUT JSON to this resource within a data object. You
do not need to supply all properties and may choose to only supply properties that require modifying.
{
"data": {
"price": 11.99,
"standardPrice": 11.99
}
}
Success response
If the Price was updated successfully you should receive a response with a 200 status
code:
success
A boolean where a value of true means the Price was created successfully.
|
status
The HTTP status code e.g. 200 means the Price was updated successfully. |
data
Contains the Product Price object you updated. |
Error responses
If the Price 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 Price could not be updated.
|
status
|
context
|
errors
Contains an array of error objects, each will have the following properties:
|
Delete a Product Price
DELETE
/api/v2/products/{productId}/prices/{id}.json
Delete a Product Price within your product catalogue by its ID.
Requires the products OAuth scope.
URL parameters
id
required
The ID of your Product Price object |
productId
required
The ID of your Product object |
Request body
Does not require a payload
Success response
If the Price was deleted successfully you should receive a response with a 204 status code
and no body.
Error responses
If the Price 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 Price could not be deleted.
|
status
|