This API is in beta. Endpoints and response shapes may change before stable release.

Products

A product represents an agricultural input — a chemical, fertiliser, seed, or other consumable. Products belong to an organisation and are referenced by receipt line items and returns.

ℹ Requires a Shed subscription on the target organisation. Requests to organisations without an active Shed entitlement return 403.

The product object

Field Type Mutability Notes
id uuid system
organisation_id uuid system
name string system Product name.
category string system Product category.
subcategory string system Product subcategory. Only present when category is "input".
unit string system Base unit for this product (e.g. l, kg).
external_id string system Optional identifier from an external system.
hazardous boolean system Whether the product is flagged as hazardous.
registration string system Optional registration or permit number.
density_value decimal string system Density value. Null unless the product is volume-based and has a density configured.
density_unit string system Density unit (e.g. kg/l). Null unless density_value is set.
archived_at iso8601 system When the product was archived, or null if active.
inserted_at iso8601 system
updated_at iso8601 system

List products

GET /api/shed/organisations/:org_id/products

By default, returns only active (non-archived) products. Pass include_archived=true to include archived products.

Parameter Type Required Description
include_archived boolean — Include archived (inactive) products. Defaults to false.
updated_after iso8601 — Return only products updated after this timestamp.
page integer — Page number. Defaults to 1.
page_size integer — Results per page. Defaults to 50, maximum 200.
200 
{
  "data": [
    {
      "id": "<uuid>",
      "organisation_id": "<uuid>",
      "name": "<string>",
      "category": "<string>",
      "subcategory": "<string>",
      "unit": "<string>",
      "external_id": "<string>",
      "hazardous": "<boolean>",
      "registration": "<string>",
      "density_value": "<decimal string>",
      "density_unit": "<string>",
      "archived_at": "<iso8601>",
      "inserted_at": "<iso8601>",
      "updated_at": "<iso8601>"
    }
  ],
  "meta": {
    "page": "<integer>",
    "page_size": "<integer>",
    "total_count": "<integer>",
    "total_pages": "<integer>"
  }
}

Get a product

GET /api/shed/products/:id
200 
{
  "id": "<uuid>",
  "organisation_id": "<uuid>",
  "name": "<string>",
  "category": "<string>",
  "subcategory": "<string>",
  "unit": "<string>",
  "external_id": "<string>",
  "hazardous": "<boolean>",
  "registration": "<string>",
  "density_value": "<decimal string>",
  "density_unit": "<string>",
  "archived_at": "<iso8601>",
  "inserted_at": "<iso8601>",
  "updated_at": "<iso8601>"
}

List deleted products

GET /api/shed/organisations/:org_id/products/deleted
Parameter Type Required Description
deleted_after iso8601 — Return only records deleted after this timestamp.
Deletion record
Field Type Mutability Notes
id uuid optional The ID of the deleted product.
deleted_at iso8601 optional When the record was deleted.
200 
{
  "data": [
    {"id": "<uuid>", "deleted_at": "<iso8601>"}
  ]
}

Categories

Every product belongs to one of six categories. The category determines which unit types are valid for that product.

Value Description Allowed unit types Notes
input Input volume, weight, count Supports an optional subcategory field (e.g. herbicide, fertiliser). See Subcategories below.
feed Feed & Supplements volume, weight, count
fuel Fuel & Oil volume, weight
part Parts count Unit is always each.
seed Seed weight, count, custom Custom unit is bag.
vet Veterinary volume, weight, count

Subcategories

Products with category: "input" may carry a subcategory field. The following values are supported:

Value Description
adjuvant Adjuvant
antimicrobial Antimicrobial
attractant Attractant
biological_control Biological Control
cleaner Cleaner
defoliant Defoliant
fertiliser Fertiliser
fumigant Fumigant
fungicide Fungicide
herbicide Herbicide
inoculant Inoculant
insect_growth_regulator Insect Growth Regulator
insecticide Insecticide
mating_disruptant Mating Disruptant
miticide Miticide
molluscicide Molluscicide
nematicide Nematicide
plant_amendment Plant Amendment
plant_growth_regulator Plant Growth Regulator
post_harvest Post Harvest
repellent Repellent
rodenticide Rodenticide
seed_treatment Seed Treatment
soil_amendment Soil Amendment
stress_protectant Stress Protectant
vertebrate_toxic_agent Vertebrate Toxic Agent

Units

The unit field holds the symbol string for the product's base unit (e.g. "l", "kg", "each"). Which units are valid depends on the product's category — see the table above.

Volume

Valid for: input, feed, fuel, vet

Symbol Unit System
ml Millilitre Metric
l Litre Metric
m3 Cubic metre Metric
ML Megalitre Metric
fl oz Fluid ounce US Imperial
pt Pint US Imperial
qt Quart US Imperial
gal Gallon US Imperial

Weight

Valid for: input, feed, fuel, seed, vet

Symbol Unit System
g Gram Metric
kg Kilogram Metric
t Tonne Metric
oz Ounce US Imperial
lb Pound US Imperial
ton Ton US Imperial

Count

Valid for: input, feed, part, seed, vet

Symbol Unit System
each Each —

Custom

Valid for: seed

Symbol Unit System
bag Bag —

Density

Liquid products may carry optional density_value and density_unit fields. These are used internally for unit conversions (e.g. receipting a liquid product by weight) and are informational only via the API.

Symbol Unit System
g/cm3 Grams per cubic centimetre Metric
kg/l Kilograms per litre Metric
lb/gal Pounds per gallon US Imperial