Aalam Stock
API docs by Redocly

Stock (0.8.0)

Download OpenAPI specification:

Authentication

Every API request should be sent with a valid token. The token can be fetched by registering a remote application in your account's Settings -> Users & Groups -> Remote applications. The token of the remote application should be passed along with the header X-Auth-Token and also make sure the remote application is authorized with necessary permissions.

Items

API related to inventory items, including item creation, retrieval, updates, deletion, pricing, variants, ratings, movement, and related item management.

Delete item

Deletes an existing item from the inventory.

Depending on the current state of the item, the item may either be permanently removed or marked as deleted. Items that have inventory history or serve as the primary variant are soft deleted to preserve data integrity.

Associated search index entries and item image metadata are also removed.

Features

  • Delete an item from inventory.
  • Remove associated resource references.
  • Remove inventory count records.
  • Remove monthly inventory count records.
  • Remove item pricing records.
  • Remove item property associations.
  • Remove item images from item details.
  • Remove the item from the search index.
  • Automatically performs soft delete when permanent deletion is not allowed.

Notes

  • The item_id path parameter must be a valid item ID.
  • Items that are parents of active combo items cannot be deleted.
  • Items having inventory transactions are marked as deleted instead of being permanently removed.
  • Primary variant items are marked as deleted instead of being permanently removed.
  • When soft deleted, the item code is cleared and the item is marked as deleted.
  • Requires Items/delete permission.

Permissions

Items/delete is needed

path Parameters
item_id
required
integer
Example: 101

Unique identifier of the item to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get item details

Retrieves detailed information for a specific item.

This endpoint returns complete information about an item, including pricing, inventory, properties, offers, and optional resources such as descriptions, images, videos, ratings, and variants.

Features

  • Retrieve complete details for a single item.
  • Include plain-text description.
  • Include localized descriptions.
  • Include item images.
  • Include item videos.
  • Include ratings.
  • Retrieve all variants of an item.
  • Retrieve combo item and combo pack details.
  • Retrieve system properties.

Notes

  • The item_id path parameter is required.
  • Anonymous users can access only public, non-deleted items.
  • Purchase price and purchase discount are omitted for users who are not authorized to view purchase prices.
  • When variants is requested, the response includes the selected item and all of its variants.
  • When variants is requested, the properties field is returned as an array of property objects instead of a key/value mapping.
  • Requires Items/access, Items/manage, or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
  • Items/manage-content
path Parameters
item_id
required
integer
Example: 101

Unique identifier of the item.

query Parameters
description
boolean
Example: description=true

Include the plain-text item description.

descriptions
boolean
Example: descriptions=true

Include all available item descriptions.

images
boolean
Example: images=true

Include image metadata.

videos
boolean
Example: videos=true

Include video metadata.

ratings
boolean
Example: ratings=true

Include rating details.

variants
boolean
Example: variants=true

Include all variants of the item.

sys_props
string
Example: sys_props=1

Include or filter system properties.

Responses

Response samples

Content type
application/json
{
  • "canonical_name": "Dell Inspiron 15",
  • "code": "ITEM-001",
  • "combo_items": [
    ],
  • "combo_packs": [
    ],
  • "description": "string",
  • "descriptions": { },
  • "id": 101,
  • "images": { },
  • "inv_parent_id": 0,
  • "inv_ratio": 0,
  • "is_public": true,
  • "launch_date": "2019-08-24",
  • "name": "Laptop",
  • "num_ratings": 0,
  • "num_variants": 0,
  • "offers": {
    },
  • "opening_stock": 0,
  • "properties": { },
  • "purchase_discount": 0,
  • "purchase_price": 0,
  • "rating": 0,
  • "ratings": { },
  • "sale_discount": 0,
  • "sale_price": 0,
  • "short_description": "string",
  • "stock": 0,
  • "stock_tat": 0,
  • "stock_threshold": 0,
  • "sub_title": "Gaming Laptop",
  • "type": "Inventory",
  • "type_id": 1,
  • "uom": "Nos",
  • "variants": [
    ]
}

Update item

Updates an existing item and its associated information.

This endpoint supports updating item details such as pricing, discounts, stock information, unit of measure, item type, visibility, descriptive information, and custom properties. Depending on the supplied parameters, the update may also be applied to all variants of the item.

If the variant_face parameter is supplied, the request updates only the variant face information instead of performing a general item update.

Features

  • Update item name and code.
  • Update sale and purchase prices.
  • Update sale and purchase discounts.
  • Update stock threshold and opening stock.
  • Update unit of measure (UOM).
  • Update launch date and stock turnaround time.
  • Update item type.
  • Update subtitle, short description and canonical name.
  • Update public visibility.
  • Update custom item properties.
  • Update all variants using the update_variants option.
  • Update variant face independently.

Notes

  • The item_id path parameter must be a valid numeric item ID.
  • At least one request parameter must be supplied.
  • Updating purchase_price or purchase_discount requires authorization to access purchase prices.
  • Only one of sale_discount or sale_discount_pr may be supplied.
  • Only one of purchase_discount or purchase_discount_pr may be supplied.
  • A discount cannot be set unless the corresponding price already exists.
  • Opening stock cannot be updated for:
    • Items sharing inventory.
    • Combo items.
    • Items using Inventory Sharing.
  • Unknown request parameters are treated as custom item properties.
  • When update_variants is enabled, supported updates are applied to all variants belonging to the same item.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
item_id
required
integer
Example: 101

Unique identifier of the item to update.

Request Body schema: application/json
required
canonical_name
string

Canonical name.

code
string

Item code.

is_public
boolean

Whether the item is publicly visible.

launch_date
string <date-time>

Launch date.

name
string

Item name.

opening_stock
number

Opening stock quantity.

purchase_discount
number

Purchase discount percentage.

purchase_discount_pr
number

Purchase discount amount.

purchase_price
number

Purchase price.

sale_discount
number

Sale discount percentage.

sale_discount_pr
number

Sale discount amount.

sale_price
number

Sale price.

short_description
string

Short description.

stock_tat
number

Stock turnaround time.

stock_threshold
number

Stock threshold.

sub_title
string

Item subtitle.

type
string

Item type.

uom
string

Unit of measure.

update_variants
boolean

Apply supported updates to all variants of the item.

variant_face
string

Update only the variant face.

Responses

Request samples

Content type
application/json
{
  • "canonical_name": "string",
  • "code": "string",
  • "is_public": true,
  • "launch_date": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "opening_stock": 0,
  • "purchase_discount": 0,
  • "purchase_discount_pr": 0,
  • "purchase_price": 0,
  • "sale_discount": 0,
  • "sale_discount_pr": 0,
  • "sale_price": 0,
  • "short_description": "string",
  • "stock_tat": 0,
  • "stock_threshold": 0,
  • "sub_title": "string",
  • "type": "string",
  • "uom": "string",
  • "update_variants": true,
  • "variant_face": "string"
}

Response samples

Content type
{
  • "message": "string"
}

Add or update item combo

Creates or updates a combo item by associating one or more existing items with a parent item.

This endpoint validates that the parent item exists before updating its combo definition. Items that are already configured as combo items are not allowed to be reused as components of another combo.

Features

  • Create a new combo for an item.
  • Update the items that belong to an existing combo.
  • Validate that the parent item exists.
  • Prevent nested combo items.

Notes

  • The item_id path parameter identifies the parent combo item.
  • The request body must include the items collection.
  • All referenced items must exist.
  • Items that are already configured as combo items cannot be added as members of another combo.
  • Anonymous users are not allowed to access this endpoint.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

  • Denied for anonymous users (Users / Apps not registered in the settings)
path Parameters
item_id
required
integer
Example: 101

Unique identifier of the parent combo item.

Request Body schema: application/json
required
items
required
Array of objects

List of items to be associated with the combo.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
{
  • "message": "string"
}

Get item movement

Retrieves the inventory movement history for an item.

This endpoint returns the inward and outward inventory transactions for the specified item. Each movement corresponds to a claim transaction and can include quantities, damaged quantities, application information, descriptions, remarks, and dates.

The response can be customized by selecting specific fields and applying filters.

Features

  • Retrieve inventory movement history.
  • Supports inward and outward movements.
  • Supports field selection.
  • Supports filtering and sorting.
  • Supports movement history for inventory parent items and variants.
  • Includes combo item movement information when applicable.

Notes

  • item_id must be a valid integer.
  • By default, up to 100 records are returned.
  • Supported sorting:
    • date.asc
    • date.desc
  • Additional filters may be supplied using supported movement fields.
  • If the item is part of an inventory hierarchy, quantities are adjusted using the inventory ratio.
  • Combo item movements include additional combo information.
  • Anonymous users are not allowed.
  • Requires Items/access or Items/manage permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
  • Denied for anonymous users (Users / Apps not registered in the settings)
path Parameters
item_id
required
integer
Example: 101

Item identifier.

query Parameters
fields
string
Example: fields=date,direction,quantity,remarks

Comma-separated list of fields to include.

Supported values:

  • claim_id
  • description
  • app_id
  • date
  • id
  • direction
  • quantity
  • damaged_qty
  • remarks
max
integer
Default: 100
Example: max=50

Maximum number of records to return.

sort
string
Enum: "date.asc" "date.desc"
Example: sort=date.desc

Sort order.

claim_id
integer

Filter by claim identifier.

app
string

Filter by application identifier.

direction
string
Enum: "inward" "outward"

Filter by movement direction.

date
string

Filter by movement date.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get item opening stock

Retrieves the opening stock details for an item on a specified date.

This endpoint calculates the opening stock by combining the item's initial opening stock with all inward and outward inventory movements recorded before the specified date. Optionally, it can also return a movement summary between the specified date and another date.

Features

  • Retrieve opening stock for an item.
  • Calculates cumulative inward and outward stock movements.
  • Uses monthly inventory summaries for efficient calculation.
  • Includes claim transactions after the monthly summary period.
  • Optionally returns inventory movement summary for a date range.

Notes

  • The date query parameter is mandatory.
  • The opening stock is calculated as of the beginning of the specified date.
  • If summary_till is provided, an additional movement summary is returned for the period between date and summary_till.
  • Anonymous users are not allowed to access this endpoint.
  • Requires Items/access or Items/manage permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
  • Denied for anonymous users (Users / Apps not registered in the settings)
path Parameters
item_id
required
integer
Example: 101

Unique identifier of the item.

query Parameters
date
required
string <date-time>
Example: date=2026-08-01T00:00:00

Date for which the opening stock is calculated.

summary_till
string <date-time>
Example: summary_till=2026-08-31T23:59:59

Returns inventory movement summary from date up to this date.

Responses

Response samples

Content type
application/json
Example
{
  • "inward": 350,
  • "outward": 120
}

Get item price

Retrieves the sale and/or purchase price details for one or more items.

This endpoint returns the current or historical pricing information for items, including price, discount, discount percentage, discount mode, and the date the price was last updated.

