List Products

GET/api/v2/public/products

The product catalogue for the organisation. Returns the product_number values every other endpoint uses to refer to a product. For stock levels use the store products stock endpoints.

Query ParametersExpand Collapse

barcode: optional string

page_size: optional string

page_start: optional string

product_number: optional array of string

store_no: optional string

ReturnsExpand Collapse

page_number: number

Current page number (1-based).

formatint64

page_size: number

Maximum number of records returned per page.

formatint32

total_record_count: number

Total number of records matching the query across all pages.

formatint64

records: optional array of ProductItem { barcode, carrier_item_quantity, edit_min_max_percentage, 74 more }

Collection of records for the current page.

barcode: string

Primary barcode for the product.

carrier_item_quantity: number

formatdouble

edit_min_max_percentage: number

How far store staff may move the minimum and maximum levels, as a percentage. Comes from the product’s category, not the product itself.

formatint32

price_compare_multiplier: number

Multiplier applied with price_compare_unit to work out the comparison price.

formatdouble

product_name: string

Display name of the product.

product_number: string

Unique product number.

shelf_label_quantity: number

Number of shelf labels to print.

formatint32

allow_decimal: optional boolean

true when the product can be counted in fractions, such as weighed goods.

attention_code: optional string

Attention code that flags the product for special handling.

average_weight: optional number

Average weight of one unit, for products sold by weight.

formatdouble

barcodes_array: optional string

All barcodes for the product, beyond the primary one.

base_unit_name: optional string

Name of the unit the product is counted in.

brand_code: optional string

Brand code in the source system.

brand_description: optional string

Brand name.

category_code: optional string

Category the product belongs to. Matches category_code on the categories endpoint.

color: optional string

Colour name, for products with variants.

color_code: optional string

Colour code, for products with variants.

countries_allowed: optional array of string

Countries where the product may be sold. Empty means all countries.

countries_not_allowed: optional array of string

Countries where the product may not be sold.

country_code: optional string

Country the product belongs to.

deprecation_date: optional string

Date the product stops being sold. Formatted yyyyMMdd.

formatdate-time

expiration_min_range: optional number

Number of days before expiry at which the product should be acted on.

formatint32

free_fields: optional array of object { sort_order, key, value }

Free key/value fields carried against the product.

sort_order: number

Order the field is shown in.

formatint32

key: optional string

Name of the free field.

value: optional string

Value of the free field.

general_ledger: optional string

General ledger account the product books to.

image_url: optional string

Link to the product image.

is_active: optional boolean

false when the product is no longer sold.

is_counted: optional boolean

true when the product is included in stock counts.

is_edit_min_max: optional boolean

true when store staff may change the minimum and maximum levels.

is_edit_replenishment: optional boolean

true when store staff may change the replenishment settings.

is_expiration: optional boolean

true when the product has an expiry date that has to be tracked.

is_order_manually: optional boolean

true when the product is ordered by hand instead of by replenishment.

is_promotion: optional boolean

true when the product is currently on promotion.

is_set: optional boolean

true when the product is a set made up of other products.

is_stock: optional boolean

true when stock is tracked for this product.

is_store_product: optional boolean

true when the product is ranged in the store the request was scoped to.

is_template: optional boolean

true when the product is a template rather than a sellable item.

margin_category: optional string

Margin category used for reporting.

moq: optional number

Minimum order quantity. Orders below this are not placed.

formatdouble

old_price: optional number

Previous sales price, kept so a price change can be shown.

formatdouble

price: optional number

Current sales price.

formatdouble

price_compare_unit: optional string

Unit the comparison price is expressed in, such as a litre or a kilo.

price_lines: optional string

product_details: optional string

Free text description of the product.

product_type: optional string

Type of product, used to drive handling in the app.

product_url: optional string

Link to the product page.

promo_stores_allowed: optional array of string

Store numbers where the promotion applies. Empty means all stores.

promo_stores_not_allowed: optional array of string

Store numbers where the promotion does not apply.

promotion: optional string

Promotion the product is part of.

promotion_price: optional number

Price while the product is on promotion.

formatdouble

promotion_week: optional string

Week the promotion runs in.

purchase_price: optional number

Price paid to the supplier.

formatdouble

purchase_unit_barcode: optional string

Barcode of the unit the product is ordered in.

purchase_unit_name: optional string

Name of the unit the product is ordered in.

purchase_unit_product_number: optional string

Product number of the purchase unit, when it differs from this product.

purchase_unit_quantity: optional number

How many base units are in one purchase unit.

