Honey Batches & Traceability¶
Bifolk provides a complete traceability system that tracks your honey and other hive products from harvest all the way to final products or inventory. The system uses different tracking hierarchies depending on the product type -- honey and honeycomb use a three-level hierarchy (charges, buckets, and jars), while pollen, propolis, and wax use a two-level hierarchy (charges and inventory).
Target Audience: Beekeepers tracking honey and other product production and traceability
Overview¶
Bifolk tracks different products through batch systems:
Honey & Honeycomb Traceability Chain:
graph LR
A[Honey/Honeycomb Harvests] --> B[Charge / Batch]
B --> C[Buckets]
C --> D[Jars]Pollen, Propolis & Wax Batch System:
graph LR
A[Pollen/Propolis/Wax Harvests] --> B[Charge / Batch]
B --> C[Warehouse Inventory]Honey & Honeycomb Components: - Charge (Batch) -- groups all honey of one type harvested in a single year. One charge exists per organization, per year, per honey type. Charges are created automatically when you record a harvest. - Bucket -- represents a physical bucket filled with honey from a charge. Each bucket tracks its weight and moisture content, and is linked to a bucket from your warehouse inventory. - Jar -- represents an individual jar filled from a bucket. Each jar is linked to a jar inventory item from your warehouse, and tracks its size, weight, and status (filled, in inventory, sold, consumed, or gifted).
Pollen, Propolis & Wax Components: - Charge (Batch) -- groups all pollen/propolis/wax harvested in a single year. One charge exists per organization, per year, per harvest type. Created automatically when you record a harvest. - Warehouse Inventory -- the harvested product is tracked in your warehouse inventory with quantities and status.
Charges (Batches)¶
A charge (also called a batch) represents all honey, honeycomb, pollen, propolis, or wax of a specific type collected during a single year within one organization. The charge identifier is generated automatically in the format configured by your organization.
Honey/Honeycomb: Charge identifiers follow the format YEAR-HONEY_TYPE (default, e.g., 2025-Waldhonig). Honeycomb harvests create separate charges with a -WH suffix appended to the identifier (for example, 2025-Waldhonig-WH). This keeps honeycomb production separate from standard honey production.
Pollen/Propolis/Wax: Charge identifiers use the format YEAR-HARVEST_TYPE (default, e.g., 2025-POL, 2025-PRO, 2025-WAX). The harvest type codes are configurable in your organization settings. These products each have their own separate batch.
How Charges Are Created¶
Charges are created automatically when you record a harvest. You do not need to create them manually. When a harvest is saved:
- Bifolk checks whether a charge already exists for that organization, year, honey type, and harvest type (honey or honeycomb)
- If a matching charge exists, the harvest is added to it
- If no matching charge exists, a new charge is created and the harvest is assigned to it
This means there is always exactly one charge per organization, per year, per honey type, and per harvest type. A standard honey harvest and a honeycomb harvest of the same honey type produce two separate charges.
Viewing the Charge List¶
- Click Charges in the sidebar to open the charge list
- The list shows all charges for your current organization (or all organizations if none is selected)
- Each row displays the charge identifier, honey type, year, total harvest weight, number of harvests, number of buckets, status, and creation date
The list is paginated with 20 records per page.
Sorting¶
You can sort the charge list by clicking the column headers for:
- Charge Identifier -- alphabetical
- Creation Date -- by charge creation date (default, newest first)
- Honey Type -- alphabetical by honey type
- Status -- open or closed
Click a column header once to sort ascending, click again to sort descending.
Filtering¶
Click the Show Filters button above the charge list to reveal the filter panel. Available filters:
| Filter | Description |
|---|---|
| Search | Search by charge identifier or notes |
| Honey Type | Filter by a specific honey type |
| Status | Show only open or closed charges |
| From Date | Show charges created on or after this date |
| To Date | Show charges created on or before this date |
After setting your filters, click Apply Filters to update the list. Click Reset Filters to clear all filters.
Tip
The date range defaults to the past 12 months. Adjust the date filters to see older charges.
Charge Detail Page¶
Click the view button (eye icon) on any charge to open its detail page. The detail page shows:
- Charge Summary -- charge identifier, honey type, year, status, and creation details
- Statistics -- total harvest weight, number of harvests, number of buckets, total jars, and moisture statistics (average, minimum, and maximum moisture across all buckets)
- Harvests -- all harvest records assigned to this charge, with options to view each harvest or reassign it to a different charge
- Buckets -- all buckets filled from this charge, with links to each bucket's detail page
Closing a Charge¶
When a charge is closed, no further modifications can be made:
- No new harvests can be assigned to it
- No new buckets can be created from it
- Existing buckets in the charge can no longer be modified
Note
Only organization owners and admins can close a charge.
Permissions¶
| Action | Required Role |
|---|---|
| View charges | Any member of the organization |
| Edit charges (when open) | Owner or Admin |
| Delete charges (when open) | Owner or Admin |
Closed charges cannot be edited or deleted by anyone.
Buckets¶
A bucket represents a physical container filled with honey from a charge. Buckets track the weight of honey they contain, the moisture content measured during filling, and which physical bucket from your warehouse inventory was used.
Creating a Bucket¶
You can create a bucket in two ways:
- From a charge detail page: Click Add Bucket to create a bucket pre-linked to that charge
- From the bucket list: Click Fill New Bucket, then select the charge to fill from
Bucket Form Fields¶
| Field | Description | Required |
|---|---|---|
| Charge | The charge to fill the bucket from (only shown when not pre-selected) | Yes |
| Weight (kg) | Weight of honey filled into the bucket, in kilograms | Yes |
| Moisture Content (%) | Moisture content measured during filling (typically 14-20%) | Yes |
| Inventory Bucket | Select a physical bucket from your warehouse inventory | Yes |
| Notes | Additional details about this bucket | No |
Warning
You must have buckets available in your warehouse inventory before you can fill a honey bucket. If the inventory bucket dropdown is empty, add buckets to your inventory first in the Warehouse.
How Bucket Numbers Work¶
Bucket numbers are generated automatically based on your organization's configured format. The default format is CHARGE_IDENTIFIER-B01, CHARGE_IDENTIFIER-B02, and so on (for example, 2025-Waldhonig-B01).
What Happens When You Create a Bucket¶
When you create a bucket:
- The bucket number is auto-generated
- The remaining weight is set to the full weight you entered
- One unit is removed from the selected inventory bucket in your warehouse (an inventory transaction is created automatically)
Viewing the Bucket List¶
- Click Buckets in the sidebar to open the bucket list
- The list shows all buckets for your current organization
- Each row displays the bucket number, charge, fill date, weight, remaining fill capacity, moisture content, number of jars, and status
The list is paginated with 20 records per page.
Sorting¶
You can sort the bucket list by clicking column headers for:
- Bucket Number -- alphabetical
- Fill Date -- by date the bucket was filled (default, newest first)
- Remaining (kg) -- by remaining fill capacity
- Moisture Content -- by moisture percentage
- Status -- open or closed
- Charge -- by parent charge identifier
Filtering¶
Click Show Filters to reveal the filter panel. Available filters:
| Filter | Description |
|---|---|
| Honey Type | Filter by honey type (through the parent charge) |
| Status | Show only open or closed buckets |
| From Date | Buckets filled on or after this date |
| To Date | Buckets filled on or before this date |
Tip
When viewing the jar list, you can filter by Bucket to show all jars from a specific bucket. This is useful for tracing which jars came from a particular honey bucket.
Bucket Detail Page¶
Click the view button on any bucket to open its detail page. The detail page shows:
- Bucket Information -- bucket number, charge, fill date, weight, remaining weight, moisture content, filled by, and status
- Utilization -- percentage of the bucket's honey that has been used for jars, and how much remains
- Jars -- all jars filled from this bucket, paginated at 50 per page
From the bucket detail page you can:
- Fill jars from the bucket (single or multiple at once)
- Print a bucket label with QR code
- Return the bucket to warehouse inventory
Printing a Bucket Label¶
Click the Print Label button on the bucket detail page to open a print-friendly label page. The label includes:
- Bucket number
- Charge identifier
- Honey type
- Organization name
- A QR code that links to the bucket's detail page
Use your browser's print function to print the label.
Returning a Bucket to Inventory¶
When a bucket is emptied (all honey has been jarred), you can return the physical bucket to your warehouse inventory:
- Open the bucket detail page
- Click Return to Inventory
- Confirm the return
This action:
- Adds one unit back to the inventory bucket item in your warehouse
- Marks the bucket as closed and returned
Note
You can only return a bucket if it has a linked inventory bucket and has not already been closed.
Tip
Returning a bucket to inventory does not block warehouse registration of filled jars. If the bucket still has jars that have not yet been registered as inventory products, you can still use the Add as Product to Inventory button on the bucket detail page.
Permissions¶
| Action | Required Role |
|---|---|
| View buckets | Any member of the organization |
| Create buckets (from open charge) | Owner or Admin |
| Return bucket to inventory | Owner or Admin |
Closed buckets (or buckets in a closed charge) cannot be modified.
Jars¶
A jar represents an individual container of honey filled from a bucket. Each jar has a unique number, tracks its weight and size, and follows a status lifecycle. Like buckets, jars are linked to an inventory item from your warehouse.
Creating Jars¶
- Open the bucket detail page
- Click Fill Jars
- Fill in the form:
| Field | Description | Required |
|---|---|---|
| Inventory Jar | Select a jar type from your warehouse inventory. The jar size and weight are determined automatically from the inventory item. | Yes |
| Quantity | Number of jars to create (1 to 1,000) | Yes |
| Notes | Notes to add to all created jars | No |
- Click Fill Jars
The jar number is auto-generated in the format BUCKET_NUMBER-J0001, BUCKET_NUMBER-J0002, and so on.
When you create jars:
- The bucket's remaining weight is automatically reduced by the total weight of all jars
- One unit per jar is removed from the selected inventory item in your warehouse (an inventory transaction is created automatically)
If you create more than one jar, a summary of all created jars with their numbers is shown after creation.
Warning
You must have jar inventory items with a jar size configured in your warehouse before you can fill jars. If the inventory jar dropdown is empty, add jar items to your inventory first in the Warehouse and set the jar size (e.g., 500 for 500g jars).
Warning
You cannot create jars if the bucket does not have enough remaining weight or if there are not enough jars in inventory. The form validates both.
Pending Warehouse Registration¶
At the top of the jar list, a Pending Warehouse Registration card appears when any returned bucket has filled jars that have not yet been registered as products in the warehouse. Each such bucket is listed with a Register in Inventory button that takes you directly to the registration form for that bucket.
Once all jars from a bucket are registered, that bucket is removed from the card automatically.
Viewing the Jar List¶
- Click Jars in the sidebar to open the jar list
- The list shows all jars for your current organization
- Each row displays the jar number, bucket, fill date, size, weight, honey type, and status
The list is paginated with 50 records per page. A summary at the top shows the total number of jars and a breakdown by status.
Sorting¶
You can sort the jar list by clicking column headers for:
- Jar Number -- alphabetical
- Fill Date -- by date the jar was filled (default, newest first)
- Status -- by jar status
Filtering¶
Available jar filters:
| Filter | Description |
|---|---|
| Organization | Filter by organization |
| Status | Filter by jar status (Filled, In Inventory, Sold, Consumed, Gifted) |
| Honey Type | Filter by honey type |
| Jar Size | Filter by jar size |
| Bucket | Filter by parent bucket |
Jar Status Lifecycle¶
Each jar follows a defined status lifecycle:
graph LR
A[Filled] --> B[In Inventory]
B --> C[Sold]
B --> D[Consumed]
B --> E[Gifted]| Status | Description | Can Transition To |
|---|---|---|
| Filled | Jar has just been filled from a bucket | In Inventory |
| In Inventory | Jar is stored and available for distribution | Sold, Consumed, Gifted |
| Sold | Jar has been sold (terminal state) | -- |
| Consumed | Jar was consumed personally (terminal state) | -- |
| Gifted | Jar was given as a gift (terminal state) | -- |
Once a jar reaches a terminal status (Sold, Consumed, or Gifted), its status cannot be changed again.
Info
When a jar is marked as Sold, you can optionally record the sale date and sale price for your records.
Permissions¶
| Action | Required Role |
|---|---|
| View jars | Any member of the organization |
| Create jars (from open bucket) | Owner or Admin |
Jars in a closed bucket or closed charge cannot be modified.
The Full Traceability Chain¶
The traceability chain lets you answer the question: "Where did the honey in this jar come from?"
Starting from any jar, you can trace back through:
- Jar -- which bucket was this jar filled from?
- Bucket -- which charge was this bucket filled from? What was the moisture content?
- Charge -- which harvests contributed to this charge?
- Harvests -- which hives were harvested, when, and by whom?
This chain is maintained automatically through the relationships between models. The jar detail, bucket detail, and charge detail pages all provide navigation links to follow the chain in either direction.
Numbering Example¶
Here is an example of how the numbering works across the full chain:
| Level | Number | Meaning |
|---|---|---|
| Charge | 2025-Waldhonig |
Forest honey collected in 2025 |
| Charge | 2025-Waldhonig-WH |
Forest honeycomb collected in 2025 |
| Bucket | 2025-Waldhonig-B01 |
First bucket from the honey charge |
| Bucket | 2025-Waldhonig-B02 |
Second bucket from the honey charge |
| Jar | 2025-Waldhonig-B01-J0001 |
First jar from the first bucket |
| Jar | 2025-Waldhonig-B01-J0002 |
Second jar from the first bucket |
The numbering format can be customized per organization in the organization settings.
What's Next¶
- Harvest Records -- record harvests from your hives
- Hive Management -- manage your hives
- Warehouse & Inventory -- track inventory, including buckets and jars
- Beekeeping Operations -- record feeding, treatments, and maintenance