For a single item, both sale and purchase prices are returned. For multiple items, the response can be filtered to include only sale prices, only purchase prices, or both.

Features

  • Retrieve sale and purchase prices.
  • Retrieve historical prices using a specific date.
  • Retrieve prices for one or more items.
  • Filter the response to include only sale or purchase prices.
  • Purchase prices are returned only to users authorized to view them.

Notes

  • The item_id path parameter accepts a single item ID or a comma-separated list of item IDs.
  • The optional date parameter retrieves the price that was effective on the specified date.
  • For multiple items, the type parameter can be used to retrieve only sale prices or purchase prices.
  • Purchase prices are omitted for users without purchase-price access.
  • Anonymous users are not allowed to access this endpoint.
  • Requires Items/access or Items/manage permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
  • Denied for anonymous users (Users / Apps not registered in the settings)
path Parameters
item_id
required
string
Example: 101

Item ID or comma-separated list of item IDs.

query Parameters
date
string <date-time>
Example: date=2026-08-01T10:00:00

Retrieve the price effective on the specified date.

type
string
Enum: "sale" "purchase" "sale,purchase"
Example: type=sale

Price types to retrieve. Applicable only when multiple item IDs are specified.

Responses

Response samples

Content type
application/json
Example
[
  • {
    },
  • {
    }
]

Get item properties

Retrieves the properties associated with one or more items.

This endpoint returns the list of properties and their values for the specified item IDs. It supports retrieving either all properties or only the varying properties across multiple items.

Features

  • Retrieve properties for one or more items.
  • Retrieve only varying properties across items.
  • Supports multiple item IDs.
  • Supports inclusion of system properties.
  • Anonymous users receive only public properties.

Notes

  • The item_id path parameter accepts a single item ID or a comma-separated list of item IDs.
  • When the path parameter is _, the item ID must be supplied using the id query parameter.
  • Setting varying=true returns only properties whose values differ among the specified items.
  • By default, system properties are excluded.
  • Use the sys_props parameter to include system properties.
  • If a single item ID is supplied, the response is a single object.
  • If multiple item IDs are supplied, the response is an array.
  • Requires Items/access, Items/manage, or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
  • Items/manage-content
path Parameters
item_id
required
string
Example: 101

Item ID, a comma-separated list of item IDs, or _ to specify the item IDs using the id query parameter.

query Parameters
id
string
Example: id=101,102

Required only when the path parameter is _. Contains one or more comma-separated item IDs.

varying
boolean
Example: varying=true

Return only properties whose values vary across the specified items.

sys_props
string
Example: sys_props=1

Controls inclusion of system properties.

Values:

  • 0 or false (default): Exclude system properties.
  • 1, true, or *: Include all system properties.
  • Comma-separated property names: Include only the specified system properties.

Responses

Response samples

Content type
application/json
Example
[
  • {
    },
  • {
    }
]

Get related items

Retrieves items related to the specified item based on shared properties.

This endpoint returns a collection of items that are considered related to the specified item. Related items are ranked according to the number of matching properties and returned in descending order of relevance.

The fields returned for each related item can be customized using the fields query parameter.

Features

  • Retrieves items related by shared properties.
  • Results are ranked by property similarity.
  • Supports custom item fields.
  • Supports filtering by item attributes.
  • Supports limiting the number of returned items.
  • Anonymous users receive only public items.

Notes

  • The requested item itself is excluded from the results.
  • By default, a maximum of 6 related items are returned.
  • When name_unique is requested, the response internally uses the item name while ensuring one representative item is returned for each unique item name.
  • If fields is omitted, a default set of commonly used item fields is returned.
  • Requires Items/access, Items/manage, or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
  • Items/manage-content
path Parameters
item_id
required
integer
Example: 101

Item identifier.

query Parameters
fields
string
Example: fields=id,name_unique,sale_price,stock

Comma-separated list of item fields to include in the response.

Default:

id,name_unique,sale_price,sale_discount,sub_title,stock,uom,num_variants,type

max
integer
Default: 6
Example: max=6

Maximum number of related items to return.

name
string

Filter by item name.

code
string

Filter by item code.

stock
number

Filter by available stock.

type
string

Filter by item type.

type_id
integer

Filter by item type identifier.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get item variants

Retrieves the variants associated with one or more items.

This endpoint returns all variants belonging to the specified item. Each variant includes its identifier, code, property values, and inventory information. Additional item fields can be requested using the fields query parameter.

When the ids query parameter is specified, only the variant item IDs are returned instead of the complete variant details.

Features

  • Retrieve variants for one or more items.
  • Retrieve only variant IDs.
  • Include additional item fields in each variant.
  • Supports anonymous and authenticated users.
  • Supports filtering of system properties.

Notes

  • Multiple item IDs can be supplied as a comma-separated list.
  • Anonymous users receive only public variants.
  • One variant is marked as the face variant using the is_face field.
  • If an item has no variants, an empty list is returned.
  • Requires Items/access, Items/manage, or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
  • Items/manage-content
path Parameters
item_id
required
string
Example: 101

Item ID or comma-separated list of item IDs whose variants are to be retrieved.

query Parameters
ids
boolean
Example: ids=true

Return only variant item IDs instead of complete variant details.

fields
string
Example: fields=sale_price,stock,uom

Comma-separated list of additional item fields to include in each variant.

sys_props
string
Example: sys_props=1

Include or filter system properties.

Responses

Response samples

Content type
application/json
Example
[
  • 101,
  • 102,
  • 103
]

Get item collections

Retrieves multiple collections of inventory items in a single request.

This endpoint groups items based on one or more item types or custom collection filters and returns the matching items for each collection.

Collections can be generated by supplying item type IDs or by defining custom collection filters using query parameters. Each collection is returned as a separate list of items.

If no item types or collections are specified, the endpoint automatically retrieves items for every available item type.

Features

  • Retrieve items grouped by one or more item types.
  • Retrieve multiple collections in a single request.
  • Support custom collection filters.
  • Apply common filtering, sorting and pagination to every collection.
  • Automatically returns all item types when no collection is specified.
  • Supports anonymous users.

Collections

Collections can be requested in two ways:

  • type_ids – Retrieves items for the specified item type IDs.
  • coll. – Creates a named collection using custom filter parameters.
  • type. – Retrieves items for an individual item type.

Notes

  • If max is not supplied, the endpoint returns up to 4 items for each collection.
  • Every collection is returned under its corresponding collection name or item type identifier.
  • Each collection contains a lightweight item representation including pricing, stock and rating information.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
query Parameters
type_ids
string
Example: type_ids=1,2,3

Comma-separated list of item type IDs.

max
integer
Example: max=4

Maximum number of items to return for each collection.

coll.{collection_name}
string

URL-encoded query string defining filters for a custom collection.

type.{type_id}
string

Adds an individual item type as a collection.

Responses

Response samples

Content type
application/json
{
  • "1": [
    ],
  • "Featured": [
    ]
}

Delete multiple items

Deletes one or more inventory items in a single request.

The endpoint accepts a comma-separated list of item IDs and attempts to remove each item from the inventory.

Before deleting an item, the system checks whether it has been referenced by any inventory claims. Items that have never been claimed are permanently deleted along with their associated inventory records, pricing, custom properties and resource references.

Items that are already referenced by claims cannot be permanently removed. Instead, they are marked as deleted by setting the is_deleted flag and clearing the item code, allowing historical claim records to remain valid.

Associated item images and search index entries are also removed after the deletion request is processed.

Features

  • Delete multiple items in a single request.
  • Automatically removes inventory count records.
  • Removes item pricing information.
  • Removes custom property associations.
  • Removes resource references.
  • Deletes associated item media.
  • Removes items from the search index.
  • Automatically performs soft deletion for items that are referenced by inventory claims.

Notes

  • The id query parameter is mandatory.
  • Item IDs must be provided as a comma-separated list.
  • Items referenced by claims are not physically removed.
  • Soft-deleted items have their is_deleted flag set to true and their item code cleared.
  • The endpoint does not return any response body on success.

Permissions

Items/delete is needed

query Parameters
id
required
string
Example: id=101,102,103

Comma-separated list of item IDs to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get items

Retrieves inventory items based on the supplied filters.

This endpoint returns one or more items from the inventory and supports filtering, searching, sorting, pagination and selective field retrieval.

Depending on the supplied parameters, the endpoint can also generate search suggestions, export item data, include variants, custom properties and active offers.

Features

  • Retrieve all inventory items.
  • Filter items using supported query parameters.
  • Perform full-text item search.
  • Get search suggestions.
  • Supports pagination.
  • Supports sorting.
  • Retrieve only selected fields.
  • Include item variants.
  • Include custom properties.
  • Include varying properties.
  • Include active offers.
  • Export item information for download.
  • Automatically hides purchase price information from users without purchase-price permission.

When the search parameter is supplied, the endpoint performs a full-text search across inventory items.

Search results are ordered by relevance by default and support continuation using the page parameter.

Download

Supplying the download query parameter switches the endpoint into export mode. Instead of returning normal API results, the endpoint prepares the selected item data for download.

Download is available only for authenticated users.

Variants

Include the variants field together with name_unique to retrieve variant information for each item.

Notes

  • Purchase price fields are automatically removed for users without sufficient permission.
  • Invalid field names result in a Bad Request response.
  • Anonymous users cannot use download mode.
  • Search pagination is supported through the returned page token.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
  • Items/manage-content
query Parameters
search
string

Full-text search query.

suggest
boolean

Return search suggestions instead of search results.

fields
string
Example: fields=id,name,code,sale_price

Comma-separated list of fields to include in the response.

max
integer

Maximum number of items to return.

page
string

Pagination token returned by a previous search request.

sort
string

Sort order for the returned items.

download
boolean

Export matching items instead of returning the normal API response.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Add a new item

Creates a new inventory item.

This endpoint registers a new item in the inventory and returns the unique identifier of the newly created item.

The item must have a type and name. If the specified item type does not already exist, the system automatically creates it before creating the item.

The endpoint supports defining pricing information, discounts, inventory settings, unit of measurement, searchable descriptions, visibility options and custom properties during item creation.

Features

  • Creates a new inventory item.
  • Automatically creates the item type if it does not exist.
  • Supports sale and purchase pricing.
  • Supports percentage-based and fixed discounts.
  • Supports opening stock and stock threshold configuration.
  • Associates the item with a Unit of Measurement (UOM).
  • Creates custom properties and assigns property values.
  • Creates an inventory record for the item.
  • Optionally stores item description information.
  • Updates the search index so the item becomes searchable immediately.

Notes

  • type and name are mandatory.
  • Item names must be unique.
  • If opening_stock is specified, the launch date is automatically initialized.
  • If uom is omitted, the default unit unit is used.
  • Custom properties are automatically created if they do not already exist.
  • If description is supplied, it is stored separately after the item has been created.

