Sipariş eventleri
order.paid, order.updated ve order.shipmentUpdated — alanlar, örnekler ve kullanım desenleri.
| Event | Ne zaman tetiklenir |
|---|---|
order.paid | Ödeme başarıyla tamamlandı |
order.updated | Siparişin kendi durumu COMPLETED, REFUNDED veya CANCELLED oldu |
order.shipmentUpdated | Siparişin kargo durumu değişti |
flowchart LR
A["Müşteri ödeme yapar"] --> B["order.paid"]
B --> C["ReadyForShipment"] --> D["Fulfilled"] --> E["CargoDelivered"]
C -.->|"her geçişte order.shipmentUpdated"| C
D -.-> D
E -.-> E
E ==>|"order.updated (COMPLETED)"| F["Sipariş kapandı"]
order.paid
En çok kullanılan event. Müşteri ödemesini tamamladı; ürünü/hakkı verebilirsiniz.
Gövde doğrudan sipariş nesnesidir, zarf yoktur. Event tipi, event kimliği ve
zaman damgası gövdede değil Hikie-Event, Hikie-Webhook-Id ve
Hikie-Timestamp başlıklarında gelir.
{
"orderId": "17716204135268844HKS",
"status": "COMPLETED",
"storeSlug": "magazam",
"dateCreated": "2026-08-07T09:18:11.000Z",
"currency": "TRY",
"totals": {
"subtotal": "274.90",
"shipping": "0.00",
"discount": "25.00",
"total": "249.90"
},
"discounts": [
{ "discountId": null, "code": "HOSGELDIN25", "amount": null }
],
"customerInfo": {
"firstName": "Ayşe",
"lastName": "Yılmaz",
"email": "[email protected]",
"phone": "+905321234567",
"address": "Bağdat Cad. No 12 D:4",
"district": "Kadıköy",
"city": "İstanbul",
"state": null,
"postcode": "34710",
"country": "TR"
},
"billingInfo": null,
"items": [
{
"itemId": "66b1efd21c9a4e0021f3ab77",
"title": "VIP Paket",
"type": "DIGITAL",
"variant": { "sku": null, "name": "30 gün" },
"quantity": 1,
"unitPrice": "274.90",
"total": "274.90",
"isUpsell": false,
"stockQuantity": 99
}
],
"isLink": true,
"linkId": "6ab6863dcee0c259bab710a7",
"merchantOrderId": "SIP-100245",
"attribution": {
"utm_source": "ig",
"utm_medium": "paid",
"utm_campaign": "120252123399970114",
"fbclid": "IwAR2x...",
"landing": "https://www.hikie.space/magazam/vip-paket"
},
"isRecurring": false,
"isSubscriptionStart": true,
"subscriptionSourceOrderId": null,
"subscriptionCycle": 1,
"cargo": null
}Alanlar
Alan
Tip
Abonelik satın alımları
order.paid abonelik ödemelerini de taşır; başka bir event'e gerek kalmadan üç
durumu ayırt edebilirsiniz:
| Durum | isSubscriptionStart | isRecurring |
|---|---|---|
| Tek seferlik veya ücretsiz satın alım | false | false |
| Aboneliğin ilk ödemesi | true | false |
| Otomatik yenileme | false | true |
async function onOrderPaid(order) {
if (order.isRecurring) {
// Yenileme — mevcut üyeyi uzatın, hoş geldin akışını yeniden işletmeyin.
return extendAccess(order.subscriptionSourceOrderId, order.subscriptionCycle);
}
if (order.isSubscriptionStart) {
return grantAccess(order.customerInfo.email, order.orderId);
}
}Başarısız yenilemeler ve iptaller ayrı event olarak gelir — bkz. Abonelik eventleri.
items[] alanları
Alan
Tip
stockQuantity asla uydurma bir değer taşımaz. Kalemin ürünü herhangi bir
sebeple çözülemiyorsa null gelir — asla yanlış bir 0 değil.
attribution
Müşteri mağazanıza bir reklam veya kampanya linkiyle geldiyse, o tıklamanın
parametreleri siparişe taşınır. Düz bir string → string haritasıdır; yalnızca
dolu olan anahtarlar gelir.
| Anahtar | Ne taşır |
|---|---|
utm_source, utm_medium, utm_campaign, utm_content, utm_term, utm_id | Linkteki UTM parametreleri |
fbclid, gclid, ttclid, msclkid | Meta, Google, TikTok ve Microsoft tıklama kimlikleri |
ref | Linkteki ref parametresi |
session | Checkout Link oturum kimliği (linkte varsa) |
landing | Müşterinin ilk indiği sayfa, sorgu parametreleri olmadan |
referer | Müşteriyi gönderen sayfa, sorgu parametreleri olmadan |
Atıf ilk tıklamaya göre yapılır ve mağaza başına 30 gün geçerlidir: müşteri
reklamdan gelip günler sonra doğrudan dönerek alsa da sipariş ilk reklama
yazılır. Reklam parametresi olmayan (organik) siparişlerde alan null gelir.
Kart bilgisi ve kart token'ı payload'a dâhil edilmez.
Kullanım
async function onOrderPaid(data) {
// Ödenen toplam: indirim ve kargo totals.total'a yansımıştır.
console.log(`${data.customerInfo?.email} → ${data.totals.total} ${data.currency}`);
for (const item of data.items) {
// variant, hangi paketin alındığını söyler
const paket = item.variant?.name ?? item.title;
for (let i = 0; i < item.quantity; i++) {
await grantPackage(data.customerInfo?.email, paket);
}
}
}item.quantity alanını atlamayın. Müşteri aynı paketten 3 adet aldıysa
quantity: 3 gelir ve tek kalem olarak listelenir.
order.updated
Siparişin kendi durumu değişti — kargo durumu değil. Yalnızca üç geçişte tetiklenir:
Alan
Tip
Ara durumlar (PENDING, PROCESSING, FAILED, kısmi iadeler) bu event'i
üretmez. Özellikle PROCESSING, size zaten bir
order.shipmentUpdated gönderen kargo adımının yansımasıdır — aynı hareketi
iki kez işlemiş olurdunuz.
{
"orderId": "17716204135268844HKS",
"status": "REFUNDED",
"previousStatus": "COMPLETED",
"storeSlug": "magazam",
"dateCreated": "2026-08-07T09:18:11.000Z",
"currency": "TRY",
"totals": {
"subtotal": "274.90",
"shipping": "0.00",
"discount": "25.00",
"total": "249.90"
},
"discounts": [
{ "discountId": null, "code": "HOSGELDIN25", "amount": null }
],
"customerInfo": {
"firstName": "Ayşe",
"lastName": "Yılmaz",
"email": "[email protected]",
"phone": "+905321234567",
"address": "Bağdat Cad. No 12 D:4",
"district": "Kadıköy",
"city": "İstanbul",
"state": null,
"postcode": "34710",
"country": "TR"
},
"billingInfo": null,
"items": [
{
"itemId": "66b1efd21c9a4e0021f3ab77",
"title": "VIP Paket",
"type": "DIGITAL",
"variant": { "sku": null, "name": "30 gün" },
"quantity": 1,
"unitPrice": "274.90",
"total": "274.90",
"isUpsell": false,
"stockQuantity": 99
}
],
"attribution": null
}order.paid ile aynı şekil (isLink, linkId, merchantOrderId ve abonelik alanları hariç); bir alan fazlası, kargo tarafı eksiği:
Alan
Tip
shipmentStatus, previousShipmentStatus ve cargo bilerek yok. Bu
event siparişin ticari durumunu bildiriyor; kargo tarafı
order.shipmentUpdated'in işi. Tek bir teslimat ya da iptal size iki
event'i birden gönderir — entegrasyonunuzun ilgilendiğini okuyun.
async function onOrderUpdated(data) {
switch (data.status) {
case 'COMPLETED':
return erişimVer(data);
case 'REFUNDED':
case 'CANCELLED':
// İndirim totals.total içinde zaten yansımış durumda.
return erişimKaldır(data.orderId, data.totals.total);
}
}Ne için: iade/iptalde erişim kaldırma, muhasebe, kendi tarafınızda siparişi kapatma.
order.shipmentUpdated
Siparişin kargo durumu değişti. Her geçişte tetiklenir.
Alan
Tip
{
"orderId": "17716204135268844HKS",
"status": "COMPLETED",
"shipmentStatus": "CargoDelivered",
"previousShipmentStatus": "Fulfilled",
"storeSlug": "magazam",
"dateCreated": "2026-08-07T09:18:11.000Z",
"currency": "TRY",
"totals": {
"subtotal": "274.90",
"shipping": "0.00",
"discount": "25.00",
"total": "249.90"
},
"discounts": [
{ "discountId": null, "code": "HOSGELDIN25", "amount": null }
],
"customerInfo": {
"firstName": "Ayşe",
"lastName": "Yılmaz",
"email": "[email protected]",
"phone": "+905321234567",
"address": "Bağdat Cad. No 12 D:4",
"district": "Kadıköy",
"city": "İstanbul",
"state": null,
"postcode": "34710",
"country": "TR"
},
"billingInfo": null,
"items": [
{
"itemId": "66b1efd21c9a4e0021f3ab77",
"title": "VIP Paket",
"type": "DIGITAL",
"variant": { "sku": null, "name": "30 gün" },
"quantity": 1,
"unitPrice": "274.90",
"total": "274.90",
"isUpsell": false,
"stockQuantity": 99
}
],
"attribution": null,
"cargo": {
"company": "Yurtiçi Kargo",
"trackingNumber": "YK123456789TR",
"trackingUrl": "https://takip.example/YK123456789TR",
"status": "CargoDelivered",
"fulfilledAt": "2026-08-09T08:05:00.000Z",
"deliveredAt": "2026-08-11T13:47:22.000Z"
}
}order.paid ile aynı yapı (isLink, linkId, merchantOrderId ve abonelik alanları hariç), artı iki alan:
Alan
Tip
Sipariş ilk kez Fulfilled durumuna gelene kadar cargo alanı null'dır;
o andan sonra kargo firmasını, takip numarasını ve URL'sini taşır.
async function onOrderUpdated(data) {
if (data.shipmentStatus === 'CargoDelivered') {
await notifyCustomer(data.customerInfo?.email, 'Siparişiniz teslim edildi.');
}
await db.updateShipmentStatus(data.orderId, data.shipmentStatus);
}Ne için kullanılır: kargo takip bildirimleri, müşteriye dönük sipariş durumu sayfaları.
Tekrar ve sıralama
| Event | Tekrar davranışı |
|---|---|
order.paid | Fatura başına bir kez — ödeme sağlayıcısı iki farklı yoldan bildirse bile tek istek gider |
order.updated | Fatura başına, durum başına bir kez — yalnızca COMPLETED, REFUNDED ve CANCELLED için; aynı duruma tekrar geçiş ikinci bir bildirim üretmez |
order.shipmentUpdated | Fatura başına, kargo durumu başına bir kez — aynı duruma tekrar geçiş (idempotent güncelleme, elle düzeltme) ikinci bir bildirim üretmez |
Bir sipariş, ömrü boyunca birden çok order.shipmentUpdated geçişinden
geçer; her biri ayrı bir teslimattır. Teslimat ya da iptal, kargo event'inin
yanında bir de order.updated gönderir — ikisi ayrı teslimattır ve hangisinin
önce geleceği garanti değildir. Sipariş durumunu kendi tarafınızda tutuyorsanız
Hikie-Occurred-At başlığıyla sıralayın — ayrı teslimatlar arasında sıra garanti değildir.
Bkz. Tekrarları yönetmek.