Langsung ke konten utama
Storefront API adalah API untuk storefront custom yang berjalan di browser. Gunakan Storefront API saat Anda ingin membuat frontend sendiri dan memakai Scalev sebagai backend untuk katalog, cart, checkout, akun customer, lokasi pengiriman, order, dan payment. Storefront API berbeda dari pengaturan Storefront bawaan. Pengaturan Storefront bawaan mengatur halaman buatan Scalev, custom domain, builder homepage dan checkout, footer pages, OTP, custom HTML, dan analytics. Pengaturan Storefront API dipakai untuk storefront API-only saat Anda mengatur frontend 100%.
Panggil Storefront API v3 langsung dari browserStorefront API v3 dirancang untuk dipanggil langsung dari browser atau client end-user. Jangan menaruh Storefront API v3 di balik backend proxy, reverse proxy, middleware, edge function, serverless function, atau pass-through API layer milik Anda sendiri.Rate limiter untuk Storefront API v3 sengaja dibuat ketat karena API ini dirancang untuk penggunaan client-side langsung. Jika request ini diproxy, banyak user dapat terlihat datang dari IP server yang sama, sehingga rate limiting, deteksi spam, proteksi order duplikat, dan logika validasi lain dapat terdampak negatif.Untuk deployment headless storefront, anggap browser sebagai caller yang dimaksud untuk Storefront API v3. Gunakan backend Anda sendiri hanya untuk hal non-Scalev seperti admin settings, custom business logic, atau private integrations.
Syarat paket berlanggananRequest runtime Storefront API tersedia untuk bisnis dengan paket aktif Basic, Pro, atau Ultimate. Merchant di paket Free atau Lite tetap bisa mengatur public Store ID, API key publishable, dan allowed origin, tetapi panggilan API akan mengembalikan response Store not found yang sama sampai bisnis upgrade atau mengaktifkan lagi paket yang eligible.

​
Urutan baca yang disarankan

  1. Mulai dari halaman ini untuk memahami arsitektur, kebutuhan setup, dan peta endpoint.
  2. Baca Auth untuk Storefront API key, guest cart token, dan customer JWT.
  3. Baca Checkout dan Payment untuk shipping, checkout summary, pembuatan order, dan rendering payment.
  4. Baca Event konversi iklan jika storefront menjalankan iklan Meta, TikTok, atau SnackVideo.
  5. Akhiri dengan Bangun storefront sebagai panduan implementasi lengkap A-Z.

​
Arsitektur

Storefront API storefront bisa berupa static app di Cloudflare Pages, Vercel, Netlify, atau CDN lain. Browser memanggil https://api.scalev.com secara langsung. Gunakan fetch dengan credentials: "omit" untuk panggilan Storefront API dari browser: 
await fetch(`https://api.scalev.com/v3/stores/${storeId}/public/items`, {
  credentials: "omit",
  headers: {
    "X-Scalev-Storefront-Api-Key": storefrontApiKey,
  },
});
Kontinuitas guest cart memakai token header yang dikelola browser, bukan cookie cross-site. Lihat Auth untuk model Storefront API key, guest token, dan customer JWT.

​
Yang perlu diatur

Di dashboard, buka halaman konfigurasi store dan gunakan bagian Storefront API. Salin public Store ID. Integrasi baru sebaiknya memakai unique_id store, contoh: 
store_vlzpML8edzxO5roOdV7Oyfn6
Buat Storefront API key yang publishable: 
sfpk_...
Daftarkan setiap origin browser yang akan memanggil API: 
https://demo.scalev.shop
http://localhost:3000
CORS preflight untuk origin yang diizinkan mencakup X-Scalev-Storefront-Api-Key, X-Scalev-Guest-Token, Authorization, dan Content-Type.

​
Endpoint utama

GET  /v3/stores/{store_id}/public/items
GET  /v3/stores/{store_id}/public/items/count
GET  /v3/stores/{store_id}/public/products/{slug}
GET  /v3/stores/{store_id}/public/bundle-price-options/{slug}
GET  /v3/stores/{store_id}/public/categories
GET  /v3/stores/{store_id}/public/payment-methods

GET  /v3/stores/{store_id}/public/locations/provinces
GET  /v3/stores/{store_id}/public/locations/cities?province_id=31
GET  /v3/stores/{store_id}/public/locations/subdistricts?city_id=3171
GET  /v3/stores/{store_id}/public/locations?search=Cempaka%20Putih
GET  /v3/stores/{store_id}/public/locations/{location_id}/postal-codes

GET  /v3/stores/{store_id}/public/cart
POST /v3/stores/{store_id}/public/cart/items
PATCH /v3/stores/{store_id}/public/cart/items/{item_id}
DELETE /v3/stores/{store_id}/public/cart/items/{item_id}

POST /v3/stores/{store_id}/public/checkout/shipping-options
POST /v3/stores/{store_id}/public/checkout/summary
POST /v3/stores/{store_id}/public/checkout
GET  /v3/stores/{store_id}/public/orders/{secret_slug}
PATCH /v3/stores/{store_id}/public/orders/{secret_slug}
POST /v3/stores/{store_id}/public/orders/{secret_slug}/payment
POST /v3/stores/{store_id}/public/orders/{secret_slug}/transfer-proof-upload
POST /v3/stores/{store_id}/public/discount-codes/check

POST /v3/stores/{store_id}/public/analytics/meta/events
POST /v3/stores/{store_id}/public/analytics/tiktok/events
POST /v3/stores/{store_id}/public/analytics/snackvideo/events
Search location memakai cursor pagination. Saat has_next bernilai true, gunakan next_cursor untuk mengambil halaman berikutnya.