Permissions

Items/manage is needed

Request Body schema: application/json
required
canonical_name
string

Canonical name used for search and indexing.

code
string

Optional item code or SKU.

description
string

Detailed description stored separately from the main item.

is_public
boolean

Indicates whether the item is publicly visible.

name
required
string

Unique name of the item.

opening_stock
number

Initial stock quantity.

object

Custom item properties.

purchase_discount
number

Fixed purchase discount.

purchase_discount_pr
number

Percentage purchase discount.

purchase_price
number

Purchase cost of the item.

sale_discount
number

Fixed sale discount.

sale_discount_pr
number

Percentage sale discount.

sale_price
number

Selling price of the item.

short_description
string

Short searchable description.

stock_tat
number

Stock turnaround time.

stock_threshold
number

Minimum stock level before the item is considered low in stock.

sub_title
string

Optional subtitle displayed with the item.

type
required
string

Item type. A new type is created automatically if it does not already exist.

uom
string

Unit of Measurement. Defaults to unit if omitted.

Responses

Request samples

Content type
application/json
{
  • "canonical_name": "wireless-mouse",
  • "code": "WM-001",
  • "description": "Premium wireless mouse with silent clicks.",
  • "is_public": true,
  • "name": "Wireless Mouse",
  • "opening_stock": 100,
  • "properties": {
    },
  • "purchase_discount": 20,
  • "purchase_discount_pr": 2,
  • "purchase_price": 650,
  • "sale_discount": 50,
  • "sale_discount_pr": 5,
  • "sale_price": 799,
  • "short_description": "Ergonomic wireless mouse",
  • "stock_tat": 2,
  • "stock_threshold": 10,
  • "sub_title": "Bluetooth Mouse",
  • "type": "Electronics",
  • "uom": "unit"
}

Response samples

Content type
application/json
{
  • "id": 101
}

Duplicate existing items

Creates one or more new inventory items by duplicating existing items.

Each duplicated item inherits the source item's configuration, including item type, pricing, inventory settings, unit of measurement and custom properties. Additional properties can be applied to every duplicated item, while existing properties may be overridden or removed.

This endpoint can also operate in clone mode by supplying the clone query parameter. In clone mode, item media such as images are copied to the newly created items in addition to the item details.

Features

  • Duplicate one or more existing items.
  • Preserve pricing, inventory settings and unit of measurement.
  • Copy all custom properties from the source item.
  • Add common properties to every duplicated item.
  • Override or remove selected properties.
  • Append custom suffixes to item names and item codes.
  • Optionally clone associated media when clone mode is enabled.
  • Returns a mapping between the original item IDs and the newly created item IDs.

Notes

  • The items field is mandatory.
  • Each duplicated item is created as a new inventory item with its own unique identifier.
  • During duplication, the system automatically records the relationship between the original item and its duplicate.
  • When clone mode is enabled, images and other supported media are copied from the original item to the cloned item.

Permissions

Items/manage is needed

query Parameters
clone
boolean

Enables clone mode. When present, associated item media is copied to the newly created items.

Request Body schema: application/json
required
code_suffix
string

Suffix appended to the duplicated item code.

object

Properties that will be added to every duplicated item.

required
Array of objects

List of items to duplicate.

name_suffix
string

Suffix appended to the duplicated item name.

object

Properties to add, replace or remove during duplication.

Responses

Request samples

Content type
application/json
{
  • "code_suffix": "-COPY",
  • "common_properties": {
    },
  • "items": [
    ],
  • "name_suffix": " - Copy",
  • "new_properties": {
    }
}

Response samples

Content type
application/json
{
  • "101": 220,
  • "105": 221
}

Bulk update item prices

Performs bulk price updates for items that match the specified filters.

This endpoint allows updating sale or purchase prices and discounts for multiple items in a single request. It also supports saving, executing, and deleting reusable bulk update templates.

Features

  • Bulk update sale or purchase prices.
  • Apply fixed discount amounts or percentage discounts.
  • Filter items before applying updates.
  • Save bulk update configurations as reusable templates.
  • Execute previously saved templates.
  • Delete saved templates.

Notes

  • Only one pricing type can be updated per request: sale or purchase.
  • Only one discount type is allowed: either a fixed discount or a discount percentage.
  • Supplying both discount amount and discount percentage results in a 400 Bad Request response.
  • Template operations are controlled using the title and action parameters.
  • Requires Items/manage permission.
Request Body schema: application/json
required
action
string
Enum: "save" "run" "delete"

Template action.

set.purchase_discount
number

Fixed purchase discount amount.

set.purchase_discount_pr
number

Purchase discount percentage.

set.purchase_price
number

New purchase price.

set.sale_discount
number

Fixed sale discount amount.

set.sale_discount_pr
number

Sale discount percentage.

set.sale_price
number

New sale price.

title
string

Template name used for saving, executing, or deleting a bulk update template.

Responses

Request samples

Content type
application/json
{
  • "brand": "Samsung",
  • "category": "Electronics",
  • "set.sale_price": 150
}

Response samples

Content type
application/json
{
  • "num": 42
}

Get bulk price update templates

Retrieves all saved bulk price update templates.

This endpoint returns the list of templates stored for bulk price update operations. Each template contains the saved filters, pricing mode, and pricing values that can later be executed or modified.

Features

  • Retrieve all saved bulk price update templates.
  • Returns template configuration including filters and pricing details.
  • Templates can be used with the bulk price update endpoint.

Notes

  • Returns an empty list if no templates have been saved.
  • Requires Items/manage permission.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Get items properties

Retrieves item property information used throughout the inventory.

This endpoint can return either:

  • The complete list of item properties with their values and usage counts.
  • Only the available property names.
  • Property statistics for items matching a search query.

Property values are aggregated across all matching items, making this endpoint suitable for building property filters, faceted search, product filtering, and analytics.

Features

  • Retrieve all item properties.
  • Retrieve only property names.
  • Retrieve detailed property metadata.
  • Search properties using free-text search.
  • Return aggregated property value counts.
  • Return item count and price summary.
  • Supports anonymous users.

When a search query is provided, only properties belonging to the matching items are returned.

The response also includes a summary object containing:

  • Minimum sale price
  • Average sale price
  • Maximum sale price
  • Number of matching items
  • Search tokens used

Notes

  • fields parameter is not supported and returns an error.
  • only_name=true returns only property names.
  • detailed=true returns additional property metadata.
  • sys_props can be used to include system-defined properties.
query Parameters
only_name
boolean
Example: only_name=true

Return only property names.

detailed
boolean
Example: detailed=true

Include detailed information for property names.

sys_props
boolean
Example: sys_props=true

Include system-defined properties.

search
string
Example: search=iphone 16

Search items and return aggregated properties for matching results.

search_toks
string
Example: search_toks=iphone apple

Pre-tokenized search string.

Responses

Response samples

Content type
application/json
{
  • "Brand": {
    },
  • "Color": {
    },
  • "__*summary*__": {
    }
}

Delete item property

Deletes an existing item property.

This endpoint removes an item property using its property name. Any associated property asset files are also removed if they exist.

Features

  • Delete an item property by its name.
  • Remove associated property assets from storage.
  • Permanently remove the property record from the database.

Notes

  • Property is identified using its current name.
  • If the specified property does not exist, a 404 Not Found response is returned.
  • Requires Items/manage permission.
path Parameters
property_name
required
string
Example: Color

Name of the item property to delete.

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Update item property

Updates an existing item property.

This endpoint allows modifying the name or visibility of an item property. Only the provided fields are updated.

Features

  • Rename an existing item property.
  • Change whether the property is publicly visible.
  • Partial updates are supported.
  • Property is identified using its current name.

Notes

  • At least one of name or is_public must be provided.
  • If both fields are omitted, the request is rejected.
  • If the specified property does not exist, a 404 Not Found response is returned.
  • Requires Items/manage permission.
path Parameters
property_name
required
string
Example: Color

Name of the item property to update.

Request Body schema: application/json
required
is_public
boolean

Whether the property is publicly visible.

name
string

New name for the item property.

Responses

Request samples

Content type
application/json
{
  • "is_public": true,
  • "name": "Colour"
}

Response samples

Content type
application/json
{
  • "success": true
}

Get item property values

Retrieves property values for one or more items.

This endpoint returns the values associated with one or more item properties for the specified item IDs. It can retrieve values for a specific property or for all properties.

Features

  • Retrieve values for a specific property.
  • Retrieve all property values by using * as the property name.
  • Supports multiple item IDs in a single request.
  • Anonymous users only receive values for public properties.

Notes

  • The item_id query parameter is mandatory.
  • Multiple item IDs should be provided as a comma-separated list.
  • Multiple property names can also be provided as a comma-separated list.
  • Set property_name to * to retrieve all properties.
  • The optional sys_props parameter controls inclusion of system properties.
  • Requires Items/access or Items/manage permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
path Parameters
property_name
required
string
Example: Color

Property name, a comma-separated list of property names, or * to retrieve all properties.

query Parameters
item_id
required
string
Example: item_id=101,102,103

Comma-separated list of item IDs.

sys_props
string
Example: sys_props=1

Include or filter system properties.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Types

API related to types.

Delete item type

Deletes an existing item type.

If the item type is not referenced by any items, it is permanently removed. Otherwise, it is soft deleted by marking it as deleted and renaming it to maintain uniqueness.

After deletion, the item type cache and search index are updated.

Features

  • Permanently delete an item type.
  • Soft delete item types that are still referenced.
  • Automatically clears the item type cache.
  • Automatically removes the item type from the search index.

Notes

  • The type_id path parameter must be a valid integer.
  • Referenced item types are soft deleted instead of being permanently removed.
  • Soft deleted item types are renamed by appending a unique suffix.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
type_id
required
integer
Example: 1

Unique identifier of the item type.

Responses

Response samples

Content type
{
  • "message": "string"
}

Update item type

Updates an existing item type.

This endpoint allows modifying the name, description, and public visibility of an item type. At least one updatable field must be supplied in the request.

After a successful update, the item type cache is cleared. If the name or description is modified, the search index is also updated.

Features

  • Update the item type name.
  • Update the item type description.
  • Update the public visibility of an item type.
  • Automatically refreshes the search index.
  • Automatically clears the item type cache.

Notes

  • The type_id path parameter must be a valid integer.
  • At least one of type, description, or is_public must be supplied.
  • The is_public value accepts true, false, 1, or 0.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
type_id
required
integer
Example: 1

Unique identifier of the item type.

Request Body schema: application/json
required
description
string

New description for the item type.

is_public
boolean

Whether the item type is publicly visible.

type
string

New item type name.

Responses

Request samples

Content type
application/json
{
  • "description": "Electronic items and accessories.",
  • "is_public": true,
  • "type": "Electronics"
}

Response samples

Content type
{
  • "message": "string"
}

Get item types

Retrieves the list of available item types.

