Inventory API v2

The Inventory resource lets you get, create, update or remove Product stock data in one or more Locations.

Scopes

Access to the Inventory API requires that the client have the following scopes granted:

  • inventory - Permits write access to add, update or remove inventory.
  • inventory.readonly - Read only access to search or get inventory data.

The Inventory object

Inventory is associated with a Product and a Location.

A Product may have zero or more associated Inventory entries. In fact, a Product may have more than one Inventory object at the same Location where stock is found at different shelf locations (bin numbers).

createdOn read-only
The datetime in ISO-8601 format when the Inventory entry was created (e.g. 2026-11-18T13:50:40+00:00).
defaultReorderQuantity
An integer representing the default/preferred number of units to procure when quantityInStock reaches the issueAlertAtQuantity.
id read-only
An unsigned 64-bit integer unique to the Inventory object.
isPreferred
A boolean value, which represents whether the Inventory is the preferred stock for the Product.
issueAlertAtQuantity
An integer representing a low stock threshold for the quantityInStock.
locationId
An unsigned 64-bit integer representing the Location the Inventory is associated with.
modifiedOn read-only
The datetime in ISO-8601 format when the Inventory entry was last modified (e.g. 2026-11-18T13:50:40+00:00).
productId
An unsigned 64-bit integer representing the Product the Inventory is associated with.
quantityAvailable read-only
The quantity of the Product available to order is dynamically calculated.
quantityInStock
The quantity of the Product present at the Location.
quantityReserved read-only
The quantity of the Product reserved for outstanding orders is dynamically calculated.
shelfLocation
A string containing a bin number or shelf location, which references where the inventory may be found within the Location.

List/search inventory

GET /api/v2/inventory.json

Get or search for one or more Inventory entries using a range of accepted query parameters.

Requires either the inventory or inventory.readonly OAuth scope.

Query parameters

createdOn:min
Return inventory with a createdOn datetime greater than or equal to the datetime supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
createdOn:max
Return inventory with a createdOn datetime less than or equal to the datetime supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
createdOn:after
Return inventory with a createdOn datetime greater than the datetime supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
createdOn:before
Return inventory with a createdOn datetime less than the datetime supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
id:in
Return inventory specified within a comma-separated list of Inventory IDs.
id:min
Return inventory with an ID greater than or equal to that specified.
id:max
Return inventory with an ID less than or equal to that specified.
id:after
Return inventory with an ID greater than that specified.
id:before
Return inventory with an ID less than that specified.
locationId
Return inventory associated with a single Location ID.
locationId:in
Return inventory associated with one or more comma-separated Location IDs.
modifiedOn:min
Return inventory with a modifiedOn datetime greater than or equal to the datetime supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
modifiedOn:max
Return inventory with a modifiedOn datetime less than or equal to the datetime supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
modifiedOn:after
Return inventory with a modifiedOn datetime greater than the datetime supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
modifiedOn:before
Return inventory with a modifiedOn datetime less than the datetime supplied in ISO-8601 format (e.g. 2026-11-18T13:50:40+00:00)
productId
Return Inventory associated with a single Product ID.
productId:in
Return Inventory associated with one or more comma-separated Product IDs.


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 Inventory 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 items 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": 5641,
            "productId": 7604,
            "locationId": 854,
            "shelfLocation": "SHELF-62977cbe0a46c",
            "quantityInStock": 100,
            "quantityReserved": null,
            "quantityAvailable": 100,
            "defaultReorderQuantity": 0,
            "isPreferred": false,
            "issueAlertAtQuantity": 0,
            "modifiedOn": "2022-06-01T14:50:50+00:00",
            "createdOn": "2022-06-01T14:50:50+00:00"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 100,
        "total": 1,
        "totalPages": 1
    },
    "links": {
        "self": "https://examples.evance.me/api/v2/inventory.json",
        "previous": null,
        "next": null
    }
}


Get a single Inventory object

GET /api/v2/inventory/{id}.json

Retrieve a single Inventory object using its ID.

Requires either the inventory or inventory.readonly OAuth scope.

URL parameters

id required
The ID of the Inventory object 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 Inventory object.


Example JSON response

{
    "success": true,
    "status": 200,
    "data": {
        "id": 2464,
        "productId": 7604,
        "locationId": 845,
        "shelfLocation": "SHELF-62977cbe0a46c",
        "quantityInStock": 100,
        "quantityReserved": null,
        "quantityAvailable": 100,
        "defaultReorderQuantity": 0,
        "isPreferred": false,
        "issueAlertAtQuantity": 0,
        "modifiedOn": "2022-06-01T14:50:50+00:00",
        "createdOn": "2022-06-01T14:50:50+00:00"
    }
}


Add new Inventory

POST /api/v2/inventory.json

Add Inventory against a Product and Location.

Requires the inventory OAuth scope.

Request body

Your request body must contain an object including:

data required
Containing an Inventory object.


Example JSON request

The minimum requirements are productId, locationId, and quantityInStock.

{
    "data": {
        "productId": 18647,
        "locationId": 5644,
        "quantityInStock": 100
    }
}


Success response

If the Inventory was created successfully you should receive a response with a 201 status code:

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 Inventory object you created including its new id.


Error responses

If the Inventory 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:

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

PUT /api/v2/inventory/{id}.json

Update an existing Inventory record.

Requires the inventory OAuth scope.

URL parameters

id required
The ID of your Inventory object


Request body

Your request body must contain an object including:

data required
Containing updates to your Inventory object.


Example JSON request

To update Inventory 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": {
        "quantityInStock": 231,
    }
}


Success response

If the object 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 updated successfully.
status
The HTTP status code e.g. 200 means the object was updated successfully.
data
Contains the Inventory object you updated.


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


Delete Inventory

DELETE /api/v2/inventory/{id}.json

Delete Inventory - indicates the Product is no longer stocked at the Location.

Requires the inventory OAuth scope.

URL parameters

id required
The ID of your Inventory object


Request body

Does not require a payload

Success responses

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