​
Alur checkout browser-only

  1. Muat katalog dengan GET /public/items, GET /public/categories, dan route detail.
  2. Buat atau baca guest cart dengan GET /public/cart; simpan X-Scalev-Guest-Token dari response.
  3. Kirim X-Scalev-Guest-Token pada request add, update, remove, checkout, dan pembacaan cart berikutnya.
  4. Ambil opsi checkout dengan GET /public/payment-methods dan endpoint public location/postal-code.
  5. Daftar opsi pengiriman dengan POST /public/checkout/shipping-options. Direct items bertipe menjadi sumber item jika dikirim; jika tidak, gunakan X-Scalev-Guest-Token untuk guest cart.
  6. Hitung ulang total dengan POST /public/checkout/summary setelah pembeli memilih courier service dan metode pembayaran. API mengabaikan shipping_cost dari client dan menghitung ulang dari courier service, warehouse, metode pembayaran, destinasi, dan item checkout.
  7. Opsional, validasi kode diskon dengan POST /public/discount-codes/check. Kirim { "code": "..." } di body request, bersama konteks checkout opsional (items, payment_method, destination, courier_service_id, warehouse_unique_id, courier_aggregator_code, net_product_price, gross_revenue, shipping_cost). Kode yang tidak dikenal atau tidak memenuhi syarat mengembalikan is_eligible: false; route hanya mengembalikan 404 jika store tidak ditemukan.
  8. Buat order dengan POST /public/checkout memakai direct items bertipe, guest cart token, atau keduanya.
  9. Baca order melalui GET /public/orders/{secret_slug} dan update field buyer seperti transferproof_url, transfer_time, atau notes dengan PATCH /public/orders/{secret_slug}.
  10. Untuk manual bank_transfer, minta URL upload bukti transfer dengan POST /public/orders/{secret_slug}/transfer-proof-upload, upload image, lalu patch order dengan file_url yang dikembalikan.
  11. Panggil POST /public/orders/{secret_slug}/payment; render instruksi payment yang dikembalikan atau yang sudah ada di payment page Anda sendiri, dan gunakan payment_url hanya sebagai hosted fallback.
  12. Untuk akun customer, mulai dari /public/auth/login, lalu panggil /customers/me/* dengan customer JWT.
Lihat Checkout dan Payment untuk panduan shipping option, summary, dan rendering payment per metode.

​
Analytics Conversion API

Gunakan Scalev sebagai server-side relay untuk event konversi Meta, TikTok, dan SnackVideo dari storefront browser. Panggilan ini memakai pixel yang sama dengan konfigurasi Storefront analytics bawaan, tetapi route Storefront API memilih toko dari /v3/stores/{store_id} dan X-Scalev-Storefront-Api-Key; jangan mengirim custom domain untuk mengidentifikasi toko. 
POST /v3/stores/{store_id}/public/analytics/meta/events
POST /v3/stores/{store_id}/public/analytics/tiktok/events
POST /v3/stores/{store_id}/public/analytics/snackvideo/events
Endpoint mengembalikan 204 No Content setelah menerima payload untuk dikirim secara asynchronous. Lihat Event konversi iklan untuk setup client pixel, cookie atribusi, penamaan event, contoh payload, dan deduplikasi Meta/TikTok.

​
Response payment

Setelah guest checkout, membaca public order, atau membuat instruksi payment, response berisi data order ringkas yang dibutuhkan storefront untuk menampilkan langkah berikutnya ke pembeli: identity order, public_order_url, payment_url, status, total, object map variants dan bundle_price_options yang sudah ada, line item, detail pengiriman, dan field payment seperti payment_method, sub_payment_method, payment_account_holder, payment_account_number, transferproof_url, dan pg_payment_info. Response ini sengaja tidak mengembalikan ID order internal, revenue khusus dashboard, platform fee, payment-status history, dan atribusi affiliate. Di v3, field tersebut ada langsung di object JSON, bukan di dalam envelope data lama. Route order akun customer mengembalikan data order yang lebih kecil dan aman untuk customer yang sedang login. Response ini mempertahankan data order yang terlihat oleh pembeli dan menghapus detail khusus dashboard seperti analytics bisnis, fee internal, provider internals, riwayat CRM, data affiliate, dan raw metadata. Endpoint payment public bersifat idempotent saat instruksi pembayaran atau payment_url sudah tersedia. Response payment menjelaskan cara storefront merender langkah pembayaran berikutnya. Metode manual seperti bank_transfer dan cod dapat mengembalikan pg_payment_info kosong sementara public order yang membawa instruksi buyer untuk dirender. Virtual account mengembalikan referensi provider dan detail akun di bawah objek payment_method provider. QRIS mengembalikan data QR atau payload QR image. E-wallet, card, dan invoice dapat mengembalikan provider actions atau URL hosted provider. Storefront sebaiknya merender halaman pembayarannya sendiri dari field tersebut dan memakai payment_url hanya sebagai hosted fallback.

​
Setup API

Endpoint setup memerlukan akses bisnis terautentikasi. Gunakan public Store ID untuk client baru; numeric store ID lama masih diterima. 
GET    /v3/stores/{store_id}/public-api-keys
POST   /v3/stores/{store_id}/public-api-keys
DELETE /v3/stores/{store_id}/public-api-keys/{id}

GET    /v3/stores/{store_id}/storefront/allowed-origins
POST   /v3/stores/{store_id}/storefront/allowed-origins
DELETE /v3/stores/{store_id}/storefront/allowed-origins/{id}