This endpoint returns item types that can be assigned to items. Anonymous users receive only public item types, while authenticated users can retrieve all available item types. Deleted item types are excluded by default unless explicitly requested.

Features

  • Retrieve all available item types.
  • Retrieve only public item types for anonymous users.
  • Optionally include deleted item types.
  • Optionally include the public visibility flag for authenticated users.
  • Returns cached results when no query parameters are supplied.

Notes

  • Anonymous users receive only public item types.
  • Deleted item types are excluded unless include_deleted is specified.
  • Authenticated users can request the is_public field by supplying inc_public_acc.
  • Responses without query parameters may be served from cache.
  • Requires Items/access or Items/manage permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
query Parameters
include_deleted
boolean

Include deleted item types in the response.

inc_public_acc
boolean
Example: inc_public_acc=true

Include the is_public field in the response for authenticated users.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create item type

Creates one or more item types.

This endpoint allows creating either a single item type or multiple item types in a single request. A request must contain either the type parameter or the types collection, but not both.

After a successful creation, the item type search index and cached item type list are automatically updated.

Features

  • Create a single item type.
  • Create multiple item types in one request.
  • Optionally associate a description with an item type.
  • Automatically updates the search index.
  • Automatically clears the item type cache.

Notes

  • The request must contain either type or types.
  • Supplying both type and types is not allowed.
  • Duplicate item type names result in a conflict.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

Request Body schema: application/json
required
One of
description
string

Description of the item type.

type
required
string

Name of the item type.

Responses

Request samples

Content type
application/json
{
  • "types": [
    ]
}

Response samples

Content type
application/json
{
  • "id": 15
}

Claims

API related to Claims.

Delete claim

Deletes an existing inventory claim.

Depending on the claim date and the requesting application, the claim is either deleted directly or automatically reversed by creating a new claim with the opposite direction. All associated inventory counts are updated accordingly.

When a claim is deleted on the same day it was created (or by the owning application), the claimed items are removed and the claim is permanently deleted. Otherwise, a reversal claim is created to preserve inventory history.

Features

  • Delete an existing claim.
  • Automatically update inventory counts.
  • Remove all claimed items for same-day deletions.
  • Remove associated claim metadata.
  • Automatically create a reversal claim when direct deletion is not allowed.
  • Preserve inventory history for historical claims.

Notes

  • The claim_id path parameter must be a valid integer.
  • Users can delete only claims belonging to their application.
  • Historical claims are reversed instead of being permanently deleted.
  • A claim cannot be reversed more than once.
  • Requires Items/claim permission.

Permissions

Items/claim is needed

path Parameters
claim_id
required
integer
Example: 101

Unique identifier of the claim.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get claim details

Retrieves detailed information about a specific inventory claim.

The response includes claim metadata, application information, formatted description and URL (when available), and the list of claimed items associated with the claim.

Features

  • Retrieve claim details by ID.
  • Retrieve application and provider information.
  • Retrieve claim direction and remarks.
  • Retrieve claim date.
  • Retrieve formatted description and URL from claim templates.
  • Retrieve all claimed items associated with the claim.

Notes

  • The claim_id path parameter must be a valid integer.
  • Anonymous users are not allowed to access this endpoint.
  • Requires Items/claim, Items/access, or Items/manage permission.

Permissions

Any of the following permissions are needed

  • Items/claim
  • Items/access
  • Items/manage
  • Denied for anonymous users (Users / Apps not registered in the settings)
path Parameters
claim_id
required
integer
Example: 101

Unique identifier of the claim.

Responses

Response samples

Content type
application/json
{
  • "app_code": "string",
  • "app_name": "string",
  • "date": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "direction": "inward",
  • "items": [
    ],
  • "provider_code": "string",
  • "provider_name": "string",
  • "remarks": "string",
  • "url": "string"
}

Update claim details

Updates the details of an existing inventory claim.

This endpoint allows modifying the claim date, remarks, and additional metadata associated with a claim. When the claim date changes, the corresponding monthly inventory summaries and inventory count tracking are updated automatically.

Features

  • Update the claim date.
  • Update claim remarks.
  • Update additional claim metadata.
  • Recalculate monthly inventory summaries when the claim month changes.
  • Refresh inventory count tracking after date changes.
  • Record the last updated user and timestamp.

Notes

  • The claim_id path parameter must be a valid integer.
  • Only the supplied fields are updated.
  • Additional request parameters are stored as claim metadata.
  • Changing the claim date may update monthly inventory records.
  • Requires Items/claim permission.

Permissions

Items/claim is needed

path Parameters
claim_id
required
integer
Example: 101

Unique identifier of the claim.

Request Body schema: application/json
required
date
string <date-time>

Updated claim date.

remarks
string

Updated remarks for the claim.

Responses

Request samples

Content type
application/json
{
  • "date": "2019-08-24T14:15:22Z",
  • "remarks": "string"
}

Response samples

Content type
{
  • "message": "string"
}

Delete claimed item

Removes an item from an existing claim.

The endpoint validates that the claim belongs to the authenticated application and that the specified item is part of the claim before removing it. Inventory counts, monthly inventory summaries, and stock calculations are automatically updated. If offer recalculation is requested, updated offer information is also returned.

Features

  • Remove an item from a claim.
  • Automatically update inventory counts.
  • Update monthly inventory statistics.
  • Update stock availability.
  • Recalculate applicable offers when requested.

Notes

  • The claim_id path parameter identifies the claim.
  • The item_id path parameter identifies the claimed item to remove.
  • The claim must belong to the authenticated application.
  • The item must already exist in the specified claim.
  • When the apply_offers request parameter is supplied, the response includes updated offer information.
  • Requires Items/claim permission.

Permissions

Items/claim is needed

path Parameters
claim_id
required
integer
Example: 1001

Unique identifier of the claim.

item_id
required
integer
Example: 101

Unique identifier of the claimed item.

query Parameters
apply_offers
boolean
Example: apply_offers=true

Recalculate applicable offers after removing the item.

Responses

Response samples

Content type
application/json
{
  • "old_quantity": 5
}

Update claimed item

Updates the quantity or damaged quantity of an item that has already been added to an inventory claim.

The endpoint recalculates inventory counts, updates monthly inventory statistics, and optionally recalculates applicable offers.

Features

  • Update claimed item quantity.
  • Update damaged quantity.
  • Automatically update inventory counts.
  • Automatically update monthly inventory statistics.
  • Recalculate applicable offers when requested.
  • Return the previous claimed quantities.

Notes

  • The claim_id and item_id path parameters identify the claimed item.
  • At least one of quantity or damaged_qty must be supplied.
  • Quantity and damaged quantity must be greater than zero.
  • Damaged quantity cannot exceed the total quantity.
  • The claimed item must already exist in the specified claim.
  • Users can update only claims belonging to their application.
  • Requires Items/claim permission.

Permissions

Items/claim is needed

path Parameters
claim_id
required
integer
Example: 101

Unique identifier of the claim.

item_id
required
integer
Example: 25

Unique identifier of the claimed item.

Request Body schema: application/json
required
apply_offers
boolean

Recalculate and return applicable offers.

damaged_qty
number

Updated damaged quantity.

quantity
number

Updated claimed quantity.

Responses

Request samples

Content type
application/json
{
  • "apply_offers": true,
  • "damaged_qty": 0,
  • "quantity": 0
}

Response samples

Content type
application/json
{
  • "offer": { },
  • "old_damaged_qty": 0,
  • "old_quantity": 0
}

Get claimed items

Retrieves the list of items associated with a specific inventory claim.

The response includes all claimed items along with their quantities and, when applicable, the combo item composition for items that are configured as combos.

Features

  • Retrieve all items associated with a claim.
  • Retrieve claimed quantities.
  • Retrieve combo item information.
  • Retrieve combo component details including quantity, item type and variant count.

Notes

  • The claim_id path parameter must be a valid integer.
  • Users can retrieve items only for claims belonging to their application.
  • The inventory application can retrieve claimed items for any application.
  • Anonymous users are not allowed to access this endpoint.
  • Requires Items/claim, Items/access, or Items/manage permission.

Permissions

Any of the following permissions are needed

  • Items/claim
  • Items/access
  • Items/manage
  • Denied for anonymous users (Users / Apps not registered in the settings)
path Parameters
claim_id
required
integer
Example: 101

Unique identifier of the claim.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add items to a claim

Adds, updates, or removes items in an existing inventory claim.

This endpoint manages the items associated with a claim. It supports adding new items, updating existing claimed quantities, and removing previously claimed items. Inventory counts, monthly inventory summaries, combo item quantities, and stock availability are updated automatically.

Features

  • Add items to an existing claim.
  • Update claimed item quantities.
  • Remove claimed items.
  • Record damaged quantities.
  • Update inventory counts automatically.
  • Update monthly inventory summaries.
  • Handle combo item inventory calculations.
  • Apply eligible offers when requested.
  • Generate low stock alerts for outward claims.

Notes

  • The claim_id path parameter must reference an existing claim.
  • The request body must include the items field.
  • Each item must include item_id and quantity.
  • quantity must be greater than zero unless the action is delete.
  • Supported actions are update and delete. If omitted, the quantity is added to the existing claimed quantity.
  • damaged_qty cannot exceed quantity.
  • All referenced items must exist.
  • Users can modify only claims belonging to their own application.
  • Requires Items/claim or Items/access permission.

Permissions

Any of the following permissions are needed

  • Items/claim
  • Items/access
path Parameters
claim_id
required
integer
Example: 101

Unique identifier of the claim.

Request Body schema: application/json
required
required
Array of objects

List of items to add, update, or remove.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "direction": "inward",
  • "items": [
    ],
  • "offer": {
    }
}

Get claims

Retrieves inventory claims belonging to the authenticated application.

This endpoint returns inward and outward inventory claims with support for field selection, filtering, sorting, and limiting the number of returned records.

Aggregate information such as the total number of claimed items, total quantity, and total damaged quantity can also be included.

Features

  • Retrieve inward and outward claims.
  • Select specific response fields.
  • Filter claims by supported fields.
  • Sort claims by date.
  • Limit the number of returned records.
  • Include aggregate claim statistics.

Notes

  • Returns only claims belonging to the authenticated application.
  • The fields parameter controls which fields are returned.
  • Aggregate fields (num_items, tot_qty, tot_dmgd) are calculated only when requested.
  • Only sorting by date is supported.
  • Invalid filters or unsupported sort fields return an error.
  • Requires Items/claim permission.

Permissions

Items/claim is needed

query Parameters
fields
string
Example: fields=id,direction,date,remarks

Comma-separated list of fields to return.

limit
integer
Example: limit=10

Maximum number of claims to return.

sort
string
Example: sort=date.desc

Sort by date using date.asc or date.desc.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new claim

Creates a new inward or outward inventory claim.

