Medusa v2 tabanlı bir storefront’ta cart id yönetimi, line item güncelleme, checkout adımları, hata dili ve özel alanların nasıl tasarlanacağını anlatıyorum.

Medusa V2 ile Checkout ve Sepet Akışı Tasarlamak

Checkout, e-ticaret deneyiminin en hassas yeridir. Kullanıcı ürünleri beğenmiş, sepete eklemiş ve artık karar noktasına gelmiştir. Bu aşamada küçük bir belirsizlik bile terk oranını artırabilir. Bu yüzden checkout tasarımını yalnızca form alanları olarak değil, güven ve ilerleme hissi veren bir akış olarak ele almak gerekir.

Medusa v2 tarafında sepet backend tarafından yönetilir. Storefront cart id’yi saklar ve line item işlemlerini Store API veya JS SDK üzerinden yapar. Bu ayrım önemlidir; çünkü fiyat, indirim, vergi, shipping ve ödeme oturumu gibi hesaplamalar backend tarafında güvenilir biçimde tutulmalıdır.

Cart id stratejisi

Cart id local storage, cookie veya server session üzerinden saklanabilir. Eğer uygulama server action ağırlıklı ilerliyorsa httpOnly cookie daha güvenli bir tercih olabilir. Daha basit storefrontlarda local storage yeterli olabilir; fakat sepet verisinin kendisi frontend’de gerçek kaynak kabul edilmemelidir.

const CART_COOKIE = 'cart_id'

export async function ensureCart(regionId: string) {
  const existing = await getCookie(CART_COOKIE)
  if (existing) return existing

  const { cart } = await sdk.store.cart.create({ region_id: regionId })
  await setCookie(CART_COOKIE, cart.id)
  return cart.id
}

Line item işlemleri

Sepete ürün ekleme, adet güncelleme ve silme işlemleri tek bir servis katmanında toplanmalıdır. Component’ler API detayını bilmemeli; sadece “ekle”, “güncelle”, “sil” gibi aksiyonları çağırmalıdır.

export async function addToCart(input: { cartId: string; variantId: string; quantity: number }) {
  return sdk.store.cart.createLineItem(input.cartId, {
    variant_id: input.variantId,
    quantity: input.quantity,
  })
}

export async function removeFromCart(cartId: string, lineId: string) {
  return sdk.store.cart.deleteLineItem(cartId, lineId)
}

Checkout adımları

Checkout dört ana adıma ayrılabilir: iletişim, teslimat, ödeme ve onay. Bütün alanları tek ekrana yığmak yerine adımları net göstermek kullanıcıyı rahatlatır. Ancak bu adımlar ayrı sayfalar olmak zorunda değildir; aynı sayfa içinde bölümlenmiş bir akış daha hızlı hissettirebilir.

const checkoutSteps = [
  { key: 'contact', label: 'İletişim' },
  { key: 'shipping', label: 'Teslimat' },
  { key: 'payment', label: 'Ödeme' },
  { key: 'review', label: 'Onay' },
]

export function CheckoutProgress({ active }: { active: string }) {
  return (
    <ol className="grid grid-cols-4 gap-2">
      {checkoutSteps.map((step) => (
        <li key={step.key} data-active={step.key === active}>{step.label}</li>
      ))}
    </ol>
  )
}

Hata dili

Checkout hataları teknik dille gösterilmemelidir. “Payment session failed” yerine “Ödeme oturumu yenilenemedi, tekrar deneyin” gibi aksiyon veren bir dil gerekir. Kullanıcıya ne olduğunu ve ne yapması gerektiğini aynı cümlede söylemek terk oranını azaltır.

Özel alanlar

Hediye notu, paketleme türü, teslimat tercihi, kurumsal fatura notu veya özel üretim isteği gibi alanlar çoğu commerce sisteminde standart değildir. Bu alanlar metadata veya custom workflow ile taşınmalıdır. Burada önemli olan formdaki alan ile operasyon panelindeki görevin aynı veri modeline bağlanmasıdır.

Sonuç

Checkout tasarımı güven tasarımıdır. Sepet state’i sağlam, adımlar anlaşılır, hata mesajları insani ve özel alanlar operasyonla bağlantılı olduğunda kullanıcı satın alma kararını daha rahat tamamlar.

Uygulamada dikkat edilmesi gereken detaylar

E-ticaret altyapısında en sık yapılan hata, kullanıcı arayüzünü commerce kurallarından kopuk tasarlamaktır. Ürün kartında görünen fiyat, sepet toplamında hesaplanan fiyatla aynı kaynaktan beslenmelidir. Varyant seçimi, stok durumu, bölge bazlı para birimi ve indirim bilgisi aynı veri modeline bağlanmadığında kullanıcı arayüzü güven kaybeder. Bu yüzden tasarımda görünen her bilgi için backend’de net bir kaynak belirlemek gerekir.

Bir diğer kritik nokta cache stratejisidir. Ürün listeleme sayfaları cachelenebilir; fakat sepet, ödeme, stok uyarısı ve kişiye özel fiyat gibi alanlarda daha dikkatli olunmalıdır. Statik hız ile canlı veri doğruluğu arasında denge kurulmalıdır. Özellikle kampanya dönemlerinde fiyat ve stok bilgisinin yanlış görünmesi, performans sorunundan daha büyük bir problemdir.

Test senaryoları

Canlıya çıkmadan önce yalnızca mutlu akış test edilmemelidir. Varyant stoğu bitince ne oluyor, ödeme oturumu yenilenemeyince kullanıcı ne görüyor, kargo seçeneği yoksa checkout nasıl davranıyor, indirim kodu geçersizse mesaj anlaşılır mı? Bu sorular test planına eklenmelidir.

Ölçüm

Başarıyı yalnızca sipariş sayısıyla ölçmek eksik kalır. Ürün detaydan sepete ekleme oranı, sepette terk oranı, checkout adımı bazlı düşüş, ödeme hatası oranı ve mobil dönüşüm oranı birlikte takip edilmelidir. Bu metrikler hem tasarım hem altyapı kararlarını iyileştirir.

Uygulama planı

Bu yaklaşımı gerçek bir projeye taşırken önce küçük ama doğru çalışan bir çekirdek kurulmalıdır. İlk adım veri modelini netleştirmek, ikinci adım API sözleşmesini belirlemek, üçüncü adım kullanıcı arayüzündeki ana akışı tamamlamak olmalıdır. Bundan sonra otomasyon, çeviri, raporlama veya medya yönetimi gibi ek katmanlar sırayla eklenebilir. Böyle ilerlemek hem geliştirme hızını korur hem de karmaşıklığın erkenden büyümesini engeller.

Ayrıca her teknik kararın kullanıcı veya operasyon karşılığı olmalıdır. Bir tablo, queue, SDK ya da dashboard bileşeni yalnızca teknik olarak doğru olduğu için değil, süreci daha anlaşılır, daha hızlı veya daha ölçülebilir yaptığı için eklenmelidir. Sağlam ürünler bu disiplinle büyür.