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:
  • current
  • future - a scheduled price change
  • past - a historical price
type
Also known as the price mechanism. Defaults to the Product's Price Type/Mechanism when adding new prices.
  • buy - represents traditional retail purchases
  • hire - for product rentals over a fixed period
  • subscription - recurring revenue model.
unit
The unit is dependent upon the type.
  • each - Default where type is buy
  • day - Default where type is hire
  • week
  • month - Default where type is subscription
  • year

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:

  • current
  • future
  • past
type

Return product prices by type:

  • buy
  • hire
  • subscription


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.
  • 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


{
    "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:

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