A claim records the movement of inventory into or out of an application. The endpoint creates the claim and can optionally add claimed items as part of the same request.

For outward claims, the request can optionally perform an availability check before creating the claim.

Features

  • Create inward and outward claims.
  • Automatically assign the current date when not provided.
  • Store claim remarks and additional details.
  • Add claimed items during claim creation.
  • Check item availability for outward claims.
  • Associate the claim with the authenticated application.

Notes

  • The direction field must be either inward or outward.
  • If date is omitted, the current date and time are used.
  • When items are supplied, they are automatically added to the newly created claim.
  • For outward claims, supplying the check parameter performs an availability check before the claim is created.
  • Requires Items/claim permission.

Permissions

Items/claim is needed

Request Body schema: application/json
required
date
string <date-time>

Claim date. Defaults to the current date and time.

details
object

Additional application-specific claim details.

direction
required
string
Enum: "inward" "outward"

Direction of the inventory claim.

items
Array of objects

Optional list of items to add to the claim.

remarks
string

Remarks associated with the claim.

Responses

Request samples

Content type
application/json
{
  • "date": "2019-08-24T14:15:22Z",
  • "details": { },
  • "direction": "inward",
  • "items": [
    ],
  • "remarks": "string"
}

Response samples

Content type
application/json
{
  • "direction": "inward",
  • "id": 101,
  • "items": [
    ],
  • "offer": {
    }
}

Register claim template

Registers or updates the claim templates for an application.

This endpoint stores the URL template and description template used when generating item claim information for an application. At least one of the templates must be supplied.

The registered templates are stored centrally and associated with the authenticated application.

Features

  • Register a URL template for item claims.
  • Register a description template for item claims.
  • Update existing claim templates.
  • Associate templates with the authenticated application.

Notes

  • At least one of url_template or description_template must be provided.
  • The application is identified from the authenticated integration request.
  • Templates are stored in Redis for fast retrieval.
  • This endpoint is intended for internal applications only.
  • Requires Items/claim permission.

Permissions

Items/claim is needed

  • Allowed for all internal applications
Request Body schema: application/json
required
description_template
string

Template used to generate claim descriptions.

url_template
string

Template used to generate claim URLs.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
{
  • "message": "string"
}

Rating

API related to Rating.

Get item ratings

Retrieves the rating summary for an item.

Ratings are aggregated across all variants of the same item and include the average rating, total number of ratings, and a distribution showing how many customers assigned each rating value.

Features

  • Retrieve the average item rating.
  • Retrieve the total number of ratings.
  • Retrieve rating distribution by rating value.
  • Aggregate ratings across all variants of the same item.

Notes

  • The item_id path parameter identifies the item.
  • If the item has no ratings, the response contains:
    • avg_rating as null
    • num_ratings as 0
    • an empty ratings object.
  • Rating statistics are shared across all variants of the same item.
  • Requires Items/access permission.

Permissions

Items/access is needed

path Parameters
item_id
required
integer
Example: 101

Unique identifier of the item.

Responses

Response samples

Content type
application/json
{
  • "avg_rating": 4.5,
  • "num_ratings": 18,
  • "ratings": {
    }
}

Add or update item rating

Creates, updates, or removes a customer's rating for an item.

Ratings are stored per customer and are automatically aggregated across all variants of the same item. When a rating is updated, the average rating and total number of ratings are recalculated and synchronized for every variant.

Internal applications may submit ratings on behalf of a customer by providing the customer_id parameter.

Features

  • Add a new item rating.
  • Update an existing customer rating.
  • Remove a rating by setting the rating value to 0.
  • Automatically recalculate the average rating.
  • Synchronize rating information across all item variants.

Notes

  • The item_id path parameter identifies the item to rate.
  • Authenticated customers rate items using their own customer account.
  • Internal applications must supply the customer_id parameter.
  • The rating parameter is mandatory.
  • Setting rating to 0 removes the customer's existing rating.
  • Ratings are shared across all variants of the same item.
  • Requires Items/access permission.

Permissions

Items/access is needed

path Parameters
item_id
required
integer
Example: 101

Unique identifier of the item.

query Parameters
rating
required
integer [ 0 .. 5 ]
Example: rating=5

Rating value. Specify 0 to remove the existing rating.

customer_id
integer
Example: customer_id=1001

Customer identifier. Required only for authenticated internal applications.

Responses

Response samples

Content type
application/json
{
  • "avg_rating": 4.6,
  • "num_ratings": 25
}

Stock

API related to Stock.

Get stock stats

Retrieves inventory stats based on the supplied filters.

This endpoint supports two modes:

  • Stats mode (default) returns summarized statistics for items, item types, and item properties.
  • Items mode (items parameter) returns detailed item statistics and optionally prepares data for report/download generation.

Range filters may be supplied to compare statistics across multiple periods.

Features

  • Retrieve item statistics.
  • Retrieve item type statistics.
  • Retrieve item property statistics.
  • Retrieve excluded and associated statistics.
  • Filter statistics using query parameters.
  • Compare multiple date or value ranges.
  • Generate data for downloadable reports.

Notes

  • When the items parameter is supplied, detailed item statistics are returned.
  • When the download parameter is supplied together with items, the response contains report generation metadata instead of stats.
  • Multiple comparison ranges may be specified using range.* query parameters.
  • Requires Items/stats permission.

Permissions

Items/stats is needed

query Parameters
items
string
Example: items=all

Returns detailed item statistics. Use excl to retrieve excluded items.

download
boolean
Example: download=true

Returns report metadata for generating downloadable statistics.

range.*
string
Example: range.*=2026-01-01;2026-01-31

Comparison range filter. Supports date and field-based ranges.

Responses

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "params": { },
  • "ranges": { }
}

Get stock summary

Retrieves a summarized inventory report grouped by item type.

The response contains the total positive and negative stock quantities along with their purchase and sale values for each item type. Stock values are calculated using the latest sale and purchase prices after applying any configured discounts.

Features

  • Retrieve stock summary grouped by item type.
  • Calculate positive and negative stock quantities.
  • Calculate total purchase value of available stock.
  • Calculate total sale value of available stock.
  • Use the latest sale and purchase prices.
  • Apply configured discounts while calculating stock values.

Notes

  • Only active item types and active items are included.
  • Inventory calculations use the global inventory (app_id = 0).
  • Purchase and sale values are computed using the latest prices after discount adjustments.
  • Requires Items/manage and Items/manage-purchase-price permissions.

Permissions

All of the following permissions are needed

  • Items/manage
  • Items/manage-purchase-price

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Template

API related to Template.

Get label templates

Retrieves all available label templates used for printing item labels.

The templates are read from the label template configuration file and returned as a JSON array. If no templates have been configured, an empty array is returned.

Features

  • Retrieve all configured label templates.
  • Returns the complete template definitions.
  • Returns an empty array when no templates exist.

Notes

  • Label templates are stored in the server configuration directory.
  • Requires one of the following permissions:
    • Items/manage
    • Items/access
    • Items/claim

Permissions

Any of the following permissions are needed

  • Items/manage
  • Items/access
  • Items/claim

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete label template

Deletes an existing label template used for item label printing.

The template is removed from the label template configuration file and its name is removed from the template registry stored in Redis.

Features

  • Delete an existing label template.
  • Remove the template from persistent storage.
  • Remove the template name from the Redis registry.

Notes

  • The name path parameter identifies the label template.
  • Template names are matched case-insensitively.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
name
required
string
Example: A4_40_LABEL

Name of the label template to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Create or update label template

Creates a new label template or updates an existing one.

To create a new template, specify _ as the templ_name path parameter. To update an existing template, specify the current template name.

A label template defines the layout used for printing item labels, including sheet dimensions, label size, DPI, and printable elements.

Features

  • Create a new label template.
  • Update an existing label template.
  • Rename an existing template.
  • Configure sheet and label dimensions.
  • Configure printable label elements.
  • Prevent duplicate template names.

Notes

  • Use _ as the templ_name to create a new template.
  • Creating a template requires all mandatory fields.
  • Updating a template allows partial updates.
  • Template names must be unique.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
templ_name
required
string
Example: A4_LABEL

Template name. Specify _ to create a new template.

Request Body schema: application/json
required
dpi
integer

Printing DPI.

elements
Array of objects

List of printable elements.

label
object

Label dimensions and layout.

name
string

Template name.

sheet
object

Sheet configuration.

Responses

Request samples

Content type
application/json
{
  • "dpi": 300,
  • "elements": [
    ],
  • "label": { },
  • "name": "A4_LABEL",
  • "sheet": { }
}

Response samples

Content type
{
  • "message": "string"
}

UOM

API related to UOM.

Delete UOM

Deletes an existing unit of measure (UOM).

The specified UOM is removed from the system if it exists.

Features

  • Delete a unit of measure.
  • Removes the UOM from the inventory configuration.

Notes

  • The uom_name path parameter identifies the UOM to delete.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
uom_name
required
string
Example: Kilogram

Name of the unit of measure to delete.

Responses

Response samples

Content type
{
  • "message": "string"
}

Update UOM

Updates an existing unit of measure (UOM).

You can update the UOM name, its type, or both. The unit type determines whether the UOM represents whole units or fractional units.

Features

  • Update the unit of measure name.
  • Update the unit of measure type.
  • Supports partial updates.

Notes

  • The uom_name path parameter identifies the UOM to update.
  • The uom_type must be either whole or fraction when provided.
  • At least one updatable field should be supplied.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
uom_name
required
string
Example: Kilogram

Name of the unit of measure to update.

Request Body schema: application/json
required
uom_name
string

New name for the unit of measure.

uom_type
string
Enum: "whole" "fraction"

Updated unit type.

Responses

Request samples

Content type
application/json
{
  • "uom_name": "Kilograms",
  • "uom_type": "fraction"
}

Response samples

Content type
{
  • "message": "string"
}

Get UOMs

Retrieves the list of configured units of measure (UOMs).

The endpoint supports filtering and sorting of results based on the available UOM fields.

Features

  • Retrieve all units of measure.
  • Filter results using supported query parameters.
  • Sort results by one or more fields.
  • Returns the UOM ID, name, and type.

Notes

  • Supported fields:
    • id
    • uom_name
    • uom_type
  • Sorting supports <field>.asc and <field>.desc.
  • Requires one of the following permissions:
    • Items/access
    • Items/manage
    • Items/manage-content

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
  • Items/manage-content
query Parameters
max
integer
Example: max=50

Maximum number of UOMs to return.

sort
string
Example: sort=uom_name.asc

Sort results using one or more fields separated by commas. Supported fields are id, uom_name, and uom_type.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create UOM

Creates a new unit of measure (UOM) that can be assigned to inventory items.

Each UOM must specify whether it represents whole units or fractional units. Duplicate UOM names are not allowed.

Features

  • Create a new unit of measure.
  • Support whole and fractional unit types.
  • Returns the ID of the newly created UOM.

