How to upload historical donations with Donation Logger

What Donation Logger does

Donation Logger gives Foodbank Admin users a self-serve way to upload historical donation records using a structured CSV file. Instead of relying on support teams or manual backend uploads, you can validate your file, correct any issues, and submit the upload directly in Foodiverse.

• Uploads create donations with a Logged source

• Logged donations remain separate from live operational donations

• Successful uploads appear in reporting and donation views

• Validation happens before donations are created

• If any row fails validation, the entire upload fails

Before you start

Before using Donation Logger, make sure all of the following are true:

• You are a Foodbank Admin

• The Donation Logger feature is enabled for your organisation

• You have the donation data ready in the approved CSV template

• You know the correct donor and charity official IDs for each row

• You understand whether each row is being logged as Actuals or Estimates

Open Donation Logger

1. Log in to Foodiverse.

2. Open the left-hand navigation menu.

3. Go to the Foodbank area of the platform.

4. Select Donation Logger.

The Donation Logger navigation item appears under Manage Donor temp. schedule and above Foodnet Settings when the feature is enabled for authorised users.

Download and complete the CSV template

On the Donation Logger page, download the template file before preparing your upload. The template is designed to show exactly which fields users should complete.

At minimum, the upload supports donation-level fields such as:

• donated_at

• donor_official_id

• charity_official_id

• category

• weight_kg

• estimate_actuals

Important rules when completing the file:

• Use the approved category values and formatting from the template guidance

• Enter the donation date only where requested

• Use valid donor and charity official IDs

• Do not rename columns unless the template guidance explicitly allows it

• Do not add backend-only fields

Understand Actuals and Estimates

Each row must identify whether it is being uploaded as Actuals or Estimates. This matters because Product Level Detail rules differ depending on the value.

Add Product Level Detail for Actuals

If a row is marked as Actuals, you must provide the required Product Level Detail values for that row. Product Level Detail is used to support product visibility in downstream surfaces such as Donations History, Recent Offers, and the View Product experience where supported.

For Actuals rows:

• PLD is mandatory

• One product per row is supported for MVP

• Product values must be valid and complete

• The system will try to match the product to an existing donor product

• If no matching donor product exists, the system can create one

For Estimates rows:

• PLD is not required

• If PLD is included, the final behaviour depends on the confirmed implementation rules for your release version

Donation-logger-example.csv

Upload and validate your file

1. Open the Donation Logger page.

2. Select your completed CSV file.

3. Start validation.

4. Review the validation result.

Validation checks the structure and content of the file before anything is created in the system.

Validation can detect issues such as:

• Missing required fields

• Blank or null values

• Invalid date formats

• Unsupported category values

• Invalid donor official IDs

• Invalid charity official IDs

• Duplicate rows

• Duplicate filenames

• Malformed files

• Missing or invalid PLD for Actuals rows

Fix validation issues

If validation fails, review the on-screen feedback and download the error log if available. The error log is designed to help you identify the exact rows and fields that need attention.

Common reasons a file fails:

• A donor or charity official ID does not match a valid record

• A category value is unsupported or incorrectly formatted

• An Actuals row is missing required PLD information

• Two rows are exact duplicates

• The same filename was already uploaded within the configured duplicate window

After correcting the file, save it and run validation again.

Confirm and submit the upload

Once your file passes validation, proceed to the confirmation step.

1. Review the summary shown on screen.

2. Check that the file is the correct version.

3. Confirm the upload.

After submission, Foodiverse processes the file and creates logged donations. Each successful donation receives a backend-generated reference ID that clearly identifies it as logged.

Where logged donations appear

After a successful upload, logged donations should appear in the same key places users already use to review donation activity and reporting.

• Donations History

• Recent Offers

• Impact Summary

• Branch Impact Reports

Where filtering is supported, reports can distinguish between:

• Logged

• Live

• All

Good practice for successful uploads

• Always start from the latest downloadable template

• Double-check donor and charity official IDs before uploading

• Keep category values exactly aligned with the template guidance

• Make sure Actuals rows include all required PLD fields

• Validate before sharing the file with colleagues as “ready”

• Avoid reusing filenames unless you are sure duplicate rules will allow it

• Keep a local copy of both the submitted file and any error log for your records