# İndirim Kuponları

https://dev.wisecp.com/tr/indirim-kuponlari

İndirim kuponlarını tanımlayan, çoğaltan ve koşullarını yöneten yedi uç.

## Genel Bakış

Kuponlar müşterinin sepette ya da faturada kullandığı **indirim kodlarıdır**. Bir kupon ya yüzde ya da sabit tutar indirir; hangisi olduğu tip alanında yazar ve karşılığı gelen alan doldurulur.

Kuponun ne zaman geçerli olduğu **üç şeye** bağlıdır: kayıtlı durumu, tarih aralığı ve kullanım sınırı. Liste ucu bu üçünü birleştirip gerçek durumu ayrıca döndürür; müşterinin karşılaştığı da odur.

Koşullar bundan sonrası için: hangi ürünlerde, hangi dönemlerde, hangi müşteri grubunda ve en az ne kadarlık sepette geçerli olduğu. Ürün değerlerinin listesi **ayrı bir uçtan** alınır.

## Referans

### Kuponları Listeleme

get/api/v1/admin/financial/coupons

`Financial/GetCoupons` admin

İndirim kuponlarını gerçek durumlarıyla döndürür.

Sorgu 4

pageintKaçıncı sayfa.

limitintSayfa başına kayıt. Bir ile yüz arasına çekilir.

searchstringKodda ve notlarda arar.

statusstringGerçek duruma göre süzer: etkin, kapalı, henüz başlamamış, süresi dolmuş ya da sınırı dolmuş.

Dönen alanlar data[] — 15 + meta — 4

idintKuponun numarası.

codestringMüşterinin gireceği kod.

statusstringKayıtlı durum: etkin ya da kapalı.

effective_statusstringGerçek durum. Tarih ve kullanım sınırı hesaba katılarak bulunur.

typestringİndirim tipi.

ratefloatYüzde indirim oranı.

amountfloatSabit indirim tutarı.

currency_idintSabit indirimin para birimi.

auto_applyboolKendiliğinden uygulanıp uygulanmadığı.

max_usesintKullanım sınırı.

usesintŞimdiye kadar kaç kez kullanıldığı.

start_datestring | nullGeçerliliğin başladığı an.

due_datestring | nullGeçerliliğin bittiği an.

created_atstring | nullOluşturulma anı.

totalintSüzgece uyan toplam kupon. Meta altında döner.

pageintBulunulan sayfa.

limitintSayfa boyutu.

next_pageintSonraki sayfa. Sıfır, son sayfadasınız demektir.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/financial/coupons?status=active' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const url = new URL('https://panel.ornek.com/api/v1/admin/financial/coupons');
url.searchParams.set('status', 'active');