Notes

  • The uom_type must be either whole or fraction.
  • Duplicate UOMs result in a conflict.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

Request Body schema: application/json
required
uom_name
required
string

Name of the unit of measure.

uom_type
required
string
Enum: "whole" "fraction"

Type of unit of measure.

Responses

Request samples

Content type
application/json
{
  • "uom_name": "Kilogram",
  • "uom_type": "fraction"
}

Response samples

Content type
application/json
{
  • "id": 12
}

Inventory Sharing

APIs for managing shared inventory relationships between items.

Inventory sharing allows multiple items or variants to share the same underlying stock, enabling centralized inventory tracking while maintaining separate item records. These endpoints support creating, updating, retrieving, and deleting inventory sharing configurations.

Create inventory sharing

Creates a new inventory sharing group by linking multiple items to a shared inventory.

A hidden parent inventory item is created automatically, and all selected items share the same inventory based on their configured ratios.

Features

  • Create a new inventory sharing group.
  • Assign multiple items to a shared inventory.
  • Configure opening stock for the shared inventory.
  • Configure a low stock threshold.
  • Configure the shared unit of measure.
  • Automatically calculate opening stock when not provided.

Notes

  • At least two items are required.
  • Every item in the request must exist.
  • Items already participating in another inventory sharing group cannot be included.
  • Combo items cannot participate in inventory sharing.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

Request Body schema: application/json
required
required
Array of objects >= 2 items

Items to include in the inventory sharing group.

name
string

Inventory sharing group name.

opening_stock
number <float>

Opening stock for the shared inventory. If omitted, it is calculated automatically.

stock_threshold
number <float>

Low stock threshold for the shared inventory.

uom
string

Unit of measure for the shared inventory.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "name": "Warehouse Inventory",
  • "opening_stock": 100,
  • "stock_threshold": 10,
  • "uom": "Piece"
}

Response samples

Content type
application/json
{
  • "id": 1001,
  • "name": "Warehouse Inventory",
  • "opening_stock": 100,
  • "stock": 98,
  • "uom": "Piece"
}

Delete inventory sharing

Deletes an inventory sharing configuration.

If the specified item is the inventory sharing parent, the entire inventory sharing group is removed. Otherwise, only the specified item is removed from the sharing group.

When only one shared item remains after removal, the inventory sharing group is automatically dissolved.

Features

  • Delete an entire inventory sharing group.
  • Remove a single item from an inventory sharing group.
  • Automatically dissolve the sharing group when only one item remains.
  • Remove associated inventory and monthly inventory records for the shared inventory parent when the sharing group is deleted.

Notes

  • The item_id path parameter may refer to either the inventory sharing parent or a participating item.
  • Returns 404 Not Found if the inventory sharing configuration does not exist.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
item_id
required
integer
Example: 1001

Identifier of the inventory sharing parent or participating item.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get inventory sharing

Retrieves the details of an inventory sharing group.

The response includes the shared inventory information along with all items participating in the inventory sharing group and their inventory sharing ratios.

Features

  • Retrieve inventory sharing group details.
  • Retrieve all items in the sharing group.
  • Retrieve inventory sharing ratios.
  • Retrieve item properties.
  • Retrieve shared inventory information, including stock, opening stock, stock threshold, and unit of measure.

Notes

  • The item_id path parameter identifies the inventory sharing parent.
  • Returns 404 Not Found if the inventory sharing group does not exist.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
item_id
required
integer
Example: 1001

Inventory sharing parent item identifier.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "name": "Warehouse Inventory",
  • "opening_stock": 100,
  • "stock": 98,
  • "stock_threshold": 10,
  • "uom": "Piece"
}

Update inventory sharing

Updates an existing inventory sharing configuration.

This endpoint can be used to update either the inventory sharing parent or an individual shared item.

Features

  • Update the inventory ratio of a shared item.
  • Update the shared opening stock.
  • Update the shared stock threshold.
  • Update the shared unit of measure.
  • Rename the inventory sharing group.
  • Automatically recalculate shared inventory when required.

Notes

  • If item_id refers to a shared item, only the ratio field can be updated.
  • If item_id refers to the inventory sharing parent, opening_stock, stock_threshold, uom, and name can be updated.
  • Updating the opening stock recalculates the shared inventory stock.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
item_id
required
integer
Example: 1001

Shared inventory parent ID or shared item ID.

Request Body schema: application/json
required
name
string

Updated inventory sharing group name.

opening_stock
number <float>

Updated opening stock for the shared inventory.

ratio
number <float>

Inventory sharing ratio for a shared item.

stock_threshold
number <float>

Updated low stock threshold.

uom
string

Updated unit of measure.

Responses

Request samples

Content type
application/json
{
  • "name": "Warehouse Inventory",
  • "opening_stock": 250,
  • "ratio": 1.5,
  • "stock_threshold": 20,
  • "uom": "Piece"
}

Response samples

Content type
application/json
{
  • "stock": 245
}

Add inventory sharing

Adds one or more items to an existing inventory sharing group.

Inventory sharing allows multiple items to share a common inventory pool managed by a parent inventory item. The parent inventory is updated with the supplied opening stock, stock threshold, and unit of measure when provided.

Features

  • Add items to an existing inventory sharing group.
  • Update the shared inventory opening stock.
  • Update the shared stock threshold.
  • Update the shared unit of measure.
  • Automatically recalculate the shared inventory stock.

Notes

  • The parent_id path parameter identifies the shared inventory parent.
  • Every item in the request must exist.
  • Items already participating in another inventory sharing group cannot be added.
  • Combo items cannot participate in inventory sharing.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
parent_id
required
integer
Example: 1001

Identifier of the inventory sharing parent.

Request Body schema: application/json
required
required
Array of objects

Items to be added to the inventory sharing group.

name
string

Shared inventory group name.

opening_stock
number <float>

Opening stock for the shared inventory.

stock_threshold
number <float>

Low stock threshold for the shared inventory.

uom
string

Unit of measure for the shared inventory.

Responses

Request samples

Content type
application/json
{
  • "items": [
    ],
  • "name": "Warehouse Inventory",
  • "opening_stock": 100,
  • "stock_threshold": 10,
  • "uom": "Piece"
}

Response samples

Content type
application/json
{
  • "id": 1001,
  • "name": "Warehouse Inventory",
  • "opening_stock": 100,
  • "stock": 98,
  • "uom": "Piece"
}

Offers

APIs for creating, managing, retrieving, validating, and deleting item offers and promotional plans.

These endpoints allow applications to:

  • Create promotional offers.
  • Update offer details and validity periods.
  • Retrieve offer information.
  • List available offers.
  • Delete existing offers.
  • Check applicable offers for a collection of items.

Delete offer

Deletes or deactivates an offer.

By default, the offer is permanently removed. If the deactivate query parameter is provided, the offer is marked as deleted and its validity period ends immediately instead of being removed.

Features

  • Permanently delete an offer.
  • Deactivate an offer without removing it.
  • Immediately expire a deactivated offer.

Notes

  • Supplying the deactivate query parameter performs a soft delete.
  • Without deactivate, the offer is permanently deleted.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
offer_id
required
integer
Example: 101

Identifier of the offer to delete.

query Parameters
deactivate
boolean
Example: deactivate=true

If present, the offer is deactivated instead of permanently deleted.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get offer details

Retrieves the complete details of one or more offers.

The response includes the offer information, validity period, and the complete offer plan with its target, reward, and matching criteria.

Features

  • Retrieve a single offer or multiple offers.
  • Returns the complete offer plan.
  • Includes target and reward conditions.
  • Includes matching criteria such as items, item types, variants, and properties.
  • Returns offer validity information.

Notes

  • Multiple offer IDs can be supplied as a comma-separated list.
  • Property identifiers are returned as property names when available.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
offer_id
required
string
Example: 101,102

Offer ID or a comma-separated list of offer IDs.

Responses

Response samples

Content type
application/json
[ ]

Update offer

Updates an existing offer.

You can modify the offer title, subtitle, validity period, or replace the entire offer plan. When a new plan is provided, the existing plan is removed and replaced after validation.

Features

  • Update the offer title.
  • Update the offer subtitle.
  • Update the offer validity period.
  • Replace the complete offer plan.
  • Validates the updated plan before saving.

Notes

  • Only the fields provided in the request are updated.
  • If plan is supplied, the existing plan is deleted and recreated.
  • valid_from must be earlier than valid_till.
  • All referenced items, item types, and properties must exist.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
offer_id
required
integer
Example: 101

Identifier of the offer to update.

Request Body schema: application/json
required
plan
Array of objects

New offer plan that replaces the existing plan.

sub_title
string

Updated offer subtitle.

title
string

Updated offer title.

valid_from
string <date-time>

Updated offer start date and time.

valid_till
string <date-time>

Updated offer expiry date and time.

Responses

Request samples

Content type
application/json
{
  • "plan": [
    ],
  • "sub_title": "Limited Time Offer",
  • "title": "Buy 2 Get 1 Free",
  • "valid_from": "2026-08-05T00:00:00Z",
  • "valid_till": "2026-08-31T23:59:59Z"
}

Response samples

Content type
{
  • "message": "string"
}

Get offers

Retrieves offers matching the specified filter criteria.

The endpoint supports filtering, sorting, limiting results, and filtering offers by their validity period.

Features

  • Retrieve all active offers.
  • Filter offers by ID, title, subtitle, and validity dates.
  • Sort results by offer ID or validity start date.
  • Limit the number of returned offers.
  • Optionally include deleted offers.

Notes

  • Deleted offers are excluded by default.
  • Sorting is supported only on id and valid_from.
  • Requires Items/access permission.

Permissions

Items/access is needed

query Parameters
id
integer
Example: id=101

Filter by offer ID.

title
string
Example: title=Buy 2 Get 1 Free

Filter by offer title.

sub_title
string
Example: sub_title=Weekend Special

Filter by offer subtitle.

valid_from
string <date-time>
Example: valid_from=2026-08-01T00:00:00Z

Return offers valid on or after this date.

valid_till
string <date-time>
Example: valid_till=2026-08-31T23:59:59Z

Return offers that remain valid on or after this date.

incl_deleted
boolean

Include deleted offers in the response.

sort
string
Example: sort=valid_from.desc

Sort results using id or valid_from.

limit
integer
Example: limit=20

Maximum number of offers to return.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create offer

Creates a new promotional offer.

An offer consists of one or more matching rules that define the target items and the corresponding reward. Offers can be configured using item, item type, variant, and item property criteria.

Features

  • Create a new promotional offer.
  • Configure offer validity period.
  • Define multiple matching rules.
  • Match items by item, type, variant, or property.
  • Configure target quantity or price.
  • Configure reward quantity, reward price, or discount.
  • Validate all referenced items, item types, and properties before creation.

