# MyRedButton — CSV bulk-import guide

This is the format you give Carl (or any client admin) so they can drop a roster into the dashboard in seconds.

## Download

[**myredbutton-customers-template.csv**](myredbutton-customers-template.csv) — sample file with 5 example rows showing every option.

## Columns

| Column | Required | Notes |
|---|---|---|
| **first_name** | ✅ Yes | Given name only. |
| **surname** | ✅ Yes | Family name. |
| **phone** | ✅ Yes | South African mobile. Either local 10-digit (`0828590094`) or international E.164 (`+27828590094`) — the importer auto-normalises. |
| **email** | No | Optional. Lowercased on save. |
| **tier** | No | One of `essential`, `plus`, `premium`. Defaults to `essential` if blank. |
| **plan_kind** | No | One of `single`, `family`. Defaults to `single` if blank. |
| **id_number** | No | South African ID, no spaces. Optional but recommended — used by responders for identity verification on dispatch. |
| **notes** | No | Free-text. Visible to MyRedButton + ProjectHelp customer service. Never shown to the customer themselves. |

## Tier + plan reference

| | Single | Family (main + up to 4 dependants) |
|---|---|---|
| **Essential** | R59 / mo — Panic Button only | R129 / mo |
| **Plus** | R69 / mo — Panic + Roadside + License + Fines + Talking Point | R139 / mo |
| **Premium** | R89 / mo — Plus all of the above + RAF Claims + everything | R159 / mo |

## What happens on import

- Every row lands in `app_customers` with `status = 'invited'`, `source = 'csv_import'`.
- Once the mobile app's [lookup wiring](https://github.com/Jadederidder/project-help-sos/) is live (Session 3), the customer can download the app, verify their phone OTP, and drop straight into the home screen — no Paystack, no signup wizard. The corporate has prepaid via the bulk import.
- The same row appears in JD's main ProjectHelp CRM for customer service to manage (cancellations, upgrades, downgrades, support calls).
- A welcome SMS is fired via BulkSMS when wiring lands (currently stubbed).

## Validation rules

The import wizard's **Preview** step shows every row + flags invalid ones in red. You'll see:
- ❌ first name or surname missing
- ❌ phone not a valid E.164 / SA mobile
- ❌ tier not one of essential/plus/premium
- ❌ plan_kind not single/family

Only valid rows are imported. Invalid rows are skipped — the wizard tells you how many were skipped on the final screen.

## Re-imports + duplicates

The importer uses **(tenant + phone)** as the conflict key. If you re-upload a CSV that contains a phone number already in the system, that row's tier/plan/email/notes are **updated**, not duplicated. So you can safely use the same file to roll out updates.

## Family plans

A `family` plan covers the main holder + up to 4 dependants. The main holder pays the family fee; dependants are invited separately from within the app (or via a second CSV row with the same `family_group_id` once we wire that — current pattern is "add the dependant as their own customer row with `plan_kind=family` so they get the app", which works fine).

---

Questions: jd@projecthelp.co.za