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.

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.