Notes

  • title and plan are mandatory.
  • If valid_from is omitted, the current date and time is used.
  • valid_till must be later than valid_from.
  • Every plan entry must contain a match object.
  • Every plan entry must contain either a target or reward.
  • At least one target condition and one reward condition must exist across the complete offer.
  • All referenced item IDs, type IDs, and property names must exist.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

Request Body schema: application/json
required
required
Array of objects

List of offer rules.

sub_title
string

Optional offer subtitle.

title
required
string

Offer title.

valid_from
string <date-time>

Offer start date and time.

valid_till
string <date-time>

Offer expiry date and time.

Responses

Request samples

Content type
application/json
{
  • "plan": [
    ],
  • "sub_title": "Weekend Promotion",
  • "title": "Buy 2 Get 1 Free",
  • "valid_from": "2026-08-01T00:00:00",
  • "valid_till": "2026-08-31T23:59:59"
}

Response samples

Content type
application/json
{
  • "id": 15
}

Check offers

Evaluates the supplied items against all applicable offers and returns the best matching offers along with the resulting item list.

The endpoint can optionally evaluate offers for a specific date and enrich newly added reward items with additional item information or filter them based on stock availability.

Features

  • Evaluate applicable offers for a list of items.
  • Return the best matching offers.
  • Calculate reward items automatically.
  • Evaluate offers for a specific date.
  • Include additional fields for newly added reward items.
  • Optionally exclude reward items that are out of stock.

Notes

  • The request must contain an items collection.
  • If date is omitted, currently active offers are evaluated.
  • new_item.fields appends additional fields to generated reward items.
  • new_item.check_stock removes generated reward items that have no stock.
  • Requires Items/access permission.

Permissions

Items/access is needed

Request Body schema: application/json
required
date
string <date-time>

Evaluate offers active at the specified date and time.

items
required
Array of objects

Items to evaluate for offers.

new_item.check_stock
boolean

Exclude generated reward items that are out of stock.

new_item.fields
string

Comma-separated list of item fields to include for generated reward items.

Responses

Request samples

Content type
application/json
{
  • "date": "2026-08-05T10:30:00Z",
  • "items": [
    ],
  • "new_item.check_stock": true,
  • "new_item.fields": "name,code,price"
}

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "offers": [
    ]
}

Item Image

API related to item image.

Get face/back image

Retrieves the primary face or back image for an item.

This endpoint returns the designated face or back image without requiring the caller to know the actual image file name. If a dedicated back image has not yet been generated, it is automatically resolved from the item's image order when available.

Features

  • Retrieve the primary face image.
  • Retrieve the primary back image.
  • Automatically resolves the back image when needed.
  • Supports overriding the image type using the type query parameter.

Notes

  • The img_type path parameter is typically face or back.
  • If the type query parameter is supplied, it takes precedence over the path parameter.
  • Returns the image as binary content.
  • Requires Items/access permission.

Permissions

Items/access is needed

path Parameters
item_id
required
integer
Example: 101

Item identifier.

img_type
required
string
Example: face

Image type to retrieve.

query Parameters
type
string
Enum: "face" "back"
Example: type=back

Overrides the image type specified in the path.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get item image

Retrieves an image for the specified item.

The image is returned in the requested size. If the client supports WebP, a WebP image is returned when available; otherwise PNG or JPEG is returned.

Features

  • Retrieve an item image by name.
  • Supports multiple image sizes.
  • Automatically serves the best supported image format.
  • Supports WebP, PNG, and JPEG formats.

Notes

  • The item and image must exist.
  • The requested image size must be available.
  • The response is the image file itself.
  • Requires Items/access permission.

Permissions

Items/access is needed

path Parameters
item_id
required
integer
Example: 101

Identifier of the item.

img_name
required
string
Example: front.jpg

Image name.

query Parameters
size
string
Example: size=medium

Image size to retrieve.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get item media spec

Retrieves the media specification for an item.

The response contains the ordered list of images and videos associated with the item, including their URLs, descriptions, media type, and display order.

Features

  • Retrieve all images and videos assigned to an item.
  • Returns media in display order.
  • Includes image and video URLs.
  • Includes media descriptions when available.
  • Supports uploaded media and shared library media.

Notes

  • The item must exist.
  • Image URLs are returned in the src field.
  • Video URLs are returned in the video_src field.
  • Embedded videos return the original embed URL.
  • Requires Items/access, Items/manage, or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
  • Items/manage-content
path Parameters
item_id
required
integer
Example: 101

Identifier of the item.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upload item media

Uploads and manages images and videos associated with an item.

This endpoint supports uploading new images, videos, embedded videos, updating media descriptions, changing display order, synchronizing existing media, and linking media from the shared media library.

Features

  • Upload item images.
  • Upload item videos and video covers.
  • Add embedded video references.
  • Update media descriptions.
  • Reorder item media.
  • Synchronize existing media.
  • Reference media from the shared media library.
  • Automatically update item media references.

Notes

  • The request content type must be multipart/form-data.
  • The item must already exist.
  • Uploaded media must match the order specification when provided.
  • Library media references are validated before being linked.
  • The first image becomes the item's primary (face) image.
  • The second image becomes the item's secondary (back) image.
  • Requires Items/manage or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/manage
  • Items/manage-content
path Parameters
item_id
required
integer
Example: 101

Identifier of the item.

Request Body schema: multipart/form-data
required
object

Multipart form containing images, videos, media descriptions, and an optional order definition describing the media layout.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get item video

Retrieves a video associated with the specified item.

The response streams the original video file stored for the item.

Features

  • Retrieve a video by name.
  • Returns the original video file.
  • Supports both item-specific and shared library videos.

Notes

  • The item and video must exist.
  • The response is the video file itself.
  • Requires Items/access permission.

Permissions

Items/access is needed

path Parameters
item_id
required
integer
Example: 101

Identifier of the item.

video_name
required
string
Example: demo.mp4

Video file name.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get video cover

Retrieves the cover image associated with a video of the specified item.

The response returns the cover image file used as the video's thumbnail.

Features

  • Retrieve a video's cover image.
  • Returns the original cover image file.
  • Supports both item-specific and shared library videos.

Notes

  • The item, video, and cover image must exist.
  • The response is the image file itself.
  • Requires Items/access permission.

Permissions

Items/access is needed

path Parameters
item_id
required
integer
Example: 101

Identifier of the item.

video_name
required
string
Example: demo.mp4

Video file name.

cover_name
required
string
Example: cover.jpg

Video cover image file name.

Responses

Response samples

Content type
{
  • "message": "string"
}

Search media library

Searches the shared item media library.

This endpoint returns images and videos stored in the media library and supports filtering, sorting, field selection, and limiting the number of returned records.

Features

  • Search image and video resources.
  • Filter by media attributes.
  • Select only required response fields.
  • Sort search results.
  • Limit the number of returned records.

Notes

  • By default, both images and videos are returned.
  • If fields is omitted, the default fields are: id, name, num_refs, is_fav, and type.
  • Results are limited to 30 records by default.
  • Requires Items/manage or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/manage
  • Items/manage-content
query Parameters
fields
string
Example: fields=id,name,type,num_refs,is_fav

Comma-separated list of fields to return.

type
string
Example: type=image

Filter by media type.

title
string
Example: title=Banner

Filter by media title.

name
string
Example: name=banner

Filter by media name.

id
integer
Example: id=101

Filter by media resource ID.

is_fav
boolean
Example: is_fav=true

Return only favourite media.

max
integer
Example: max=20

Maximum number of records to return.

sort
string
Example: sort=date.desc

Sort expression in the format <field>.<asc|desc>.

Supported fields:

  • date
  • id
  • title
  • name
  • num_refs
  • is_fav
  • type

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upload media library

Uploads images and videos to the shared item media library.

Media uploaded through this endpoint can be reused by multiple items, avoiding duplicate uploads. Existing media can be replaced by specifying the force query parameter.

Features

  • Upload shared image resources.
  • Upload shared video resources.
  • Upload optional cover images for videos.
  • Replace existing media when force=true.

Notes

  • Request content type must be multipart/form-data.
  • Media names are stored in lowercase.
  • Media names must not exceed 64 characters.
  • Uploading an existing media without force=true returns 409 Conflict.
  • Requires Items/manage or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/manage
  • Items/manage-content
query Parameters
force
boolean
Example: force=true

Replace existing media if it already exists.

Request Body schema: multipart/form-data
required
image/<media_name>
string <binary>

Image file.

video/<media_name>
string <binary>

Video file.

video/<media_name>/cover/<cover_name>
string <binary>

Cover image for the uploaded video.

Responses

Response samples

Content type
application/json
{
  • "banner": 101,
  • "demo": 103,
  • "logo": 102
}

Get library image

Retrieves an image from the shared item media library.

The image is returned in the requested size. If the client supports WebP, a WebP image is returned when available; otherwise PNG or JPEG is returned.

Features

  • Retrieve an image from the shared media library.
  • Supports multiple image sizes.
  • Automatically serves the best supported image format.
  • Supports WebP, PNG, and JPEG formats.

Notes

  • The specified library image must exist.
  • The requested image size must be available.
  • The response is the image file itself.
  • Requires Items/access permission.

Permissions

Items/access is needed

path Parameters
img_name
required
string
Example: product_front

Library image name.

query Parameters
size
string
Example: size=medium

Image size to retrieve.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get library video cover

Retrieves the cover image for a video stored in the shared item media library.

This endpoint serves the thumbnail or poster image associated with a library video resource.

Features

  • Retrieve a shared library video cover image.
  • Returns the original stored cover image.
  • Accessible without referencing a specific item.

Notes

  • The video_name identifies the library video.
  • The cover_name identifies the cover image file.
  • Requires Items/access permission.

Permissions

Items/access is needed

path Parameters
video_name
required
string
Example: demo.mp4

Library video resource name.

cover_name
required
string
Example: cover.png

Cover image file name.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get library video

Retrieves a video from the shared item media library.

The response streams the original video file stored in the shared media library.

Features

  • Retrieve a video from the shared media library.
  • Returns the original video file.

Notes

  • The specified library video must exist.
  • The response is the video file itself.
  • Requires Items/access permission.

Permissions

Items/access is needed

path Parameters
video_name
required
string
Example: demo.mp4

Library video file name.

Responses

Response samples

Content type
{
  • "message": "string"
}

Delete media library

Deletes one or more resources from the shared item media library.

Media can be deleted by specifying either resource IDs or media file names. If a media resource is currently referenced by one or more items, deletion is blocked unless the force query parameter is supplied.

Features

  • Delete one or multiple media resources.
  • Delete using media resource IDs or file names.
  • Prevent accidental deletion of referenced media.
  • Force deletion of referenced media.

Notes

  • Specify either the media_files path parameter or the ids query parameter.
  • Do not provide both at the same time.
  • Use _ as the path parameter when deleting by IDs.
  • Requires Items/manage or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/manage
  • Items/manage-content
path Parameters
media_files
required
string
Example: banner,demo