const res  = await fetch(url, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/coupons?' . http_build_query(['status' => 'active']));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Iki durum alani vardir: kayitli olan ile GERCEK olan. Musteriyi ikincisi ilgilendirir.
$rows = Api::Financial()->GetCoupons()['data'];
$live = array_filter($rows, fn ($c) => $c['effective_status'] === 'active');
```

### Kupon Oluşturma

post/api/v1/admin/financial/coupons

`Financial/CreateCoupon` admin etkin doğar

Yeni bir indirim kuponu tanımlar.

Gövde 26

codestringreqMüşterinin gireceği kod. Kurulumda benzersiz olmalı.

typestringİndirim tipi: `percentage` ya da `amount`. Öntanımlı olarak yüzde.

ratefloatYüzde indirim oranı.

amountfloatSabit indirim tutarı.

currency_idintSabit indirimin para birimi.

product_servicesstring[]Kuponun geçerli olduğu ürünler, kategoriler, alan adı uzantıları ve ek hizmetler.

required_productsstring[]Sepette bulunması gereken ürünler.

validity_cyclesobjectKuponun geçerli olduğu ödeme dönemleri.

required_product_cyclesobjectGerekli ürünlerin dönemleri.

min_amountfloatKuponun çalışması için gereken en düşük sepet tutarı.

min_amount_currency_idintEn düşük tutarın para birimi.

max_usesintToplam kullanım sınırı. Sıfır, sınırsız demektir.

recurringboolİndirimin yenilemelerde de sürüp sürmediği.

recurring_numintKaç yenilemede süreceği.

auto_applyboolSepete kendiliğinden uygulanır.

apply_onceboolBir müşteride bir kez uygulanır.

onetime_use_per_orderboolBir siparişte bir kez uygulanır.

tax_freeboolİndirimi vergiden muaf sayar.

new_signups_onlyboolYalnız yeni üyelere açar.

existing_customers_onlyboolYalnız mevcut müşterilere açar.

dealership_onlyboolYalnız bayilere açar.

allow_mergeboolBaşka kuponlarla birlikte kullanılabilir.

used_in_invoicesboolFaturalarda da kullanılabilir.

start_datestringGeçerliliğin başladığı an.

due_datestringGeçerliliğin bittiği an. Boş bırakılırsa süresizdir.

notesstringKupona düşülen not.

Dönen alanlar 201 — data

dataobjectOluşan kupon. Detay ucuyla aynı şekildedir.

Hatalar 4

code_required422Kupon kodu boş.

coupon_save_failed422Kod başka bir kuponda kullanılıyor ya da oran geçersiz.

blocked_by_gate422Bir kanca kaydı reddetti.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/financial/coupons' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"code":"HOSGELDIN30","type":"percentage","rate":30,"max_uses":50}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/financial/coupons', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'WELCOME30',
    type: 'percentage',
    rate: 30,
    max_uses: 50,
    due_date: '2026-12-31',
  }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/coupons');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'code'     => 'WELCOME30',
        'type'     => 'percentage',
        'rate'     => 30,
        'max_uses' => 50,
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Kupon ETKIN dogar ve bitis tarihi verilmezse SURESIZ olur; ikisini birlikte dusunun.
Api::Financial()->CreateCoupon([
    'code'     => 'WELCOME30',
    'rate'     => 30,
    'max_uses' => 50,
    'due_date' => '2026-12-31',
]);
```

### Ürün Ağacını Getirme

get/api/v1/admin/financial/coupons/products-hierarchy

`Financial/GetCouponProductsHierarchy` admin

Kuponun bağlanabileceği ürün ve kategorilerin listesini döndürür.

Dönen alanlar data

dataarraySeçilebilir ürün, kategori, alan adı uzantısı ve ek hizmetlerin düz listesi. Kupon alanlarına yazılacak değerler buradan alınır.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/financial/coupons/products-hierarchy' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/financial/coupons/products-hierarchy', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/coupons/products-hierarchy');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Degerleri koda gomme: kurulumun urunleri degistikce bu liste de degisir.
$options = Api::Financial()->GetCouponProductsHierarchy()['data'];
```

### Kupon Detayı

get/api/v1/admin/financial/coupons/{id}

`Financial/GetCoupon` admin

Tek bir kuponu bütün koşullarıyla döndürür.

Dönen alanlar data — 29

idintKuponun numarası.

codestringMüşterinin gireceği kod.

statusstringKayıtlı durum.

typestringİndirim tipi.

ratefloatYüzde indirim oranı.

amountfloatSabit indirim tutarı.

currency_idintSabit indirimin para birimi.

product_servicesstring[]Kuponun geçerli olduğu ürünler.

validity_cyclesobjectGeçerli olduğu ödeme dönemleri.

required_productsstring[]Sepette bulunması gereken ürünler.

required_product_cyclesobjectGerekli ürünlerin dönemleri.

min_amountfloatEn düşük sepet tutarı.

min_amount_currency_idintEn düşük tutarın para birimi.

auto_applyboolKendiliğinden uygulanıp uygulanmadığı.

max_usesintKullanım sınırı.

usesintKaç kez kullanıldığı.

recurringboolYenilemelerde sürüp sürmediği.

recurring_numintKaç yenilemede süreceği.

apply_onceboolMüşteri başına bir kez uygulandığı.

onetime_use_per_orderboolSipariş başına bir kez uygulandığı.

tax_freeboolİndirimin vergiden muaf sayıldığı.

new_signups_onlyboolYalnız yeni üyelere açık olduğu.

existing_customers_onlyboolYalnız mevcut müşterilere açık olduğu.

dealership_onlyboolYalnız bayilere açık olduğu.

allow_mergeboolBaşka kuponlarla birlikte kullanılabildiği.

used_in_invoicesboolFaturalarda kullanılabildiği.

notesstringKupona düşülen not.

start_datestring | nullGeçerliliğin başladığı an.

due_datestring | nullGeçerliliğin bittiği an.

created_atstring | nullOluşturulma anı.

Hatalar 2

not_found404Kupon bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/financial/coupons/19' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch(`https://panel.ornek.com/api/v1/admin/financial/coupons/${id}`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/coupons/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Detayda GERCEK durum alani YOKTUR; onu yalniz liste hesaplar.
$coupon = Api::Financial()->GetCoupon(['id' => $id])['data'];
```

### Kuponu Güncelleme

patch/api/v1/admin/financial/coupons/{id}

`Financial/UpdateCoupon` admin

Kuponun gönderdiğiniz alanlarını değiştirir.

Gövde 26

codestringMüşterinin gireceği kod.

typestringİndirim tipi: `percentage` ya da `amount`. Öntanımlı olarak yüzde.

ratefloatYüzde indirim oranı.

amountfloatSabit indirim tutarı.

currency_idintSabit indirimin para birimi.

product_servicesstring[]Kuponun geçerli olduğu ürünler, kategoriler, alan adı uzantıları ve ek hizmetler.

required_productsstring[]Sepette bulunması gereken ürünler.

validity_cyclesobjectKuponun geçerli olduğu ödeme dönemleri.

required_product_cyclesobjectGerekli ürünlerin dönemleri.

min_amountfloatKuponun çalışması için gereken en düşük sepet tutarı.

min_amount_currency_idintEn düşük tutarın para birimi.

max_usesintToplam kullanım sınırı. Sıfır, sınırsız demektir.

recurringboolİndirimin yenilemelerde de sürüp sürmediği.

recurring_numintKaç yenilemede süreceği.

auto_applyboolSepete kendiliğinden uygulanır.

apply_onceboolBir müşteride bir kez uygulanır.

onetime_use_per_orderboolBir siparişte bir kez uygulanır.

tax_freeboolİndirimi vergiden muaf sayar.

new_signups_onlyboolYalnız yeni üyelere açar.

existing_customers_onlyboolYalnız mevcut müşterilere açar.

dealership_onlyboolYalnız bayilere açar.

allow_mergeboolBaşka kuponlarla birlikte kullanılabilir.

used_in_invoicesboolFaturalarda da kullanılabilir.

start_datestringGeçerliliğin başladığı an.

due_datestringGeçerliliğin bittiği an. Boş bırakılırsa süresizdir.

notesstringKupona düşülen not.

Dönen alanlar data

dataobjectGüncel kupon. Detay ucuyla aynı şekildedir.

Hatalar 4

not_found404Kupon bulunamadı.

coupon_save_failed422Kod başka bir kuponda kullanılıyor ya da oran geçersiz.

blocked_by_gate422Bir kanca kaydı reddetti.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X PATCH 'https://panel.ornek.com/api/v1/admin/financial/coupons/19' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"rate":25,"due_date":"2027-01-31"}'
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/financial/coupons/${id}`, {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ rate: 25, due_date: '2027-01-31', auto_apply: true }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/coupons/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['rate' => 25, 'due_date' => '2027-01-31']),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Orani degistirmek GECMIS siparislere islemez; yalniz bundan sonraki kullanimlari etkiler.
Api::Financial()->UpdateCoupon(['id' => $id, 'rate' => 25]);
```

### Kuponu Silme

delete/api/v1/admin/financial/coupons/{id}

`Financial/DeleteCoupon` admin

Kuponu kaldırır.

Dönen alanlar data — 2

deletedboolSilme çalıştı mı.

idintSilinen kuponun numarası.

Hatalar 2

not_found404Kupon bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/financial/coupons/19' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/financial/coupons/${id}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/coupons/' . $id);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Silmek yerine KAPATIN: kod tekrar kullanilamaz kalir, gecmis kullanim izi de durur.
Api::Financial()->UpdateCoupon(['id' => $id, 'status' => 'inactive']);
```

