Afsláttarkóðar

Afsláttarkóðar Áskels eru tveir hlutir sem vinna saman:

Afsláttur (coupon) skilgreinir afsláttinn sjálfan: fasta upphæð (amount_off og currency) eða prósentu (percent_off), hversu lengi hann gildir (duration: forever, once eða repeating með duration_in_months) og takmarkanir eins og max_redemptions og redeem_by.
Kynningarkóði (promotion_code) er kóðinn sem viðskiptavinur slær inn (code) og vísar á afslátt. Hægt er að stofna marga kóða fyrir sama afsláttinn, binda kóða við einn viðskiptavin, setja gildistíma (expires_at) og lágmarksupphæð í restrictions.

Báða hlutina má stofna, sækja, uppfæra og eyða í gegnum V2 vefþjónustuna. Öll köll krefjast leynilegs API lykils. Eldri token-auðkenning er ekki studd á þessum köllum:

Authorization: Api-Key your-secret-api-key

Nákvæm skjölun á reitum og svörum er í Swagger skjölun okkar undir V2 Coupons á /api/swagger/v2/.

Afslættir

Kall	Lýsing
`GET /api/v2/coupons/`	Listar afslætti. Síur: `valid`, `duration`, `currency`, `name`. `page_size` kveikir á síðuskiptingu.
`POST /api/v2/coupons/`	Stofnar afslátt.
`GET /api/v2/coupons/{couponId}/`	Sækir einn afslátt.
`PATCH /api/v2/coupons/{couponId}/`	Uppfærir afslátt að hluta.
`DELETE /api/v2/coupons/{couponId}/`	Eyðir afslætti (mjúk eyðing).

Dæmi um stofnun á 20% afslætti sem gildir í þrjá mánuði:

{
  "name": "Sumartilboð",
  "percent_off": "20",
  "duration": "repeating",
  "duration_in_months": 3,
  "max_redemptions": 100,
  "redeem_by": "2026-12-31T23:59:59Z"
}

Reglur:

Nákvæmlega annað af amount_off (ásamt currency) eða percent_off þarf að vera sett. Til að skipta á milli í PATCH er gamli reiturinn sendur sem null í sama kalli.
duration_in_months er skylda þegar duration er repeating og má ekki vera sett annars.
redeem_by þarf að vera í framtíðinni nema afslátturinn sé þegar útrunninn; útrunninn afslátt má áfram uppfæra og eyða, en gildan afslátt er ekki hægt að gera útrunninn með dagsetningu í fortíðinni.
Óþekktum reitum í POST og PATCH er hafnað með 400. metadata og restrictions má senda sem null til að hreinsa þau.
id og times_redeemed er ekki hægt að breyta. id má gefa upp við stofnun (bókstafir, tölustafir, undirstrik, bandstrik og punktar, að hámarki 128 stafir), annars er það búið til sjálfkrafa.
currency þarf að vera gildur þriggja stafa ISO 4217 kóði. max_redemptions og duration_in_months þurfa að vera 1 eða hærri.
Afslætti sem hefur verið nýttur (times_redeemed > 0) er ekki hægt að eyða. Notið redeem_by eða max_redemptions til að loka honum.

Takmörkun við áskriftarleiðir og vörur

Afslátt má takmarka við tilteknar eldri áskriftarleiðir (applies_to_plans, listi af auðkennum áskriftarleiða), tiltekna áskriftarmöguleika þeirra (applies_to_plan_variants, listi af auðkennum áskriftarmöguleika), tilteknar vörur (applies_to_products, listi af auðkennum vara) og tiltekin verð þeirra (applies_to_prices, listi af auðkennum verða, sama id og GET /api/v2/catalog/prices/ skilar og price í línum tilboða). Allir listarnir eru sjálfgefið tómir og þá gildir afslátturinn um allt:

{
  "name": "Afsláttur af grunnpakka",
  "percent_off": "10",
  "duration": "forever",
  "applies_to_products": [42]
}

