title: “Membership — Program Loyalty” description: “Manajemen tier membership dengan 5 skema loyalty (spending, stamp, points, visits, hybrid), benefit konfigurasi, dan auto-upgrade di SNISHOP ERP.”

Membership — Program Loyalty

Halaman Membership mengelola tier membership dan program loyalty perusahaan. Sistem mendukung 5 skema loyalty dengan benefit yang bisa dikustomisasi per tier, termasuk diskon, poin multiplier, dan free delivery.

Arsitektur

Akses Halaman

URL: /crm → tab Loyalty

Diagram Relasi Entitas (ERD)

Berikut adalah relasi antar entitas yang terlibat dalam sistem membership SNISHOP ERP:

Entitas: CustomerMembership (Schema Lengkap)

Entitas CustomerMembership mendefinisikan setiap tier dalam program loyalty. Setiap tier memiliki konfigurasi skema, kriteria upgrade, benefit, dan reward yang independen. Berikut adalah schema lengkap seluruh field:

Field Identitas & Visual

Field	Tipe	Default	Wajib	Deskripsi
`company_id`	string	—	Ya	ID perusahaan pemilik tier ini. Setiap tier terisolasi per company.
`level_name`	string	—	Ya	Nama tampilan tier, misal “Silver”, “Gold”, “Platinum”, “Diamond”.
`level_key`	string	—	Ya	Key unik untuk referensi programatik, misal `silver`, `gold`, `platinum`. Harus unik dalam satu company.
`icon`	string	—	Tidak	Ikon emoji untuk tier (misal ”🥈”, ”🥇”, ”💎”). Ditampilkan di POS dan dashboard.
`color`	string	—	Tidak	Kode warna hex/nama untuk tier (misal “#C0C0C0”, “gold”). Digunakan di UI badge dan kartu member.
`description`	string	—	Tidak	Penjelasan lengkap mengenai keuntungan dan syarat keanggotaan pada level ini. Maksimal 1.000 karakter.
`is_active`	boolean	`true`	Tidak	Status aktif tier. Tier non-aktif tidak bisa dijadikan target upgrade namun tetap berlaku untuk member yang sudah berada di tier tersebut.
`order`	number	`0`	Tidak	Urutan tier dalam hierarki. Semakin tinggi nilainya, semakin premium tier tersebut. Digunakan untuk sorting dan penentuan arah upgrade/downgrade.

Field Benefit & Diskon

Field	Tipe	Default	Deskripsi
`discount_percentage`	number	`0`	Persentase diskon otomatis di POS (range 0–100). Diterapkan ke subtotal transaksi sebelum pajak.
`points_multiplier`	number	`1`	Pengali perolehan poin per transaksi. Nilai 1 = normal, 2 = double points, 3 = triple points.
`benefits`	array[string]	—	Daftar benefit dalam bentuk teks bebas. Ditampilkan di kartu member dan halaman profil pelanggan.
`priority_support`	boolean	`false`	Hak akses antrian prioritas via WhatsApp dedicated.
`free_delivery`	boolean	`false`	Gratis ongkos kirim untuk semua pesanan (delivery & marketplace).
`birthday_bonus`	number	`0`	Bonus poin tambahan yang diberikan di hari ulang tahun customer. Nilai 0 berarti tidak ada bonus.

Field Skema Spending

Field	Tipe	Default	Deskripsi
`min_purchase`	number	`0`	Minimum akumulasi pembelian (`lifetime_value`) untuk mencapai tier ini. Digunakan pada skema `spending` dan sebagai salah satu kriteria `hybrid`.

Field Skema Points

Field	Tipe	Default	Deskripsi
`points_threshold`	number	`10000`	Ambang batas nilai belanja (dalam Rupiah) untuk memperoleh poin. Misal Rp 10.000 = setiap kelipatan Rp 10.000 dari transaksi eligible menghasilkan poin.
`points_per_threshold`	number	`1`	Jumlah poin yang diperoleh per threshold tercapai. Misal 1 poin per Rp 10.000.
`min_redemption_points`	number	`0`	Minimum poin yang harus dimiliki customer sebelum bisa melakukan penukaran reward. Nilai 0 berarti tidak ada minimum.

Field Skema Stamp

Field	Tipe	Default	Deskripsi
`stamps_required`	number	`10`	Jumlah stamp yang dibutuhkan untuk naik tier atau menukar reward pada skema stamp.
`stamp_per_transaction`	number	`1`	Jumlah stamp yang diperoleh customer per satu transaksi eligible. Bisa lebih dari 1 untuk transaksi dengan nilai tertentu.

Field Reward

Field	Tipe	Default	Deskripsi
`reward_type`	enum	`"none"`	Jenis reward yang bisa ditukarkan: `none` (tidak ada), `discount_percentage` (diskon persen), `discount_amount` (diskon nominal), `free_product` (produk gratis).
`reward_value`	number	`0`	Nilai reward — berupa persentase (untuk `discount_percentage`) atau nominal Rupiah (untuk `discount_amount`).
`reward_product_id`	string	—	ID produk yang diberikan sebagai reward jika `reward_type = "free_product"`. Referensi ke entitas POSProduct.
`reward_product_name`	string	—	Nama produk reward gratis (disimpan sebagai denormalisasi agar tetap tersedia meski produk dihapus).

Field Skema Visits & Kedaluwarsa

Field	Tipe	Default	Deskripsi
`scheme_type`	enum	`"points"`	Skema loyalty yang berlaku pada tier ini: `points`, `stamp`, `spending`, `visits`, atau `hybrid`.
`expiry_days`	number	—	Masa kedaluwarsa poin dalam hari. Jika diisi, poin yang tidak digunakan akan hangus setelah N hari sejak perolehan. Kosong = tidak ada kedaluwarsa.

Total: 25 Field

Entitas CustomerMembership memiliki 25 field yang mencakup identitas, visual, benefit, 5 jenis skema loyalty, konfigurasi reward, dan kedaluwarsa poin.

Entitas: Customer (Field Membership)

Entitas Customer memiliki beberapa field khusus yang terhubung dengan sistem membership:

Field	Tipe	Default	Deskripsi
`membership_level_id`	string	—	Foreign key ke `CustomerMembership._id`. Menentukan tier aktif pelanggan.
`membership_level_name`	string	—	Denormalisasi nama tier untuk performa query (tidak perlu join).
`membership_since`	date	—	Tanggal pertama kali customer terdaftar sebagai member.
`membership_points`	number	`0`	Saldo poin aktif yang bisa digunakan untuk redeem reward.
`lifetime_points`	number	`0`	Total poin yang pernah diperoleh sepanjang waktu (tidak berkurang saat redeem).
`stamps`	number	`0`	Saldo stamp aktif untuk skema stamp.
`has_negative_points`	boolean	`false`	Flag yang menandakan saldo poin negatif akibat pembatalan/void transaksi setelah poin terpakai.
`loyalty_deficit_points`	number	`0`	Besaran defisit poin yang membutuhkan rekonsiliasi manual oleh admin.
`loyalty_review_notes`	string	—	Catatan review dari admin/operator terkait penanganan loyalty deficit.
`last_tier_upgrade_date`	datetime	—	Timestamp perubahan tier terakhir (upgrade atau downgrade).
`last_tier_upgrade_reason`	string	—	Alasan perubahan tier, misal “Auto-upgrade: spending threshold met” atau “Manual downgrade oleh admin”.
`last_tier_upgrade_by`	string	—	Email operator atau admin yang melakukan perubahan tier. Untuk auto-upgrade, diisi oleh sistem.
`lifetime_value`	number	`0`	Total nilai transaksi sepanjang waktu — menjadi kriteria utama skema spending.
`total_orders`	number	`0`	Jumlah total transaksi — menjadi kriteria utama skema visits.

Entitas: CustomerLoyaltyLedger (Audit Trail)

Setiap mutasi loyalty (perolehan, penukaran, pembatalan, penyesuaian) dicatat di CustomerLoyaltyLedger sebagai audit trail lengkap. Entitas ini menjamin traceability penuh atas setiap perubahan saldo poin dan stamp.

Field Utama

Field	Tipe	Default	Deskripsi
`company_id`	string	—	ID perusahaan (multi-tenant isolation).
`customer_id`	string	—	ID customer pemilik mutasi loyalty.
`customer_name`	string	—	Nama customer saat transaksi (denormalisasi untuk audit).
`customer_phone`	string	—	Nomor telepon customer saat transaksi.
`transaction_id`	string	—	ID transaksi POS yang menghasilkan mutasi ini.
`transaction_number`	string	—	Nomor struk / receipt number transaksi.
`idempotency_key`	string	—	Wajib. Key unik untuk mencegah double-crediting atau double-posting. Setiap mutasi harus memiliki key yang unik.
`event_type`	enum	—	Wajib. Tipe event mutasi: `earn`, `redeem`, `return_reversal`, `tier_upgrade`, `manual_adjustment`.
`scheme_type`	enum	`"points"`	Skema loyalty yang berlaku saat event terjadi.

Field Saldo (Before/After Snapshot)

Field	Tipe	Default	Deskripsi
`points_delta`	number	`0`	Perubahan poin: positif = bertambah, negatif = berkurang.
`points_before`	number	`0`	Saldo poin sebelum event terjadi.
`points_after`	number	`0`	Saldo poin setelah event terjadi.
`stamps_delta`	number	`0`	Perubahan stamp: positif = bertambah, negatif = berkurang.
`stamps_before`	number	`0`	Saldo stamp sebelum event.
`stamps_after`	number	`0`	Saldo stamp setelah event.
`eligible_amount`	number	`0`	Nilai transaksi yang sah (eligible) untuk perhitungan perolehan poin.

Field Reward & Deficit

Field	Tipe	Default	Deskripsi
`reward_details`	object	—	Detail reward saat event = `redeem`. Berisi `reward_type`, `discount_amount`, `discount_percentage`, `product_id`, `product_name`, `cost_points`, `cost_stamps`.
`deficit_points`	number	`0`	Defisit poin yang terjadi jika transaksi di-void setelah poin sudah terpakai.
`requires_manual_review`	boolean	`false`	Flag yang menandakan transaksi reversal menghasilkan saldo negatif dan butuh review manual oleh admin.
`reason`	string	—	Alasan atau keterangan mutasi (wajib untuk `manual_adjustment`).

Field Audit

Field	Tipe	Deskripsi
`performed_by`	string	Email atau ID operator yang memproses mutasi.
`actor_role`	string	Role aktor: `owner`, `admin`, `cashier`.
`created_at`	datetime	Waktu event tercatat di server.
`finance_record_id`	string	ID FinancialRecord terkait (untuk event `redeem` yang mem-posting biaya COGS reward ke modul keuangan).

Entitas: POSMember

Entitas POSMember adalah representasi member yang terdaftar langsung melalui modul POS (kasir). Memiliki field yang mirip dengan Customer namun lebih sederhana dan terfokus pada operasional kasir.

Field	Tipe	Default	Deskripsi
`name`	string	—	Wajib. Nama member POS.
`phone`	string	—	Wajib. Nomor telepon member.
`email`	string	—	Alamat email member.
`address`	string	—	Alamat lengkap.
`birth_date`	date	—	Tanggal lahir (untuk birthday bonus).
`membership_tier`	enum	`"regular"`	Tier member: `regular`, `silver`, `gold`, `platinum`.
`points`	number	`0`	Saldo poin aktif.
`lifetime_points`	number	`0`	Total poin sepanjang waktu.
`stamps`	number	`0`	Saldo stamp aktif.
`has_negative_points`	boolean	`false`	Flag saldo negatif.
`loyalty_deficit_points`	number	`0`	Defisit poin setelah retur/void.
`loyalty_review_notes`	string	—	Catatan review deficit.
`last_tier_upgrade_date`	datetime	—	Waktu perubahan tier terakhir.
`last_tier_upgrade_reason`	string	—	Alasan perubahan tier.
`last_tier_upgrade_by`	string	—	Email operator yang mengubah tier.
`total_spent`	number	`0`	Total nilai belanja.
`visit_count`	number	`0`	Jumlah kunjungan/transaksi.
`last_visit`	datetime	—	Waktu kunjungan terakhir.
`discount_percentage`	number	`0`	Diskon khusus member (di-set berdasarkan tier).
`notes`	string	—	Catatan tambahan tentang member.
`is_active`	boolean	`true`	Status keaktifan member.

State Machine: Tier Progression

Berikut adalah diagram state machine untuk progresi tier membership customer:

Transisi State — Detail

Dari	Ke	Trigger	Kondisi
`[*]`	NonMember	Registrasi customer baru	Customer dibuat dengan `membership_level_id = null`
NonMember	Regular	Registrasi member	Customer diberi `membership_level_id` ke tier terendah
Regular	Silver+	Auto-upgrade	Kriteria tier berikutnya terpenuhi (lihat skema di bawah)
Silver+	Gold+	Auto-upgrade	Kriteria tier berikutnya terpenuhi
Tier tinggi	Tier rendah	Manual downgrade	Admin melakukan downgrade dengan alasan yang dicatat
Active	Inactive	Timeout / manual	Tidak aktif > 365 hari atau dinonaktifkan oleh admin
Inactive	Regular	Re-aktivasi	Admin mengaktifkan kembali customer

5 Skema Loyalty — Perbandingan Lengkap

Aspek	Spending	Stamp	Points	Visits	Hybrid
Kriteria Upgrade	`lifetime_value >= min_purchase`	`stamps >= stamps_required`	`membership_points >= points_required`	`total_orders >= visits_required`	Salah satu kriteria terpenuhi
Field Kunci	`min_purchase`	`stamps_required`, `stamp_per_transaction`	`points_threshold`, `points_per_threshold`	`visits_required` (via `total_orders`)	Kombinasi semua field
Satuan Metrik	Rupiah (Rp)	Jumlah stempel	Jumlah poin	Jumlah kunjungan	Multi-metrik
Perolehan	Otomatis dari total transaksi	+`stamp_per_transaction` per trx	`eligible_amount / points_threshold * points_per_threshold * multiplier`	+1 per transaksi	Tergantung skema tier
Cocok Untuk	F&B premium, restoran fine dining	Coffee shop, bakery, quick service	Retail, supermarket, F&B general	Fast food, warung, kantin	Bisnis dengan multi-channel
Kelebihan	Mencerminkan nilai pelanggan	Sederhana, mudah dipahami	Fleksibel, bisa untuk redeem	Mendorong frekuensi kunjungan	Fleksibel, customer punya banyak jalur
Kekurangan	Customer kecil sulit upgrade	Tidak mencerminkan nilai transaksi	Perlu perhitungan lebih kompleks	Tidak mencerminkan nilai per trx	Konfigurasi lebih rumit

Skema Spending

Upgrade jika: customer.lifetime_value >= tier.min_purchase

Tier	min_purchase
Silver	Rp 1.000.000
Gold	Rp 5.000.000
Platinum	Rp 20.000.000

Skema Stamp

Upgrade jika: customer.membership_points >= tier.stamps_required
Setiap transaksi: customer.membership_points += tier.stamp_per_transaction

Tier	stamps_required	stamp_per_transaction
Silver	10	1
Gold	25	2
Platinum	50	3

Skema Points

Upgrade jika: customer.membership_points >= tier.points_required

Poin diperoleh dari transaksi dengan multiplier sesuai tier.

Skema Visits

Upgrade jika: customer.total_orders >= tier.visits_required

Skema Hybrid

Upgrade jika: SALAH SATU kriteria terpenuhi
  - lifetime_value >= min_purchase
  - membership_points >= points_required
  - total_orders >= visits_required

Sistem Reward — 4 Jenis Reward

Sistem membership SNISHOP ERP mendukung 4 jenis reward yang bisa dikonfigurasi per tier melalui field reward_type:

1. Discount Percentage (`discount_percentage`)

Reward berupa potongan harga dalam persentase dari subtotal transaksi.

Aspek	Detail
Field	`reward_type = "discount_percentage"`, `reward_value = 10` (untuk 10%)
Mekanisme	Customer menukarkan poin → mendapat voucher diskon persentase
Berlaku untuk	Satu transaksi atau periode tertentu
Contoh	Tukar 500 poin → diskon 10% untuk transaksi berikutnya

2. Discount Amount (`discount_amount`)

Reward berupa potongan harga dalam nominal Rupiah tetap.

Aspek	Detail
Field	`reward_type = "discount_amount"`, `reward_value = 25000` (untuk Rp 25.000)
Mekanisme	Customer menukarkan poin → mendapat voucher diskon nominal tetap
Berlaku untuk	Satu transaksi dengan minimum pembelian tertentu
Contoh	Tukar 300 poin → diskon Rp 25.000 untuk min. pembelian Rp 100.000

3. Free Product (`free_product`)

Reward berupa produk gratis yang sudah ditentukan.

Aspek	Detail
Field	`reward_type = "free_product"`, `reward_product_id`, `reward_product_name`
Mekanisme	Customer menukarkan poin → mendapat produk spesifik secara gratis
Berlaku untuk	Satu produk yang sudah dikonfigurasi
Contoh	Tukar 200 poin → gratis 1x Es Teh Manis (reward_product_id = “prod_xxx”)

4. None (`none`)

Tidak ada reward yang bisa ditukarkan — tier ini hanya memberikan benefit pasif (diskon otomatis, multiplier, dll).

Aspek	Detail
Field	`reward_type = "none"`
Mekanisme	Customer tidak bisa menukarkan poin, namun tetap mendapat benefit tier
Berlaku untuk	Tier yang hanya mengandalkan benefit pasif
Contoh	Tier Silver: diskon 5% otomatis, tanpa opsi redeem

Perbandingan 4 Jenis Reward

Kriteria	Discount %	Discount Amount	Free Product	None
Fleksibilitas	Tinggi (semua produk)	Tinggi (semua produk)	Rendah (1 produk)	N/A
Prediksi Biaya	Variabel (% dari trx)	Tetap (nominal)	Tetap (HPP produk)	Nol
Daya Tarik	Tinggi	Tinggi	Sangat tinggi (konkret)	Rendah
Kompleksitas	Sedang	Sedang	Tinggi (butuh stock)	Nol
COGS Tracking	Via `finance_record_id`	Via `finance_record_id`	Via `finance_record_id`	Tidak ada

Benefit Konfigurasi

Setiap tier bisa memiliki benefit yang berbeda:

Benefit	Tipe	Deskripsi
Discount %	number	Persentase diskon di POS
Points Multiplier	number	Pengali perolehan poin
Birthday Bonus	boolean	Poin ganda di bulan ulang tahun
Priority Support	boolean	Akses antrian prioritas
Free Delivery	boolean	Gratis ongkos kirim
Custom Benefits	array	Benefit kustom (text)

Contoh Tier

Tier	Discount	Multiplier	Free Delivery	Priority
Silver	5%	1x	—	—
Gold	10%	1.5x	✓	—
Platinum	15%	2x	✓	✓
Diamond	20%	3x	✓	✓

Sequence Diagram: Alur Upgrade Tier

Berikut adalah sequence diagram lengkap untuk proses auto-upgrade dan manual downgrade tier membership:

Auto-Upgrade Flow

Manual Downgrade Flow

Reward Redemption Flow

Fitur Manager

CRUD Tier

Operasi	Deskripsi
Create	Tambah tier baru dengan form
Edit	Ubah konfigurasi tier
Delete	Hapus tier (dengan konfirmasi)

Drag to Reorder

Tier bisa di-drag untuk mengubah urutan prioritas. Urutan ini menentukan level mana yang lebih tinggi dalam hierarki.

Auto-Upgrade

Jika auto_upgrade = true, sistem otomatis menaikkan tier pelanggan saat kriteria terpenuhi:

Integrasi dengan POS

Saat pelanggan melakukan transaksi di POS:

POS lookup customer berdasarkan nama/telepon
Baca membership_level_id dan discount_percentage
Apply diskon otomatis ke total transaksi
Tambah poin/stamp berdasarkan points_multiplier
Cek apakah kriteria upgrade terpenuhi → auto-upgrade jika ya

Stamp Scheme Persistence

Untuk skema stamp, tag SCHEME:STAMP di-inject ke array benefits sebagai mekanisme persistence untuk identifikasi skema.

Penanganan Loyalty Deficit

Ketika transaksi di-void atau diretur setelah poin/stamp sudah terpakai (redeem), sistem mencatat defisit:

Skenario Deficit

Skenario	Kondisi	Penanganan
Void sebelum redeem	Poin masih utuh	Reverse otomatis, saldo kembali normal
Void setelah redeem sebagian	Poin sudah dipakai sebagian	Reverse poin yang tersisa, catat deficit
Void setelah redeem penuh	Poin sudah habis dipakai	Saldo jadi negatif, butuh review manual
Retur produk	Produk dikembalikan	Hitung ulang poin eligible, reverse selisih

Tips Penggunaan

Mulai dengan 3-4 tier agar program loyalty tidak terlalu kompleks
Tetapkan min_purchase yang realistis berdasarkan data historis
Berikan benefit yang berbeda signifikan antar tier untuk motivasi upgrade
Aktifkan auto_upgrade agar pelanggan otomatis naik tier
Review dan sesuaikan kriteria tier setiap kuartal
Gunakan birthday bonus untuk meningkatkan engagement
Manfaatkan CustomerLoyaltyLedger untuk audit trail — setiap mutasi tercatat dengan points_before dan points_after sehingga bisa dilacak sepenuhnya
Untuk skema stamp, pastikan stamp_per_transaction sesuai dengan rata-rata nilai transaksi agar program terasa adil
Gunakan expiry_days untuk mendorong customer aktif menukarkan poin sebelum hangus
Selalu monitor loyalty_deficit_points dan segera lakukan rekonsiliasi manual agar saldo member tetap akurat
Pertimbangkan skema hybrid jika bisnis memiliki multi-channel (dine-in, delivery, marketplace) agar customer punya banyak jalur untuk naik tier

​title: “Membership — Program Loyalty” description: “Manajemen tier membership dengan 5 skema loyalty (spending, stamp, points, visits, hybrid), benefit konfigurasi, dan auto-upgrade di SNISHOP ERP.”

​Membership — Program Loyalty

​Arsitektur

​Akses Halaman

​Diagram Relasi Entitas (ERD)

​Entitas: CustomerMembership (Schema Lengkap)

​Field Identitas & Visual

​Field Benefit & Diskon

​Field Skema Spending

​Field Skema Points

​Field Skema Stamp

​Field Reward

​Field Skema Visits & Kedaluwarsa

​Total: 25 Field

​Entitas: Customer (Field Membership)

​Entitas: CustomerLoyaltyLedger (Audit Trail)

​Field Utama

​Field Saldo (Before/After Snapshot)

​Field Reward & Deficit

​Field Audit

​Entitas: POSMember

​State Machine: Tier Progression

​Transisi State — Detail

​5 Skema Loyalty — Perbandingan Lengkap

​Skema Spending

​Skema Stamp

​Skema Points

​Skema Visits

​Skema Hybrid

​Sistem Reward — 4 Jenis Reward

​1. Discount Percentage (discount_percentage)

​2. Discount Amount (discount_amount)

​3. Free Product (free_product)

​4. None (none)

​Perbandingan 4 Jenis Reward

​Benefit Konfigurasi

​Contoh Tier

​Sequence Diagram: Alur Upgrade Tier

​Auto-Upgrade Flow

​Manual Downgrade Flow

​Reward Redemption Flow

​Fitur Manager

​CRUD Tier

​Drag to Reorder

​Auto-Upgrade

​Integrasi dengan POS

​Stamp Scheme Persistence

​Penanganan Loyalty Deficit

​Skenario Deficit

​Tips Penggunaan