### Kuponu Çoğaltma

post/api/v1/admin/financial/coupons/{id}/duplicate

`Financial/DuplicateCoupon` admin kopya kapalı doğar

Var olan bir kuponun ayarlarıyla yeni bir kupon açar.

Gövde —

——Gövde gerekmez, boş gönderin. Kuponu adresteki kimlik belirler.

Dönen alanlar 201 — data

dataobjectOluşan kopya. Koda bir kopya eki gelir, durum kapalı olur, kullanım sayacı sıfırlanır ve başlangıç tarihi silinir.

Hatalar 2

not_found404Kupon bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/financial/coupons/19/duplicate' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch(`https://panel.ornek.com/api/v1/admin/financial/coupons/${id}/duplicate`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await res.json();
console.log(data.code);   // WELCOME30-COPY
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/financial/coupons/' . $id . '/duplicate');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```

```php
// Kopya KAPALI dogar: kodunu ve tarihlerini duzelttikten sonra kendiniz acarsiniz.
$copy = Api::Financial()->DuplicateCoupon(['id' => $id])['data'];
Api::Financial()->UpdateCoupon([
    'id' => $copy['id'], 'code' => 'SUMMER30', 'status' => 'active',
]);
```

## Tuzaklar

> **İki ayrı durum alanı vardır**
> 
> Kayıtlı durum operatörün açıp kapattığı anahtardır; **gerçek durum** ise tarih aralığı ve kullanım sınırıyla birlikte hesaplanır. Etkin görünen bir kupon süresi dolduğu ya da sınırı dolduğu için çalışmayabilir. Müşteriye ne göreceğini anlatan alan ikincisidir ve yalnız liste ucunda döner.

