Index | Conventions

api/v1/stock

Path: api/v1/stock

This API is JSON:API compliant.

This endpoint supports the following methods:
GET

This endpoint requires an OAuth bearer token, and returns errors in a standard shape. See API Conventions for authentication, error responses and paging, which apply to every endpoint.

The resource type for this endpoint is Stock
The identifier is stockno

Relationships

A relationship links this Stock to another resource. By default only the related resource's type and id are returned. Relationships marked Includable can be embedded in the response via the include query parameter (see Includes below). To set or change a relationship, send a resource identifier (type and id) for it. Postable means the relationship can be set when creating the resource (POST); Patchable means it can be changed when updating an existing resource (PATCH). Some relationships are Postable but not Patchable — they can be set at creation but not changed afterwards. A value sent for a relationship that is not Postable/Patchable in that context is not applied.

NotePostable and Patchable describe what the API surface accepts. Whether a particular change is permitted also depends on the resource's current state and your permissions, which Jim2 enforces — a change that is not allowed is rejected with an error response (see the Conventions page).
RelationshipTypeReturnsIncludablePostablePatchable
alternateStockStockobject
locationsStockLocationsobject
manufacturingItemItemobject
parentStockStockobject
priceLevelsPriceLevelsobject
serviceItemItemobject
supersededByStockobject

Attributes

The Stock resource type attributes are as follows:

AttributeTypeDescription
activebooleanWhether the stock item is active.
allowPriceOverridebooleanWhether the price may be overridden on a transaction.
avgCOGSnumberThe average cost of goods sold (COGS).
avgCostnumberThe average cost.
avgPOCOGSnumberThe average purchase-order cost of goods sold (COGS).
buyobjectThe buy tax code and decimal places for the stock item.
See the buy section below.
codestringThe stock code.
comissionsobjectThe commission settings for the stock item (exclude, floor, percent, extra).
See the comissions section below.
dangerousGoodsbooleanWhether the item is classified as dangerous goods.
descriptionstringThe stock description.
detailedDescstringThe detailed (long) description.
dimensionsobjectThe stock item's weight and dimensions (weight, width, height, depth).
See the dimensions section below.
discountIsPercentageOfPricebooleanWhether the discount is treated as a percentage of price.
excludeAttributesInProcurementbooleanWhether stock attributes are excluded when procuring the item.
floorCostMarkupnumberThe floor cost markup.
gLGroupCodestringThe stock GL group name.
groupsarray of objectThe groups the stock item belongs to.
See the groups section below.
gTINumberstringThe GTIN (Global Trade Item Number).
hideOnInvoicebooleanWhether the item is hidden on the invoice.
labourContentnumberThe labour content of the stock item.
lastCOGSnumberThe last cost of goods sold (COGS).
lastCostnumberThe last cost recorded for the stock item.
lastPOCOGSnumberThe last purchase-order cost of goods sold (COGS).
listPriceExclnumberThe recommended retail price, excluding tax.
listPriceInclnumberThe recommended retail price, including tax.
macroDescstringThe macro description.
manufacturePartNumberstringThe manufacturer part number.
manufacturingCostnumberThe manufacturing cost.
manufacturingTypestringThe manufacturing type: SingleLevel / MultiLevel, or null if the item is not manufactured.
maxCOGSnumberThe maximum cost of goods sold (COGS).
measurearray of objectThe units of measure defined for the stock item (unit, qty, description, barcode).
See the measure section below.
procurementobjectThe procurement / reorder settings for the stock item.
See the procurement section below.
publishPriceTostringWhere the price is published: Price List & Web / Price List / Web / Don't Publish.
qtyDecimalPlacesintegerThe number of decimal places used for quantities of this item.
rateMultipliernumberThe rate multiplier applied to the stock item.
roundPriceUpToNearestCentsintegerRound the calculated price up to the nearest number of cents.
sellobjectThe sell tax code and decimal places for the stock item.
See the sell section below.
serialNostringWhen serial numbers are captured for the item: On Purchase / On Sell, or null if not serialised.
serviceStockbooleanWhether the item is a service item.
shortDescstringThe short description.
summaryKitbooleanWhether the kit is summarised (a summary kit).
typestringThe stock type: Depleting / Non Depleting / Labour / Applies / Journal / Special / Virtual, or a kit type (Dynamic Kitting / Static Kitting / Packaging).
warrantyDescstringThe warranty description.
warrantyMonthsNullable`1The warranty period in months.

buy

Attributes of the buy object.

AttributeTypeDescription
decimalPlacesintegerThe number of decimal places.
taxCodestringThe tax code.

comissions

Attributes of the comissions object.

AttributeTypeDescription
excludebooleanWhether the item is excluded from commission.
extranumberThe extra commission amount.
floornumberThe commission floor amount.
percentnumberThe commission percentage.

dimensions

Attributes of the dimensions object.

AttributeTypeDescription
depthnumberThe depth of the item.
heightnumberThe height of the item.
weightnumberThe weight of the item.
widthnumberThe width of the item.

groups

Attributes of each element in the groups array.

AttributeTypeDescription
idintegerThe group's unique identifier.
namestringThe group's name.
typestringThe group's type.

measure

Attributes of each element in the measure array.

AttributeTypeDescription
barcodestringThe barcode for this unit of measure.
qtynumberThe quantity of the base unit this unit of measure represents.
unitstringThe unit of measure code.
unitDescstringThe unit of measure description.

procurement

Attributes of the procurement object.

AttributeTypeDescription
addExtraPercentNullable`1The extra percentage to add when reordering.
dailyAvgSoldPerDayBasedOnstringHow the daily average sold per day is calculated: Last / Current month last year.
dailyAvgSoldPerDayBasedOnDaysNullable`1The number of days the daily average sold per day is based on.
minQtyPerLocationMethodstringHow the minimum quantity per location is determined: None / Calculated.
reorderQtynumberThe reorder quantity.

sell

Attributes of the sell object.

AttributeTypeDescription
decimalPlacesintegerThe number of decimal places.
taxCodestringThe tax code.

Example GET (Return using filter)

Path: api/v1/stock?filter[isSerialOnSell]=True&filter[stockGLGroup]=STOCK&filter[lastModified][-gt]2025-01-12T00%3A00%3A00%2B00%3A00

Filtering

For more information see Resource Filtering.

Stock Filter uses list technology to retreive data. Names should match those on the list screen in Jim List Help.

The following fields can be used to filter by.
FieldTypeComment
barCodeTextSearch by barcode on Unit 1
dateInDateTime
dateSearchTypeTextWhat Date to search for. Values can be 'Date Sold', 'Date Purchased', 'Date Moved', 'Date not Sold'
groupsTextComma separated list of Stock Group Ids
includeDetailedDescBoolSearch 'StockDesc' in all detailed descriptions
isActiveBoolIs the stock Active
isAttributesNotRequiredBoolThe stock does not use Attributes
isAttributesOnPurchaseBoolThe stock uses Attributes on Purchase
isAttributesOnSellBoolThe stock uses Attributes on Sell
isBuyStockBoolI buy this stock
isDangerousGoodsBoolIs the stock flagged as dangerous
isManufacturingStockBoolI manufacture this stock
isSellStockBoolI sell this stock
isSerialNotRequiredBoolThe stock does not use Serial#
isSerialOnPurchaseBoolThe stock uses Serial# on purchase
isSerialOnSellBoolThe stock uses Serial# on sell
isServiceStockBoolThis is a Service stock
labourContentTextSearch by Labour content amount
lastModifiedDateTime
parentStock.idIntAll stock that have this stockId as parent
promoIdIntReturns stock on the specified promoId
publishPriceTextMatches the Publish Price to
stockCodeTextSearch by Stock Code
stockDescTextSearch by Stock Description
stockGLGroupTextMatches the stock GL Group Name
StockLocationCodeTextIt is in stock in the specified location
stockTypeTextThe Type of the Stock
weightTextSearch by weight

Response:

This example shows the maximum set of fields the endpoint can return, all populated. A real response only contains the data that applies to that record, so fields that are empty or not relevant are omitted — do not assume every field shown here will be present in every response.

This is a list. To keep the example readable, only the first item below is written out; the later items have been trimmed down in this documentation. In a real response each item comes back with the data applicable to that record (as described above).

Side-loading related resources with the include query parameter is not supported on list endpoints: an include parameter is ignored here and no included section is returned. To retrieve a related resource, request it directly using the id shown in each item's relationships, or use the single-resource (get by id) endpoint, which does support include.

{
  "data": [
    {
      "id": "53",
      "type": "Stock",
      "attributes": {
        "code": "PSU.X200",
        "description": "Replacement power supply for X200 controller",
        "type": "Depleting",
        "serialNo": "On Sell",
        "active": true,
        "gLGroupCode": "STOCK",
        "labourContent": 0.0000,
        "manufacturingCost": 42.5000,
        "buy": {
          "taxCode": "GST",
          "decimalPlaces": 4
        },
        "sell": {
          "taxCode": "GST",
          "decimalPlaces": 2
        },
        "listPriceExcl": 99.0000,
        "listPriceIncl": 108.9000,
        "dimensions": {
          "weight": 1.2500,
          "width": 15.0000,
          "height": 5.0000,
          "depth": 20.0000
        },
        "procurement": {
          "minQtyPerLocationMethod": "Calculated",
          "dailyAvgSoldPerDayBasedOn": "Last",
          "dailyAvgSoldPerDayBasedOnDays": 90,
          "addExtraPercent": 10,
          "reorderQty": 25.0000
        },
        "measure": [
          {
            "unit": "EACH",
            "qty": 1.0000,
            "unitDesc": "Each",
            "barcode": "9312345678900"
          },
          {
            "unit": "BOX",
            "qty": 10.0000,
            "unitDesc": "Box of 10",
            "barcode": "9312345678917"
          }
        ],
        "qtyDecimalPlaces": 4,
        "warrantyMonths": 12,
        "manufacturingType": "SingleLevel",
        "serviceStock": false,
        "macroDesc": "X200 PSU",
        "hideOnInvoice": false,
        "excludeAttributesInProcurement": false,
        "publishPriceTo": "Price List & Web",
        "roundPriceUpToNearestCents": 5,
        "rateMultiplier": 1.0000,
        "summaryKit": false,
        "floorCostMarkup": 15.0000,
        "manufacturePartNumber": "X200-PSU-A",
        "gTINumber": "09312345678900",
        "shortDesc": "X200 Power Supply",
        "detailedDesc": "Regulated 24V power supply unit for the X200 controller range.",
        "warrantyDesc": "12 month return-to-base warranty.",
        "allowPriceOverride": true,
        "discountIsPercentageOfPrice": true,
        "dangerousGoods": false,
        "comissions": {
          "exclude": false,
          "floor": 5.0000,
          "percent": 7.5000,
          "extra": 2.0000
        },
        "lastCost": 42.5000,
        "lastCOGS": 43.1000,
        "maxCOGS": 45.0000,
        "avgCost": 42.8000,
        "avgCOGS": 43.0500,
        "lastPOCOGS": 42.5000,
        "avgPOCOGS": 42.7500,
        "groups": [
          {
            "type": "Category",
            "id": 3,
            "name": "Power Supplies"
          }
        ]
      },
      "relationships": {
        "supersededBy": { "data": { "type": "Stock", "id": "54" } },
        "alternateStock": { "data": { "type": "Stock", "id": "55" } },
        "parentStock": { "data": { "type": "Stock", "id": "50" } },
        "serviceItem": { "data": { "type": "Stock", "id": "61" } },
        "manufacturingItem": { "data": { "type": "Stock", "id": "62" } },
        "locations": {
          "data": [
            { "type": "StockLocations", "id": "53-1" },
            { "type": "StockLocations", "id": "53-2" }
          ]
        },
        "priceLevels": {
          "data": [
            { "type": "PriceLevels", "id": "53-129" },
            { "type": "PriceLevels", "id": "53-130" }
          ]
        }
      },
      "links": {
        "self": "/api/v1/stock/53"
      }
    },
    {
      "id": "70",
      "type": "Stock",
      "attributes": {
        "code": "CALKIT.C50",
        "description": "Calibration kit for C50 bench"
      }
    }
  ]
}