hikiehikieDeveloper Documentation
Eventler

Sipariş eventleri

order.paid, order.updated ve order.shipmentUpdated — alanlar, örnekler ve kullanım desenleri.

EventNe zaman tetiklenir
order.paidÖdeme başarıyla tamamlandı
order.updatedSiparişin kendi durumu COMPLETED, REFUNDED veya CANCELLED oldu
order.shipmentUpdatedSipariş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.

order.paid
{
  "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:

DurumisSubscriptionStartisRecurring
Tek seferlik veya ücretsiz satın alımfalsefalse
Aboneliğin ilk ödemesitruefalse
Otomatik yenilemefalsetrue
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.

AnahtarNe taşır
utm_source, utm_medium, utm_campaign, utm_content, utm_term, utm_idLinkteki UTM parametreleri
fbclid, gclid, ttclid, msclkidMeta, Google, TikTok ve Microsoft tıklama kimlikleri
refLinkteki ref parametresi
sessionCheckout Link oturum kimliği (linkte varsa)
landingMüşterinin ilk indiği sayfa, sorgu parametreleri olmadan
refererMüş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.

order.updated
{
  "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

order.shipmentUpdated
{
  "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

EventTekrar davranışı
order.paidFatura başına bir kez — ödeme sağlayıcısı iki farklı yoldan bildirse bile tek istek gider
order.updatedFatura 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.shipmentUpdatedFatura 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.

Bu sayfada