API Penggunaan Kupon (Redeem)

API Penggunaan Kupon Vivoldi (Redeem) memungkinkan Anda menandai kupon sebagai telah digunakan.

Tanpa perlu proses manual di dashboard, penggunaan dapat diproses secara otomatis melalui API.
Setiap permintaan akan mengurangi jumlah penggunaan yang tersisa, dan setelah batas tercapai, penggunaan selanjutnya akan diblokir.

API ini tersedia mulai dari paket Personal.

PUT

/api/coupon/v1/redeem 

{
    "cpnNo": "ZJLF0399WQBEQZJM",
    "userId": "x77hu",
    "memo": "IP Address: 210.123.111.222, Request Page: https://example.com/shop/bags/p112233"
}

Request Parameters

cpnNo string required
Nomor kupon.
onsitePwd string
Kata sandi kupon di lokasi. Wajib diisi jika kupon di lokasi memiliki kata sandi.
userId string
ID pengguna. Digunakan untuk mengidentifikasi penerbit/pengguna kupon.
Harus diisi jika batas penggunaan kupon ditetapkan antara 2–5.
memo string
Catatan referensi internal. Dapat digunakan untuk mencatat IP pengguna, lokasi penggunaan kupon, atau informasi lainnya.
Jika penggunaan kupon tidak terbatas, catatan ini dapat digunakan sebagai pengganti userId untuk membedakan pengguna. 
{
    "code": 0,
    "message": "",
    "result": null
}

Response Parameters

code integer
Kode respons: 0 = Berhasil, nilai lainnya = Error
message string
Pesan respons. Jika kode bukan 0, pesan error akan dikembalikan.
result null

Cara menggunakan dengan API validasi

Karena API penggunaan kupon mengubah status, disarankan untuk memverifikasi terlebih dahulu menggunakan API validasi sebelum memanggilnya.

Dengan memastikan kupon valid sebelumnya, Anda dapat menghindari pemrosesan yang tidak perlu pada kupon yang sudah kedaluwarsa atau telah digunakan.

Alur standar adalah: validasi → penggunaan.

Kapan menggunakan API ini

Gunakan API ini saat Anda perlu menerapkan kupon setelah validasi.

  • Menandai kupon sebagai digunakan setelah pembayaran berhasil
  • Mencatat penggunaan diskon saat pesanan dikonfirmasi
  • Menangani penggunaan di toko atau secara offline
  • Memperbarui status untuk mencegah penggunaan ganda

Dengan kata lain, ini adalah tahap akhir saat kupon benar-benar digunakan.

Alur penggunaan kupon

Kupon ditandai sebagai telah digunakan berdasarkan kode (cpnNo).

  • Jumlah penggunaan langsung berkurang saat digunakan
  • Kupon berubah menjadi tidak dapat digunakan kembali
  • Penggunaan dicatat berdasarkan data pengguna (userId)
  • Log tambahan dapat disimpan melalui memo

Proses ini bukan sekadar perubahan status, tetapi transaksi penting yang terkait dengan proses pembayaran.

Identifikasi pengguna dan penggunaan memo

userId digunakan untuk mengidentifikasi pengguna yang menggunakan kupon.

Jika kupon memiliki batas penggunaan 2–5 kali, nilai ini wajib diisi dan mencegah penggunaan ganda oleh pengguna yang sama.

Field memo dapat digunakan untuk mencatat informasi internal seperti IP pengguna, lokasi penggunaan, atau sumber permintaan.
Jika tidak ada batas penggunaan, memo juga dapat digunakan sebagai alternatif userId untuk membedakan pengguna.

Pengelolaan password kupon onsite

Field onsitePwd wajib diisi jika kupon memiliki password.

Biasanya digunakan di toko atau lokasi offline, di mana staf memverifikasi password sebelum memproses penggunaan kupon.

Contoh penggunaan

  • Integrasi e-commerce: Panggil API saat pembayaran selesai untuk otomatis menerapkan kupon dan mencatat diskon
  • Penggunaan di toko: Staf memindai QR, mendapatkan kode kupon, lalu menggunakan API untuk memprosesnya secara instan
  • Pelacakan penggunaan: Simpan IP dan sumber permintaan di memo untuk analisis penyalahgunaan
  • Kontrol penggunaan ganda: Gunakan userId untuk mencegah pengguna yang sama melebihi batas penggunaan

Kode kupon yang sama dapat digunakan kembali untuk membuat kupon baru setelah dihapus.

Hal yang perlu diperhatikan

  • Selalu panggil API ini setelah validasi untuk memastikan keamanan.
  • Setelah digunakan, kupon tidak dapat digunakan kembali.
  • Strategi rollback mungkin diperlukan jika pembayaran gagal.
  • Implementasikan mekanisme untuk mencegah penggunaan ganda akibat permintaan berulang.