Customers

Manage the people who receive food parcels from your food bank, including their demographics, referrer links, and login accounts.

Overview

In HelpingHand, customers are called Recipients. You will find them under Recipient > Recipients in the sidebar. Each recipient belongs to a single customer group. The system tracks their personal details and order history. Address, family size, ethnicity, and referrer relationship are optional fields that your food bank can choose to enable or disable.

You only see your own food bank's recipients -- those that belong to customer groups linked to your food bank.

Key Concepts

Recipients (Customers)

A recipient record stores:

• Name and email -- basic identity fields.
• Address -- street number, apartment number, street address, suburb/town, and post code / zip code.
• Phone number -- contact number.
• Ethnicity -- selected from a predefined list, with an "other" free-text option for certain categories.
• Family size -- number of adults and number of children in the household.
• Pickup location -- the location where the recipient collects their parcel.
• Referrer, referrer contact, and auth code -- links the recipient to the organisation that referred them.
• Customer group -- organises recipients within your food bank and can set order limits.
• Pricing mode -- optional override for how product prices display to this recipient.
• Order limits -- per-recipient overrides for how many orders they can place in a period.

Customer Groups

Customer groups organise recipients within your food bank. Your food bank has one or more customer groups, and each recipient belongs to exactly one group. Groups can also set default order limits (max orders in a period, period length in weeks) that apply to all recipients in that group unless overridden at the recipient level.

Groups are managed under Recipient > Groups in the sidebar.

Shop Users (Login Accounts)

A shop user is the login account that lets a recipient sign in to the online shop. The relationship is many-to-one: multiple recipients can share the same shop user account. This is useful when a single person receives parcels from more than one food bank.

Each shop user has:

• Enabled status -- whether the account can log in.
• Verified status -- whether the email address has been confirmed.

Admins can prevent login (soft-delete the shop user) or reinstate login (restore the shop user) from the recipient detail page. This does not delete the recipient record itself.

Auth Codes and Referrer Links

Recipients are linked to referrers through auth codes. The flow works as follows:

1. A referrer organisation has contacts (referrer contacts).
2. Referrer contacts generate 8-digit auth codes for their recipients.
3. A recipient enters the auth code during registration.
4. The system links the recipient to the referrer contact and referrer that issued the code.

Soft Delete and Restore

Recipients use soft delete. When you delete a recipient, the system sets a deletedAt timestamp rather than removing the record. Soft-deleted recipients do not appear in the grid or in shop operations. The delete button appears on both the recipient edit page and the detail page, with a confirmation prompt.

Shop user accounts can also be soft-deleted and restored independently. This lets you block a recipient's login without removing their data.

How It Works

The Recipients Grid

Navigate to Recipient > Recipients. The grid displays:

| Column | Description | |---|---| | First Name | Sortable. | | Last Name | Sortable. | | Email | Sortable. Links to the recipient detail page. | | Referrer Code | The full auth code (prefix + suffix). | | Referrer | The referrer organisation name. | | Referrer Contact | The referrer contact's name. | | Registration Date | When the recipient registered. Sortable. | | Status | Two icons: enabled (tick or cross) and verified (tick or cross). Guest recipients show a spy icon. |

The grid defaults to 200 rows per page, sorted by first name ascending.

Filters

Expand the Filters panel to narrow results:

• Search -- free-text search across email, first name, and last name.
• Group -- filter by customer group.
• Referrer -- filter by referrer organisation. When active, the Referrer column hides automatically.
• Referrer Contact -- filter by referrer contact. When active, both the Referrer and Referrer Contact columns hide automatically (since the filter already tells you which referrer contact you are viewing).

Grid Actions

Each row has three action buttons:

• Show orders -- opens the recipient's order history.
• Show -- opens the recipient detail page.
• Update -- opens the recipient edit form.

There is no "Create" button on the grid. Recipients register themselves through the shop front or are created via the API.

Recipient Detail Page

The detail page shows all recipient information in read-only sections:

• General information -- name, email, phone, gender, birthday, customer since date.
• Address -- street number, apartment, street address, suburb/town, post code / zip code.
• Customer group -- which group the recipient belongs to.
• Pickup location -- where parcels are collected.
• Ethnicity -- the selected ethnicity, with free-text detail for "other" categories.
• Family -- number of children and number of adults.
• Referrer details -- referrer contact name and phone, referrer organisation, and full auth code.
• Order limits -- max orders in period, period length (weeks), reset date override, and a summary showing orders used vs remaining.
• Agreed to terms -- whether the recipient accepted terms and conditions.
• Registration question -- answer to any custom registration question configured in your settings.

From the detail page, admins can:

• Prevent login -- soft-deletes the shop user, blocking the recipient from signing in.
• Reinstate login -- restores a previously blocked shop user.
• Delete -- soft-deletes the recipient record.

Recipient Edit Form

The edit form lets you modify all recipient fields. It includes additional sections:

• Extra information -- address, ethnicity, family size, pickup location, referrer link, registration question, and terms agreement.
• Order limits -- max orders in period, period weeks, reset date override, next order allowed from date, limit days override, and pricing mode.

Data Visibility

The recipient list is filtered so you only see your own food bank's data:

• You only see recipients in customer groups linked to your food bank.
• If a referrer admin is logged in, they only see their own referrer's recipients.
• If a referrer contact admin is logged in, they only see their own referrer contact's recipients.

Soft-deleted recipients (those with a deletedAt value) are always excluded from the grid.

Common Tasks

Find a recipient

1. Go to Recipient > Recipients.
2. Use the Search filter to type part of the name or email.
3. Click the search icon or press Enter.

Filter by referrer or referrer contact

1. Expand the Filters panel.
2. Select a Referrer or Referrer Contact from the dropdown.
3. Apply the filter. The grid hides redundant columns automatically.

View a recipient's orders

1. Find the recipient in the grid.
2. Click the Show orders action (shopping bag icon) on their row.

Block a recipient from logging in

1. Open the recipient's detail page (click Show on their row).
2. Click Prevent login from the actions menu.
3. Confirm the action. The shop user is soft-deleted and the recipient can no longer sign in.

Reinstate a blocked login

1. Open the recipient's detail page.
2. Click Reinstate login from the actions menu.
3. Confirm the action. The shop user is restored and the recipient can sign in again.

Delete a recipient

1. Open the recipient's edit page (click Update on their row).
2. Click the Delete button.
3. Confirm the action. The recipient is soft-deleted and no longer appears in the grid.

View demographic information

1. Open the recipient's detail page.
2. Scroll to the Ethnicity and Family sections to see ethnicity, number of adults, and number of children.

FAQ

Why is the page called "Recipients" instead of "Customers"? HelpingHand uses the term "Recipients" in the admin interface because food bank users receive food parcels rather than purchasing products. Internally, the system still uses the Sylius "Customer" entity.

Can I create a new recipient from the admin? No. The grid does not have a Create button. Recipients register themselves through the shop front or are created via the API. This ensures they go through the proper registration flow, including agreeing to terms and entering an auth code.

What happens when I delete a recipient? The recipient is soft-deleted. Their record stays in the database but no longer appears in the grid or shop. Their order history is preserved. You cannot undo a soft delete from the admin interface for the recipient record itself, but shop user logins can be reinstated.

Can a recipient belong to multiple food banks? A recipient record belongs to one customer group and therefore one food bank. However, the same person can have multiple recipient records (one per food bank) sharing the same shop user login account.

What are order limits? Order limits control how many orders a recipient can place within a time period. These can be set at three levels (highest priority first): the individual recipient, the customer group, or your food bank's settings. A recipient-level override takes precedence over the group default.

How does the auth code work? Each auth code is a unique 8-digit number. Recipients enter this code during registration to gain access to the system. The code also associates the recipient with the referrer and referrer contact who issued it.

What do the status icons mean? The Status column shows two icons side by side. The first indicates whether the shop user account is enabled (green tick) or disabled (grey cross). The second indicates whether the email is verified (green tick) or unverified (grey cross). If the recipient has no shop user, a spy icon appears instead, indicating a guest.