FarmReady API Reference

Returns

A return records the return of a product to a supplier from a storage location. Returns are simpler than receipts — they have no line items.

ℹ Requires a Shed subscription on the target organisation.

The return object

Field	Type	Mutability	Notes
id	uuid	system
organisation_id	uuid	system
sequence	string	system	Sequential identifier (RET-XXXXXXXX).
storage_id	uuid	required	Storage location the product is being returned from.
product_id	uuid	required	Product being returned.
returned_at	iso8601	required	Date and time of the return.
supplier	string	required	Supplier the product is being returned to.
amount_value	decimal string	required	Quantity being returned.
amount_unit	string	required	Unit for the amount (e.g. l, kg).
notes	string	optional	Optional notes.
reference	string	optional	Optional reference number.
inserted_at	iso8601	system
updated_at	iso8601	system

List returns

GET /api/shed/organisations/:org_id/returns

Parameter	Type	Required	Description
updated_after	iso8601	—	Return only records updated after this timestamp.
page	integer	—	Page number. Defaults to 1.
page_size	integer	—	Results per page. Defaults to 50, maximum 200.
include	string	—	Comma-separated list of related resources to sideload. Accepted values: product, storage.

200

{
  "data": [
    {
      "id": "<uuid>",
      "organisation_id": "<uuid>",
      "sequence": "<string>",
      "storage_id": "<uuid>",
      "product_id": "<uuid>",
      "returned_at": "<iso8601>",
      "supplier": "<string>",
      "amount_value": "<decimal string>",
      "amount_unit": "<string>",
      "notes": "<string>",
      "reference": "<string>",
      "inserted_at": "<iso8601>",
      "updated_at": "<iso8601>"
    }
  ],
  "meta": {
    "page": "<integer>",
    "page_size": "<integer>",
    "total_count": "<integer>",
    "total_pages": "<integer>"
  }
}

200 200 with ?include=product

{
  "data": [...],
  "meta": {...},
  "included": {
    "products": {
      "<uuid>": {
        "id": "<uuid>",
        "organisation_id": "<uuid>",
        "name": "<string>",
        "inserted_at": "<iso8601>",
        "updated_at": "<iso8601>"
      }
    }
  }
}

Get a return

GET /api/shed/returns/:id

Parameter	Type	Required	Description
include	string	—	Comma-separated list of related resources to sideload. Accepted values: product, storage.

200

{
  "id": "<uuid>",
  "organisation_id": "<uuid>",
  "sequence": "<string>",
  "storage_id": "<uuid>",
  "product_id": "<uuid>",
  "returned_at": "<iso8601>",
  "supplier": "<string>",
  "amount_value": "<decimal string>",
  "amount_unit": "<string>",
  "notes": "<string>",
  "reference": "<string>",
  "inserted_at": "<iso8601>",
  "updated_at": "<iso8601>"
}

200 200 with ?include=product,storage

{
  "id": "<uuid>",
  "organisation_id": "<uuid>",
  "sequence": "<string>",
  "storage_id": "<uuid>",
  "product_id": "<uuid>",
  "returned_at": "<iso8601>",
  "supplier": "<string>",
  "amount_value": "<decimal string>",
  "amount_unit": "<string>",
  "notes": "<string>",
  "reference": "<string>",
  "inserted_at": "<iso8601>",
  "updated_at": "<iso8601>",
  "included": {
    "products": {
      "<uuid>": {
        "id": "<uuid>",
        "organisation_id": "<uuid>",
        "name": "<string>",
        "inserted_at": "<iso8601>",
        "updated_at": "<iso8601>"
      }
    },
    "storages": {
      "<uuid>": {
        "id": "<uuid>",
        "organisation_id": "<uuid>",
        "name": "<string>",
        "locked_at": "<iso8601>",
        "inserted_at": "<iso8601>",
        "updated_at": "<iso8601>"
      }
    }
  }
}

Create a return

POST /api/shed/organisations/:org_id/returns

Request body
Field	Type	Mutability	Notes
storage_id	uuid	required	Must belong to the organisation.
product_id	uuid	required	Must belong to the organisation.
returned_at	iso8601	required
supplier	string	required
amount_value	decimal string	required
amount_unit	string	required	e.g. l, kg
notes	string	optional
reference	string	optional

201

{
  "id": "<uuid>",
  "organisation_id": "<uuid>",
  "sequence": "<string>",
  "storage_id": "<uuid>",
  "product_id": "<uuid>",
  "returned_at": "<iso8601>",
  "supplier": "<string>",
  "amount_value": "<decimal string>",
  "amount_unit": "<string>",
  "notes": "<string>",
  "reference": "<string>",
  "inserted_at": "<iso8601>",
  "updated_at": "<iso8601>"
}

Update a return

PATCH /api/shed/organisations/:org_id/returns/:id

200

{
  "id": "<uuid>",
  "organisation_id": "<uuid>",
  "sequence": "<string>",
  "storage_id": "<uuid>",
  "product_id": "<uuid>",
  "returned_at": "<iso8601>",
  "supplier": "<string>",
  "amount_value": "<decimal string>",
  "amount_unit": "<string>",
  "notes": "<string>",
  "reference": "<string>",
  "inserted_at": "<iso8601>",
  "updated_at": "<iso8601>"
}

Delete a return

DELETE /api/shed/organisations/:org_id/returns/:id

204 204 No Content

List deleted returns

GET /api/shed/organisations/:org_id/returns/deleted

Parameter	Type	Required	Description
deleted_after	iso8601	—	Return only records deleted after this timestamp.

200

{
  "data": [
    {"id": "<uuid>", "deleted_at": "<iso8601>"}
  ]
}