formatdouble

referral_product_id: optional string

reset_store_stock: optional boolean

set_product: optional array of object { set_item_quantity, set_product_number }

The products that make up the set, with their quantities.

set_item_quantity: optional string

How many of that component the set contains.

set_product_number: optional string

Product number of a component in the set.

shelf_label: optional boolean

true when a shelf label should be printed for this product.

shelf_label_barcode: optional boolean

true when the shelf label shows the barcode.

shelf_label_layout: optional number

Layout used when printing a shelf label.

formatint32

shelf_label_price: optional boolean

true when the shelf label shows the price.

size: optional string

Size name, for products with variants.

size_code: optional string

Size code, for products with variants.

smallest_product_number: optional string

Product number of the smallest sellable unit, when this product is a larger pack.

smallest_quantity: optional number

How many of the smallest unit this product contains.

formatdouble

special_price: optional number

Temporary price that overrides the normal one while it applies.

formatdouble

stores_allowed: optional array of string

Store numbers where the product may be sold. Empty means all stores.

stores_not_allowed: optional array of string

Store numbers where the product may not be sold.

supplier_id: optional string

Supplier code. Matches supplier_code on the suppliers endpoint.

supplier_name: optional string

Supplier name.

supplier_product_number: optional string

The supplier’s own number for this product.

units: optional array of object { unit_quantity, unit_barcode, unit_name }

The units the product can be handled in, each with its own barcode and quantity.

unit_quantity: number

How many base units this unit contains.

formatdouble

unit_barcode: optional string

Barcode for this unit.

unit_name: optional string

Name of the unit.

variant_code: optional string

Code that identifies this specific variant.

variant_factor: optional number

formatdouble

variant_family: optional string

Code shared by all variants of the same product.

volume: optional string

Volume or content of the product, as text.

List Products

curl https://api.colleqtive.net/api/v2/public/products \
    -H "Authorization: $COLLEQTIVE_BEARER_TOKEN"

{
  "page_number": 0,
  "page_size": 0,
  "total_record_count": 0,
  "records": [
    {
      "barcode": "barcode",
      "carrier_item_quantity": 0,
      "edit_min_max_percentage": 0,
      "price_compare_multiplier": 0,
      "product_name": "product_name",
      "product_number": "product_number",
      "shelf_label_quantity": 0,
      "allow_decimal": true,
      "attention_code": "attention_code",
      "average_weight": 0,
      "barcodes_array": "barcodes_array",
      "base_unit_name": "base_unit_name",
      "brand_code": "brand_code",
      "brand_description": "brand_description",
      "category_code": "category_code",
      "color": "color",
      "color_code": "color_code",
      "countries_allowed": [
        "string"
      ],
      "countries_not_allowed": [
        "string"
      ],
      "country_code": "country_code",
      "deprecation_date": "2019-12-27T18:11:19.117Z",
      "expiration_min_range": 0,
      "free_fields": [
        {
          "sort_order": 0,
          "key": "key",
          "value": "value"
        }
      ],
      "general_ledger": "general_ledger",
      "image_url": "image_url",
      "is_active": true,
      "is_counted": true,
      "is_edit_min_max": true,
      "is_edit_replenishment": true,
      "is_expiration": true,
      "is_order_manually": true,
      "is_promotion": true,
      "is_set": true,
      "is_stock": true,
      "is_store_product": true,
      "is_template": true,
      "margin_category": "margin_category",
      "moq": 0,
      "old_price": 0,
      "price": 0,
      "price_compare_unit": "price_compare_unit",
      "price_lines": "price_lines",
      "product_details": "product_details",
      "product_type": "product_type",
      "product_url": "product_url",
      "promo_stores_allowed": [
        "string"
      ],
      "promo_stores_not_allowed": [
        "string"
      ],
      "promotion": "promotion",
      "promotion_price": 0,
      "promotion_week": "promotion_week",
      "purchase_price": 0,
      "purchase_unit_barcode": "purchase_unit_barcode",
      "purchase_unit_name": "purchase_unit_name",
      "purchase_unit_product_number": "purchase_unit_product_number",
      "purchase_unit_quantity": 0,
      "referral_product_id": "referral_product_id",
      "reset_store_stock": true,
      "set_product": [
        {
          "set_item_quantity": "set_item_quantity",
          "set_product_number": "set_product_number"
        }
      ],
      "shelf_label": true,
      "shelf_label_barcode": true,
      "shelf_label_layout": 0,
      "shelf_label_price": true,
      "size": "size",
      "size_code": "size_code",
      "smallest_product_number": "smallest_product_number",
      "smallest_quantity": 0,
      "special_price": 0,
      "stores_allowed": [
        "string"
      ],
      "stores_not_allowed": [
        "string"
      ],
      "supplier_id": "supplier_id",
      "supplier_name": "supplier_name",
      "supplier_product_number": "supplier_product_number",
      "units": [
        {
          "unit_quantity": 0,
          "unit_barcode": "unit_barcode",
          "unit_name": "unit_name"
        }
      ],
      "variant_code": "variant_code",
      "variant_factor": 0,
      "variant_family": "variant_family",
      "volume": "volume"
    }
  ]
}