> **Bitiş tarihi verilmezse kupon süresizdir**
> 
> Bitiş tarihi boş bırakılan bir kupon **hiç sona ermez**. Kampanya için açılıp unutulan böyle bir kod aylar sonra hâlâ indirim yapar. Kullanım sınırı da sıfırsa kupon hem süresiz hem sınırsızdır; kampanya kuponlarında ikisinden en az birini doldurun.

> **Kopya kapalı doğar ve kodu değişir**
> 
> Çoğaltma ucu yeni kuponu **kapalı** durumda açar, koduna bir kopya eki ekler, kullanım sayacını sıfırlar ve başlangıç tarihini siler. Yani kopya kullanıma hazır değildir: kodunu düzeltip açmanız gerekir. Aynı kuponu iki kez çoğaltırsanız ek numaralanarak artar.

> **Değişiklik geçmişe işlemez**
> 
> Kuponun oranını ya da koşullarını değiştirmek **bundan sonraki kullanımları** etkiler. Daha önce o kuponla kesilmiş siparişler ve faturalar eski oranıyla kalır; bu doğru davranıştır, çünkü o belgeler geçmişi anlatır. Bir hatayı düzeltmek istiyorsanız ilgili faturaya ayrıca dokunmanız gerekir.

> **Ürün değerleri kuruluma özgüdür**
> 
> Kuponun hangi ürünlerde geçerli olduğunu yazarken kullanılan değerler **ayrı bir uçtan** gelir ve kurulumun ürün ağacına göre değişir. Bu değerleri koda gömmek, kuponu başka bir kurulumda ya da ürünler değiştiğinde sessizce hiçbir şeye uymayan bir hâle getirir. Her seferinde listeyi okuyun.

## İlgili Makaleler

- [Para Birimleri ve Kurlar](https://dev.wisecp.com/tr/para-birimleri-ve-kurlar)
- [Vergilendirme Kuralları](https://dev.wisecp.com/tr/vergilendirme-kurallari)
- [Fatura Yönetimi](https://dev.wisecp.com/tr/fatura-yonetimi)