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

Receipts

A receipt records the delivery of agricultural inputs — chemicals, fertiliser, seed — into a storage location. Each receipt has one or more line items, each representing a product and quantity received.

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

The receipt object

Field Type Mutability Notes
id uuid system
organisation_id uuid system
sequence string system Sequential identifier (REC-XXXXXXXX).
storage_id uuid required Storage location receiving the delivery.
received_at iso8601 required Date and time the delivery was received.
supplier string required Supplier name.
notes string optional Optional notes.
order_number string optional Optional purchase order number.
under_review boolean system Whether the receipt is currently under review. Read-only — set by the system during import.
line_items array optional Array of line item objects.
inserted_at iso8601 system
updated_at iso8601 system Updated when line items change.

Line item object

Field Type Mutability Notes
id uuid system
product_id uuid required Product.
product_alias_id uuid optional Product alias, if applicable.
quantity decimal string required Number of packs.
pack_size_value decimal string required Pack size amount.
pack_size_unit string required Pack size unit (e.g. l, kg).
pack_cost decimal string required Cost per pack. May be zero.

List receipts

GET /api/shed/organisations/:org_id/receipts
Parameter Type Required Description
updated_after iso8601 — Return only records updated after this timestamp. Useful for polling-based sync.
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: products, product_aliases, storage.
200 
{
  "data": [
    {
      "id": "<uuid>",
      "organisation_id": "<uuid>",
      "sequence": "<string>",
      "storage_id": "<uuid>",
      "received_at": "<iso8601>",
      "supplier": "<string>",
      "notes": "<string>",
      "order_number": "<string>",
      "under_review": "<boolean>",
      "line_items": [
        {
          "id": "<uuid>",
          "product_id": "<uuid>",
          "product_alias_id": "<uuid>",
          "quantity": "<decimal string>",
          "pack_size_value": "<decimal string>",
          "pack_size_unit": "<string>",
          "pack_cost": "<decimal string>"
        }
      ],
      "inserted_at": "<iso8601>",
      "updated_at": "<iso8601>"
    }
  ],
  "meta": {
    "page": "<integer>",
    "page_size": "<integer>",
    "total_count": "<integer>",
    "total_pages": "<integer>"
  }
}
200 200 with ?include=products,product_aliases 
{
  "data": [...],
  "meta": {...},
  "included": {
    "products": {
      "<uuid>": {
        "id": "<uuid>",
        "organisation_id": "<uuid>",
        "name": "<string>",
        "inserted_at": "<iso8601>",
        "updated_at": "<iso8601>"
      }
    },
    "product_aliases": {
      "<uuid>": {
        "id": "<uuid>",
        "organisation_id": "<uuid>",
        "product_id": "<uuid>",
        "name": "<string>",
        "inserted_at": "<iso8601>",
        "updated_at": "<iso8601>"
      }
    }
  }
}

Get a receipt

GET /api/shed/receipts/:id

Returns a single receipt with all line items. The receipt must belong to an organisation accessible by the token.

Parameter Type Required Description
include string — Comma-separated list of related resources to sideload. Accepted values: products, product_aliases, storage.
200 
{
  "id": "<uuid>",
  "organisation_id": "<uuid>",
  "sequence": "<string>",
  "storage_id": "<uuid>",
  "received_at": "<iso8601>",
  "supplier": "<string>",
  "notes": "<string>",
  "order_number": "<string>",
  "under_review": "<boolean>",
  "line_items": [
    {
      "id": "<uuid>",
      "product_id": "<uuid>",
      "product_alias_id": "<uuid>",
      "quantity": "<decimal string>",
      "pack_size_value": "<decimal string>",
      "pack_size_unit": "<string>",
      "pack_cost": "<decimal string>"
    }
  ],
  "inserted_at": "<iso8601>",
  "updated_at": "<iso8601>"
}
200 200 with ?include=products,product_aliases,storage 
{
  "id": "<uuid>",
  "organisation_id": "<uuid>",
  "sequence": "<string>",
  "storage_id": "<uuid>",
  "received_at": "<iso8601>",
  "supplier": "<string>",
  "notes": "<string>",
  "order_number": "<string>",
  "under_review": "<boolean>",
  "line_items": [
    {
      "id": "<uuid>",
      "product_id": "<uuid>",
      "product_alias_id": "<uuid>",
      "quantity": "<decimal string>",
      "pack_size_value": "<decimal string>",
      "pack_size_unit": "<string>",
      "pack_cost": "<decimal string>"
    }
  ],
  "inserted_at": "<iso8601>",
  "updated_at": "<iso8601>",
  "included": {
    "products": {
      "<uuid>": {
        "id": "<uuid>",
        "organisation_id": "<uuid>",
        "name": "<string>",
        "inserted_at": "<iso8601>",
        "updated_at": "<iso8601>"
      }
    },
    "product_aliases": {
      "<uuid>": {
        "id": "<uuid>",
        "organisation_id": "<uuid>",
        "product_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 receipt

POST /api/shed/organisations/:org_id/receipts
Request body
Field Type Mutability Notes
storage_id uuid required Must belong to the organisation.
received_at iso8601 required
supplier string required
notes string optional
order_number string optional
line_items array optional Array of line item objects (see below). Omit to create a receipt with no items.

Line item fields

Field Type Mutability Notes
product_id uuid required
product_alias_id uuid optional
quantity decimal string required Number of packs.
pack_size_value decimal string required
pack_size_unit string required e.g. l, kg
pack_cost decimal string required Cost per pack. May be zero.
201 
{
  "id": "<uuid>",
  "organisation_id": "<uuid>",
  "sequence": "<string>",
  "storage_id": "<uuid>",
  "received_at": "<iso8601>",
  "supplier": "<string>",
  "notes": "<string>",
  "order_number": "<string>",
  "under_review": "<boolean>",
  "line_items": [
    {
      "id": "<uuid>",
      "product_id": "<uuid>",
      "product_alias_id": "<uuid>",
      "quantity": "<decimal string>",
      "pack_size_value": "<decimal string>",
      "pack_size_unit": "<string>",
      "pack_cost": "<decimal string>"
    }
  ],
  "inserted_at": "<iso8601>",
  "updated_at": "<iso8601>"
}

Update a receipt

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

Updates a receipt. The line_items key controls how line items are handled:

  • Key absent — header fields updated, line items untouched.
  • Empty array [] — all line items deleted.
  • Array with items — desired-state merge: items with an id are updated, items without an id are created, existing items not in the list are deleted.
⚠ Omit line_items entirely to leave items unchanged. Passing null is invalid and will return a 422 error.
200 
{
  "id": "<uuid>",
  "organisation_id": "<uuid>",
  "sequence": "<string>",
  "storage_id": "<uuid>",
  "received_at": "<iso8601>",
  "supplier": "<string>",
  "notes": "<string>",
  "order_number": "<string>",
  "under_review": "<boolean>",
  "line_items": [...],
  "inserted_at": "<iso8601>",
  "updated_at": "<iso8601>"
}

Delete a receipt

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

Permanently deletes a receipt and all its line items. A deletion record is written to support sync — see List deleted receipts.

204 204 No Content

List deleted receipts

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

Returns deletion records for receipts that have been deleted. Use this alongside updated_after on the main list endpoint to implement a complete sync that handles both updates and deletions.

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 receipt.
deleted_at iso8601 optional When the record was deleted.
200 
{
  "data": [
    {"id": "<uuid>", "deleted_at": "<iso8601>"}
  ]
}