{
  "code": 401,
  "status": "error",
  "message": "Authentication failed.",
  "error": "unauthorized",
  "error_description": "Authentication failed."
}

{
  "code": 500,
  "status": "fail",
  "message": "The request could not be processed.",
  "error": "internal_error",
  "error_description": "The request could not be processed."
}

Returns Examples

{
  "page_number": 0,
  "page_size": 0,
  "total_record_count": 0,
  "records": [
    {
      "barcode": "barcode",
      "carrier_item_quantity": 0,
      "edit_min_max_percentage": 0,
      "price_compare_multiplier": 0,
      "product_name": "product_name",
      "product_number": "product_number",
      "shelf_label_quantity": 0,
      "allow_decimal": true,
      "attention_code": "attention_code",
      "average_weight": 0,
      "barcodes_array": "barcodes_array",
      "base_unit_name": "base_unit_name",
      "brand_code": "brand_code",
      "brand_description": "brand_description",
      "category_code": "category_code",
      "color": "color",
      "color_code": "color_code",
      "countries_allowed": [
        "string"
      ],
      "countries_not_allowed": [
        "string"
      ],
      "country_code": "country_code",
      "deprecation_date": "2019-12-27T18:11:19.117Z",
      "expiration_min_range": 0,
      "free_fields": [
        {
          "sort_order": 0,
          "key": "key",
          "value": "value"
        }
      ],
      "general_ledger": "general_ledger",
      "image_url": "image_url",
      "is_active": true,
      "is_counted": true,
      "is_edit_min_max": true,
      "is_edit_replenishment": true,
      "is_expiration": true,
      "is_order_manually": true,
      "is_promotion": true,
      "is_set": true,
      "is_stock": true,
      "is_store_product": true,
      "is_template": true,
      "margin_category": "margin_category",
      "moq": 0,
      "old_price": 0,
      "price": 0,
      "price_compare_unit": "price_compare_unit",
      "price_lines": "price_lines",
      "product_details": "product_details",
      "product_type": "product_type",
      "product_url": "product_url",
      "promo_stores_allowed": [
        "string"
      ],
      "promo_stores_not_allowed": [
        "string"
      ],
      "promotion": "promotion",
      "promotion_price": 0,
      "promotion_week": "promotion_week",
      "purchase_price": 0,
      "purchase_unit_barcode": "purchase_unit_barcode",
      "purchase_unit_name": "purchase_unit_name",
      "purchase_unit_product_number": "purchase_unit_product_number",
      "purchase_unit_quantity": 0,
      "referral_product_id": "referral_product_id",
      "reset_store_stock": true,
      "set_product": [
        {
          "set_item_quantity": "set_item_quantity",
          "set_product_number": "set_product_number"
        }
      ],
      "shelf_label": true,
      "shelf_label_barcode": true,
      "shelf_label_layout": 0,
      "shelf_label_price": true,
      "size": "size",
      "size_code": "size_code",
      "smallest_product_number": "smallest_product_number",
      "smallest_quantity": 0,
      "special_price": 0,
      "stores_allowed": [
        "string"
      ],
      "stores_not_allowed": [
        "string"
      ],
      "supplier_id": "supplier_id",
      "supplier_name": "supplier_name",
      "supplier_product_number": "supplier_product_number",
      "units": [
        {
          "unit_quantity": 0,
          "unit_barcode": "unit_barcode",
          "unit_name": "unit_name"
        }
      ],
      "variant_code": "variant_code",
      "variant_factor": 0,
      "variant_family": "variant_family",
      "volume": "volume"
    }
  ]
}

{
  "code": 401,
  "status": "error",
  "message": "Authentication failed.",
  "error": "unauthorized",
  "error_description": "Authentication failed."
}

{
  "code": 500,
  "status": "fail",
  "message": "The request could not be processed.",
  "error": "internal_error",
  "error_description": "The request could not be processed."
}