Um leið og einhver listanna hefur færslu er afslátturinn takmarkaður: eldri áskrift fær hann aðeins ef áskriftarleið hennar er í applies_to_plans eða áskriftarmöguleiki hennar í applies_to_plan_variants, og lína á samningi aðeins ef vara hennar er í applies_to_products eða verð hennar í applies_to_prices. Afsláttur sem er aðeins bundinn við áskriftarleiðir eða áskriftarmöguleika gefur því engan afslátt á samningum, og öfugt.
Áskriftarleið í applies_to_plans nær yfir alla áskriftarmöguleika hennar en áskriftarmöguleiki í applies_to_plan_variants aðeins yfir sjálfan sig. Þannig má til dæmis veita afslátt af mánaðarlegri áskrift án þess að veita sama afslátt af fyrirframgreiddu ári á sömu áskriftarleið.
Á sama hátt nær vara í applies_to_products yfir öll verð hennar en verð í applies_to_prices aðeins yfir sjálft sig. Þannig má til dæmis veita afslátt af mánaðarverði vöru en ekki af ársverði sömu vöru:
```
{
  "name": "Fyrsti mánuðurinn á hálfvirði",
  "percent_off": "50",
  "duration": "once",
  "applies_to_prices": [101]
}
```
Á samningi er afslátturinn reiknaður af þeim línum einum sem falla undir hann: percent_off er prósenta af þeim línum og amount_off er að hámarki samtala þeirra.
Lína á samningi er metin eftir verðinu sem hún er á hverju sinni. Ef liður færist af mánaðarverði sem afslátturinn er bundinn við yfir á ársverð sem hann er ekki bundinn við fær hann engan afslátt, og aftur afslátt ef hann færist til baka.
Kóða er hafnað þegar ekkert í kaupunum, eða á samningnum sem hann er settur á, fellur undir afsláttinn.
Ef áskrift færist á áskriftarleið eða áskriftarmöguleika utan listanna helst afslátturinn á henni en lækkar ekkert fyrr en hún færist aftur á leið eða möguleika sem hann nær yfir. once afsláttur nýtist ekki upp á greiðslu sem hann lækkaði ekki.
Áskriftarleiðir, áskriftarmöguleikar, vörur og verð þurfa að tilheyra sama reikningi. Í PATCH helst listi óbreyttur ef honum er sleppt og tómur listi ([]) tæmir hann.
Ekki er hægt að eyða áskriftarleið, áskriftarmöguleika, vöru eða verði sem afsláttur er bundinn við, né áskriftarleið sem á áskriftarmöguleika eða vöru sem á verð sem afsláttur er bundinn við.

Kynningarkóðar

Kall	Lýsing
`GET /api/v2/promotion-codes/`	Listar kynningarkóða. Síur: `code`, `coupon`, `active`, `valid`, `customer_reference`.
`POST /api/v2/promotion-codes/`	Stofnar kynningarkóða.
`GET /api/v2/promotion-codes/{promotionCodeId}/`	Sækir einn kynningarkóða.
`PATCH /api/v2/promotion-codes/{promotionCodeId}/`	Uppfærir kynningarkóða að hluta.
`DELETE /api/v2/promotion-codes/{promotionCodeId}/`	Eyðir kynningarkóða (mjúk eyðing).

Dæmi um stofnun á kóða sem aðeins einn viðskiptavinur getur nýtt einu sinni:

{
  "coupon": "coup_5f3a1c2b9d8e4f6a7b8c9d0e",
  "code": "VELKOMIN",
  "customer_reference": "customer-123",
  "max_redemptions": 1,
  "expires_at": "2026-12-31T23:59:59Z",
  "restrictions": {
    "minimum_amount": "1000",
    "minimum_amount_currency": "ISK"
  }
}

Reglur:

coupon þarf að vera afsláttur í sama reikningi.
code er 4-50 stafir (bókstafir, tölustafir, bandstrik og undirstrik) og er alltaf geymdur með hástöfum. Ef honum er sleppt er kóði búinn til sjálfkrafa. Kóðinn þarf að vera einstakur meðal virkra kóða reikningsins; óvirkir (active: false) og eyddir kóðar losa kóðann til endurnotkunar.
Viðskiptavinur er tilgreindur með customer (auðkenni) eða customer_reference, ekki báðum. null fjarlægir bindinguna.
restrictions styður eingöngu lágmarksupphæð: minimum_amount (hærri en 0) og minimum_amount_currency (ISO 4217 kóði) þurfa að fylgjast að. Tómt {} fjarlægir takmörkunina.
Kynningarkóða sem hefur verið nýttur er ekki hægt að eyða. Setjið active á false í staðinn.

Nýting kóða á áskriftir er skjöluð með áskriftarköllunum, sjá POST /api/v2/subscription-contracts/{contractId}/apply-code/ fyrir V2 samninga og POST /api/subscriptions/{subscription_id}/apply-code/ fyrir eldri áskriftir.