Comma-separated media file names to delete.

Use _ when deleting by resource IDs.

query Parameters
ids
string
Example: ids=101,102

Comma-separated media resource IDs.

force
boolean
Example: force=true

Delete media even if it is referenced by items.

Responses

Response samples

Content type
{
  • "message": "string"
}

Delete type image

Deletes one or more images associated with an item type.

This endpoint removes a specific aspect-ratio image for an item type, or deletes all available type images when * is specified.

The item type can be identified using either its numeric ID or its type name.

Features

  • Delete a single type image.
  • Delete all type images using *.
  • Supports item type ID or type name.
  • Removes the stored image directory for the specified image(s).

Notes

  • Use the required aspect ratio (for example 1-1, 16-9) to delete a single image.
  • Use * to delete every image associated with the item type.
  • Returns 404 Not Found if the specified image does not exist.
  • Requires Items/manage or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/manage
  • Items/manage-content
path Parameters
required
integer or string
Example: 5

Item type ID or type name.

ar
required
string
Example: 1-1

Aspect ratio of the image to delete. Use * to delete all images for the item type.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get type image

Retrieves an image representing an item type.

The item type can be specified either by its numeric ID or by its name.

The endpoint first attempts to return an image uploaded specifically for the requested item type. If no matching type image exists, it automatically falls back to the primary (face) image of the latest item belonging to that type.

Features

  • Supports lookup by type ID or type name.
  • Returns a specific aspect ratio image.
  • Supports automatic aspect ratio selection using *.
  • Falls back to an item's primary image when no type image exists.
  • Returns the image as binary content.

Notes

  • Specify * as the aspect ratio to automatically use the first available type image.
  • If no type images are available, the latest item belonging to the type is used as the fallback image.
  • Images are served in the best supported format (WebP when supported, otherwise PNG or JPEG).
  • Requires Items/access permission.

Permissions

Items/access is needed

path Parameters
type_id
required
string
Example: 15

Item type ID or item type name.

ar
required
string
Examples:
  • * -
  • 16-9 -
  • 1-1 -

Aspect ratio of the requested image.

Use * to automatically return the first available type image.

query Parameters
size
string

Generated image size to return.

Responses

Response samples

Content type
{
  • "message": "string"
}

Get type image aspect ratios

Retrieves the list of available image aspect ratios for an item type.

The item type can be specified either by its numeric ID or by its name.

Each returned aspect ratio corresponds to an uploaded type image and can be used with the Get Type Image endpoint to retrieve that image.

Features

  • Supports lookup by type ID or type name.
  • Returns all available image aspect ratios for the type.
  • Returns an empty list when no type images have been uploaded.

Notes

  • The returned aspect ratios correspond to the directory names used to store type images(for example 1-1, 4-3, 16-9).
  • Requires Items/manage or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/manage
  • Items/manage-content
path Parameters
type_id
required
string
Example: 15

Item type ID or item type name.

Responses

Response samples

Content type
application/json
[
  • "1-1",
  • "4-3",
  • "16-9"
]

Upload type images

Uploads or updates images for an item type.

Images are uploaded using multipart/form-data, where each form field name represents the image aspect ratio (for example 1-1, 4-3, 16-9) and the field value contains the corresponding image file.

If an empty file is submitted for an existing aspect ratio, the corresponding type image is removed.

Features

  • Upload one or more type images in a single request.
  • Supports multiple aspect ratios.
  • Replaces existing images with newly uploaded ones.
  • Deletes an existing image when an empty file is supplied.
  • Automatically processes uploaded images into supported sizes and formats.

Notes

  • Request content type must be multipart/form-data.
  • Each form field name should be the desired aspect ratio.
  • Supported image formats depend on the image processing pipeline.
  • Requires Items/manage or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/manage
  • Items/manage-content
path Parameters
type_id
required
integer
Example: 15

Item type identifier.

Request Body schema: multipart/form-data
required
property name*
additional property
string <binary>

Responses

Request samples

Content type
multipart/form-data
{
  "1-1": "<image file>",
  "16-9": "<image file>",
  "4-3": "<image file>"
}

Response samples

Content type
{
  • "message": "string"
}

Item Desc

API related to item desc.

Delete description template

Deletes an existing item description template.

This endpoint removes the description template from the system and deletes its stored HTML content. The template search index entries are also removed after successful deletion.

A template cannot be deleted if it is currently referenced by any items.

Features

  • Delete an existing description template.
  • Remove stored template HTML file.
  • Remove template search index data.
  • Prevent deletion of templates used by items.

Notes

  • The template must exist before deletion.
  • Templates referenced by products cannot be deleted.
  • Requires Items/manage permission.

Permissions

Items/manage is needed

path Parameters
template_id
required
integer
Example: 25

Description template identifier.

Responses

Response samples

Content type
{
  • "message": "string"
}

Update description template

Updates an existing item description template.

This endpoint allows modifying the template title, template code, and HTML content. Only the fields provided in the request are updated.

When the HTML content is changed, the updated content is reprocessed and the search index is refreshed.

Features

  • Update description template title.
  • Update description template code.
  • Update HTML description content.
  • Refresh search index when HTML content changes.

Notes

  • At least one of title, html, or template_code must be provided.
  • Template code can contain only letters, numbers, hyphen (-), and underscore (_).
  • Template code cannot start with a hyphen.
  • Requires Items/manage or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/manage
  • Items/manage-content
path Parameters
template_id
required
integer
Example: 25

Description template identifier.

Request Body schema: application/json
required
non-empty
html
string

Updated HTML content of the template.

template_code
string

Updated unique template code. Allowed characters: A-Z, a-z, 0-9, hyphen, underscore.

title
string

Updated description template title.

Responses

Request samples

Content type
application/json
{
  • "html": "<h2>Updated Details</h2><p>New content</p>",
  • "template_code": "updated_product_specification",
  • "title": "Updated Product Specification"
}

Response samples

Content type
{
  • "message": "string"
}

Get description templates

Retrieves the list of available item description templates.

This endpoint returns reusable description templates that can be used when creating or updating item descriptions.

The response can be customized using filters, selected fields, sorting, and maximum result limits.

Features

  • List available description templates.
  • Filter templates by supported fields.
  • Select specific response fields.
  • Sort template results.
  • Limit the number of returned templates.

Notes

  • By default, the response includes:
    • Template ID.
    • Title.
    • Template code.
    • Number of item references.
    • Favourite status.
  • The API internally filters resources of type desc_templ.
  • Requires Items/access or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage-content
query Parameters
fields
string
Example: fields=id,title,template_code

Comma-separated list of fields to return.

Supported fields:

  • id
  • title
  • template_code
  • num_refs
  • is_fav
  • name
  • type
  • date
max
integer
Default: 30
Example: max=50

Maximum number of templates to return.

sort
string
Example: sort=date.desc

Sort field and order.

Supported sort fields:

  • title
  • id
  • template_code
  • date

Sort order:

  • asc
  • desc
title
string
Example: title=Specification

Filter templates by title.

template_code
string
Example: template_code=product_specification

Filter templates by template code.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create description template

Creates a new reusable description template for items.

A description template contains a title, unique template code, and HTML content. Once created, the template can be assigned to item descriptions.

After creating the template, the HTML content is processed and added to the search index.

Features

  • Create reusable item description templates.
  • Store custom HTML description content.
  • Assign a unique template code.
  • Update search index for the created template.

Notes

  • title, html, and template_code are mandatory.
  • Template code can contain only letters, numbers, hyphen (-), and underscore (_).
  • Template code cannot start with a hyphen.
  • Requires Items/manage or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/manage
  • Items/manage-content
Request Body schema: application/json
required
html
required
string

HTML content of the description template.

template_code
required
string

Unique identifier code for the template. Allowed characters: A-Z, a-z, 0-9, hyphen, underscore.

title
required
string

Description template title.

Responses

Request samples

Content type
application/json
{
  • "html": "<h2>Specifications</h2><p>Product details</p>",
  • "template_code": "product_specification",
  • "title": "Product Specification"
}

Response samples

Content type
application/json
{
  • "id": 25
}

Get description template details

Retrieves the details of a description template using its template code.

This endpoint returns the description template metadata and HTML content. It also returns the list of items that are using the template.

Features

  • Retrieve description template information using template code.
  • Returns template title, template code, and HTML content.
  • Returns items linked with the description template.
  • Supports pagination for fetching linked items using the next_item parameter.

Notes

  • The template_code path parameter identifies the description template.
  • A maximum of 30 linked items are returned per request.
  • When more items are available, next_item contains the last returned item ID, which can be used to fetch the next set of items.
  • When next_item query parameter is provided, only the item list pagination response is returned.
  • Requires Items/access or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage-content
path Parameters
template_code
required
string
Example: product_details

Description template code.

query Parameters
next_item
integer
Example: next_item=100

Fetch items after the specified item ID.

next_id
integer
Example: next_id=100

Last item ID used as the pagination reference.

Responses

Response samples

Content type
application/json
{
  • "html": "string",
  • "items": [
    ],
  • "next_item": 130,
  • "template_code": "product_details",
  • "title": "Product Description"
}

Get item description

Retrieves the description content configured for an item.

This endpoint returns all available descriptions associated with the item. Descriptions can contain either custom HTML content or references to description templates.

The API supports both the current description storage format and the legacy description format used by older item versions.

Features

  • Retrieve item description content.
  • Retrieve custom HTML descriptions.
  • Retrieve template-based descriptions.
  • Supports legacy description data fallback.

Notes

  • The item must exist before retrieving the description.
  • If no description is available, an empty array is returned.
  • Requires Items/access or Items/manage permission.

Permissions

Any of the following permissions are needed

  • Items/access
  • Items/manage
path Parameters
item_id
required
integer
Example: 101

Item identifier.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update item description

Updates the description content of an item.

The description can contain either custom HTML descriptions or predefined description templates. Existing descriptions are replaced with the new description data.

This endpoint also supports copying the updated description to other items using the dst query parameter.

Features

  • Update item description.
  • Add or update custom HTML content.
  • Attach description templates.
  • Remove old description entries that are not included in the update.
  • Synchronize description to multiple items.

Notes

  • description is mandatory.
  • The item must exist before updating the description.
  • dst can be used to copy the same description to other items.
  • Requires Items/manage or Items/manage-content permission.

Permissions

Any of the following permissions are needed

  • Items/manage
  • Items/manage-content
path Parameters
item_id
required
integer
Example: 101

Item identifier.

query Parameters
dst
string
Example: dst=102,103

Comma-separated item IDs where the same description should be copied.

Request Body schema: application/json
required
Array
html
string

Custom HTML description content.

template_code
string

Description template code.

template_id
integer

Existing description template ID.

title
string

Description title.

Responses

Request samples

Content type
application/json
[
  • [
    ]
]

Response samples

Content type
{
  • "message": "string"
}