Áskriftarsamningar V2

Áskriftarsamningar V2 eru nýja áskriftarlíkan Áskels. Það er aðskilið frá eldra PlanVariant / Subscription flæði og byggir í staðinn á vörulista, verði, pökkum, verðútreikningum, greiðslugangi og innheimtulotum.

Öll köll í V2 vefþjónustur krefjast leynilegs API lykils:

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

Eldri token-auðkenning er enn studd í sumum V2 köllum til samræmis við eldri samþættingar. Nýjar samþættingar ættu þó að nota leynilega API lykla.

Stutt yfirlit yfir dæmigert flæði

Algengt samþættingarflæði er þetta:

1. Sækja vörur, verð eða pakka úr vörulista.

2. Reikna verðútreikning með POST /api/v2/subscription-offer-quotes/.

3. Sækja mögulega færsluhirða með POST /api/v2/payment-processor-options/.

4. Stofna checkout með POST /api/v2/checkouts/.

5. Ganga frá checkout með POST /api/v2/checkouts/{token}/finalize/.

6. Fylgjast með stöðu checkout og, eftir atvikum, upphaflegri innheimtulotu.

Ef samþættingin þarf ekki greiðsluforvinnu má sleppa skrefum 3-5 og stofna samning beint með POST /api/v2/subscription-contracts/.

Sjá einnig

Fyrir eldra áskriftarflæði út frá PlanVariant og Subscription skal sjá Áskriftir.

Aðvörun

checkout_url í V2 er ekki opin hýst greiðslusíða. Hún vísar á API slóð fyrir checkout hlutinn sjálfan og hentar því fyrir kerfi-í-kerfi samþættingar, ekki fyrir beina endurvísun notanda í vafra.

Hvenær á að nota V2

V2 á að nota þegar selja á vörur og áskriftir út frá vörulista í stað eldri plana og PlanVariant auðkenna. Þar á meðal:

1. Þegar selja á stakar vörur eða samsetningu vara sem áskriftarsamning.

2. Þegar nota á pakka með vali á verði og magni.

3. Þegar skipuleggja þarf verðbreytingar með verðútgáfum.

4. Þegar halda á utan um endurteknar innheimtulotur með skýrari sögu og möguleika á endurtekningu.

Eldri greiðslusíður og eldra /api/subscriptions/ flæði halda áfram að nota eldra Subscription líkanið og eru skjöluð sér undir Áskriftir.

Kjarna hlutir

Helstu V2 hlutirnir eru þessir:

Hlutur	Lýsing
CatalogProduct	Vara í vörulista.
CatalogPrice	Stöðugt verðauðkenni sem samningur tengist.
CatalogPriceVersion	Tímabundin verðútgáfa sem skilgreinir upphæð á tímabili.
BundleTemplate	Sölupakki sem sameinar eina eða fleiri vörur.
SubscriptionContract	Nýi varanlegi áskriftarsamningurinn.
BillingRun	Ein innheimtulota á samningi.
BillingRunAttempt	Stök tilraun til að innheimta lotu.
V2Checkout	Millihlutur sem geymir verðútreikning og greiðsluforsendur áður en samningur er stofnaður.

Áður en byrjað er

Áður en hægt er að ganga frá greiðslugangi eða stofna samning þarf eftirfarandi að vera til staðar:

1. Viðskiptavinur þarf þegar að vera til í Áskeli.

2. Færsluhirðir (AccountPaymentProcessor) þarf að vera uppsettur fyrir viðeigandi gjaldmiðil og greiðsluaðferð.

3. Ef nota á checkout / finalize ferlið þarf viðskiptavinurinn þegar að vera með staðfestan greiðslumáta sem passar við valinn færsluhirði.

Sjá einnig Forsendur áður en finalize er kallað, þar sem nánar er farið yfir hvað er staðfest rétt áður en finalize stofnar samning og innheimtu.

Leit í vörulista

Til að sækja vörur og verð í vörulista má nota eftirfarandi slóðir:

curl https://askell.is/api/v2/catalog/products/ \
  -H "Authorization: Api-Key your-secret-api-key"

curl "https://askell.is/api/v2/catalog/prices/?billing_type=recurring&currency=ISK" \
  -H "Authorization: Api-Key your-secret-api-key"

Algengar síur á vörulista:

Sía	Lýsing
active	Sjálfgefið eru aðeins virk gögn sýnd. Nota má all eða any.
reference	Tilvísun á vöru eða pakka, eftir slóð.
product	Auðkenni vöru eða vöru-tilvísun á verðslóð.
currency	Gjaldmiðill verðs.
billing_type	recurring eða one_time.
recurrence_type	Tegund endurtekningar fyrir endurtekin verð.

Verðútgáfur

Í V2 tengist samningur stöðugu CatalogPrice auðkenni, en sjálf upphæðin getur breyst með tímanum í gegnum CatalogPriceVersion. Þetta gerir kleift að skipuleggja verðbreytingar fyrirfram án þess að viðskiptavinur þurfi að flytjast á nýtt verðauðkenni.

Í svörum frá verðslóðum vörulistans birtast meðal annars eftirfarandi reitir:

Reitur	Lýsing
unit_amount	Núverandi sýnd upphæð fyrir verðið.
current_version_id	Auðkenni þeirrar verðútgáfu sem telst virk núna.
versions	Fortíðar-, núverandi- og framtíðar verðútgáfur.
effective_from	Upphaf gildistíma þeirrar útgáfu sem nú er sýnd.
effective_to	Lok gildistíma þeirrar útgáfu sem nú er sýnd.

Samþættingar sem þurfa aðeins að vita núverandi upphæð geta yfirleitt lesið unit_amount. Samþættingar sem vilja sýna eða skipuleggja verðbreytingar ættu að nota versions.

Pakkar og verðval

Pakkar eru sóttir á sérstökum vefslóðum:

curl https://askell.is/api/v2/bundle-templates/ \
  -H "Authorization: Api-Key your-secret-api-key"

curl https://askell.is/api/v2/bundle-templates/42/ \
  -H "Authorization: Api-Key your-secret-api-key"

Pakki getur innihaldið fasta vöruuppsetningu, leyft val á verði fyrir ákveðna pakkaliði eða notað sjálfkrafa virk endurtekin verð á tengdri vöru.

Viðbótarvörur

Þegar pakki hefur verið valinn og viðeigandi verðval tiltekið er hægt að spyrja hvaða viðbótarvörur eða viðbótarpakkar séu í boði:

curl https://askell.is/api/v2/bundle-templates/42/addons/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_item_selections": [
      {
        "bundle_item": 100,
        "selected_price": 200
      }
    ]
  }'

Verðútreikningur og beiðnigögn

Sömu grunnreitir eru notaðir aftur og aftur í verðútreikningum, greiðslugangsferli og beinni stofnun samninga.

Reitur	Lýsing
bundle_template	Auðkenni valins pakka.
bundle_quantity	Magn pakka.
bundle_item_selections	Val á verði eða magni fyrir einstaka liði innan pakka.
items	Beint valdar endurteknar vörur án pakka.
initial_items	Einskiptis vörur eða vörur sem eiga aðeins að birtast í fyrstu innheimtu.
initial_billing_mode	Stýrir hvort upphafstímabil sé ekki innheimt, innheimt strax eða sett á næstu innheimtu.
additional_items	Viðbótarvörur sem valdar eru út frá viðbótarreglum.
additional_bundles	Viðbótarpakkar sem valdir eru út frá viðbótarreglum.

Aðeins eitt aðalinnsláttarform fyrir endurtekna vöru má nota í einu:

• bundle_template

• items

initial_items eru aðeins notaðir við upphaflega innheimtu. Þeir verða ekki varanlegir SubscriptionContractItem liðir. Sjá einnig kaflann Bein stofnun samnings.

Sendingarval

Reikningur getur tengt sendingaraðila (Dropp, Pósturinn eða sótt í verslun) og skilgreint sendingarmöguleika í stjórnborðinu. Þegar reikningurinn býður virka sendingarmöguleika og karfan inniheldur vöru sem er ekki merkt rafræn þarf POST /api/v2/checkouts/ að innihalda shipping hlut:

{
  "shipping": {
    "option": 12,
    "location_id": "9591",
    "location_name": "Póstbox Hallveigarstíg",
    "location_address": "Hallveigarstíg 1, 101 Reykjavík"
  }
}

option er auðkenni virks sendingarmöguleika reikningsins. location_id er skylda fyrir möguleika sem krefjast staðarvals, til dæmis póstbox eða Dropp-afhendingarstaði. Við frágang er valið vistað sem óbreytanlegt afrit á samningnum og skilað sem shipping_selection í samningssvörum, með heiti, verði, þjónustukóða og völdum afhendingarstað eins og þau voru við kaupin.

Sendingarmöguleiki getur haft frísendingarmörk (free_above_amount). Nái heildarupphæð pöntunarinnar mörkunum er sendingargjaldið skráð sem núll í afritinu.

Athugasemd

Sendingargjaldið (price_amount) er aðeins skráð á afritið í þessari útgáfu; það er ekki bætt við greiðslukeyrslur og því ekki innheimt. Sýndu það ekki viðskiptavinum sem gjald sem verður tekið.

Föst innheimtudagsetning

Endurtekin mánaðarleg eða árleg verð geta haft billing_day_of_month. Ef fleiri en eitt endurtekið verð í sama verðútreikningi eða samningi hefur slíkan dag verða þau að vísa á sama dag mánaðarins. Ekki er hægt að blanda saman verði sem eru föst á mismunandi daga, til dæmis eitt verð á 1. degi og annað á 15. degi mánaðarins.

Það má hins vegar blanda saman verði með föstum degi og verði án billing_day_of_month. Verð án eigin dags fylgja þá eina fasta deginum sem er til staðar í samningnum.

Verðútreikningur áður en samningur er stofnaður

POST /api/v2/subscription-offer-quotes/ býr til óvaranlegan verðútreikning út frá beiðnigögnunum og skilar samantekt á endurteknum línum, upphafslínum, sköttum, samtölum og áætlaðri tímasetningu innheimtu.

Fyrir endurtekna liði aðgreinir svarið nú:

• first_period_recurring_*: það sem er gjaldfært í fyrstu lotu, þar með talið upphafshlutfallsgreiðsla þegar fyrsta lotan er styttri en venjuleg endurnýjunarlota.

• recurring_*: venjuleg endurnýjunarfjárhæð eftir að fyrsta styttri lota er liðin.

Á einstökum endurteknum línum eru einnig birt service_period_start_at, service_period_end_at, proration_factor og renewal_line_* svo samþætting geti sýnt skýrt muninn á fyrstu innheimtu og seinni endurnýjunum.

Dæmi um verðútreikning fyrir pakka:

curl https://askell.is/api/v2/subscription-offer-quotes/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "bundle_template": 42,
    "bundle_quantity": 2,
    "bundle_item_selections": [
      {
        "bundle_item": 100,
        "selected_price": 200
      }
    ],
    "additional_items": [
      {
        "rule_id": 300,
        "price": 400,
        "quantity": 1
      }
    ],
    "initial_items": [
      {
        "price": 500,
        "quantity": 1
      }
    ]
  }'

Stytt svar gæti litið svona út:

{
  "input_mode": "bundle",
  "bundle_template_id": 42,
  "bundle_quantity": 2,
  "currency": "ISK",
  "period_start_at": "2026-05-20T00:00:00Z",
  "period_end_at": "2026-06-20T00:00:00Z",
  "subtotal_amount": "4500.0000",
  "tax_amount": "0.0000",
  "total_amount": "4500.0000",
  "first_period_recurring_subtotal_amount": "4000.0000",
  "first_period_recurring_tax_amount": "0.0000",
  "first_period_recurring_total_amount": "4000.0000",
  "recurring_subtotal_amount": "4000.0000",
  "recurring_tax_amount": "0.0000",
  "recurring_total_amount": "4000.0000",
  "billing_schedule_preview": {
    "kind": "interval"
  },
  "recurring_items": [
    {
      "key": "bundle-item-100",
      "source": "bundle",
      "creates_contract_item": true,
      "price_id": 200,
      "product_id": 10,
      "product_name": "Vefáskrift",
      "billing_type": "recurring",
      "quantity": 2,
      "unit_amount": "2000.0000",
      "service_period_start_at": "2026-05-20T00:00:00Z",
      "service_period_end_at": "2026-06-20T00:00:00Z",
      "proration_factor": "1.000000",
      "line_total_amount": "4000.0000",
      "renewal_line_total_amount": "4000.0000"
    }
  ],
  "initial_lines": [
    {
      "key": "initial-item-500",
      "source": "initial_items",
      "creates_contract_item": false,
      "price_id": 500,
      "product_id": 11,
      "product_name": "Áskrifendagjöf",
      "billing_type": "one_time",
      "quantity": 1,
      "unit_amount": "500.0000",
      "line_total_amount": "500.0000"
    }
  ]
}

Dæmi um verðútreikning fyrir beinar vörur án pakka:

curl https://askell.is/api/v2/subscription-offer-quotes/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "ISK",
    "items": [
      {
        "price": 200,
        "quantity": 1
      }
    ],
    "initial_items": [
      {
        "price": 500,
        "quantity": 1
      }
    ]
  }'

Bein stofnun samnings

POST /api/v2/subscription-contracts/ stofnar V2 samning beint. Þetta flæði hentar þegar samþættingin hefur þegar staðfest pöntunina og þarf ekki að keyra greiðsluforvinnu í sama kalli.

Þú getur meðal annars sent inn:

• customer_reference

• currency

• bundle_template eða items

• bundle_item_selections

• additional_items

• additional_bundles

• initial_items

• initial_billing_mode

• metadata

• payment_processor_override ef samningurinn á að vera bundinn ákveðnum færsluhirði

initial_items verða ekki varanlegir SubscriptionContractItem liðir. Þeir fara eingöngu á fyrstu innheimtulotulínurnar ef fyrsta innheimta er byggð á þeim.

initial_billing_mode gerir upphafsinnheimtu skýra:

none

Sjálfgefið gildi. Samningur og endurteknir samningsliðir eru stofnaðir og next_billing_at er sett út frá næstu innheimtu samningsliðanna. Engin innheimtulota eða upphafshlutfallslína er stofnuð fyrir tímabilið frá stofnun samnings fram að fyrstu skipulögðu innheimtu. Þetta hentar þegar upphafstímabilið á að vera án endurgjalds eða er innheimt utan Áskels.

create_initial_run

Stofnar áætlaða upphaflega BillingRun með endurteknum línum fyrir fyrsta tímabilið og mögulegum einskiptis initial_items. Fyrsta innheimtan fylgir sömu reglum um upphafshlutfallsgreiðslu og POST /api/v2/subscription-offer-quotes/ og getur því verið lægri en recurring_* upphæðirnar ef samningur byrjar inni í styttri upphafslotu.

next_invoice

Stofnar ekki upphaflega BillingRun. Í staðinn eru upphafshlutfallslínur fyrir endurteknu vörurnar geymdar sem biðlínur og merktar á fyrstu skipulögðu innheimtuna. Þegar fyrsta reglulega innheimtulotan er stofnuð fær hún bæði upphafstímabilið og næsta reglulega tímabil. Þetta hentar þegar þjónusta á að hefjast strax en innheimta á hlutfallslega fyrir upphafstímabilið á fyrsta gjalddaga.

initial_items eru aðeins leyfð með initial_billing_mode=create_initial_run. Þau eru ekki leyfð með none eða next_invoice þar sem þau verða ekki varanlegir samningsliðir og geta því ekki verið færð sjálfkrafa á næstu reglulegu innheimtu.

Dæmi: þjónusta byrjar strax en upphafstímabil er innheimt á fyrsta gjalddaga:

curl https://askell.is/api/v2/subscription-contracts/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_reference": "customer-123",
    "currency": "ISK",
    "items": [
      {
        "price": 200,
        "quantity": 1
      }
    ],
    "initial_billing_mode": "next_invoice"
  }'

Ef samningur er stofnaður 21. maí og fyrsta skipulagða innheimta er 1. júní, þá verður hlutfallslega tímabilið 21. maí til 1. júní sett á innheimtuna 1. júní ásamt reglulegu tímabilinu 1. júní til 1. júlí.

Sækja og uppfæra samning

Samningur er sóttur á:

GET /api/v2/subscription-contracts/{id}/

Samningar aðgangsins eru sóttir á GET /api/v2/subscription-contracts/. Listinn styður eftirfarandi síur:

Sía	Lýsing
state	Staða samnings: inactive, active, paused, canceled eða ended.
customer	Auðkenni viðskiptavinar.
customer_reference	Tilvísun viðskiptavinar.

Athugasemd

Listinn styður enga ordering færibreytu og engar aðrar síur en þær sem taldar eru upp hér að ofan. Óþekktar færibreytur skila ekki villu heldur eru hunsaðar, svo til dæmis ?ordering=-created_at, ?reference=... eða ?legacy_subscription_id=... skila listanum óbreyttum. Röðunin er föst: nýjustu samningar fyrst (-created_at, -id). Þetta er ólíkt eldra GET /api/subscriptions/, sem styður ordering á active_until og start_date.

Reitir í svari samnings

Sama svarform er notað fyrir stofnun samnings, stakan samning, lista og lífsferilsköll. Helstu reitir eru þessir:

Reitur	Lýsing
id	Auðkenni samnings.
customer_id / customer	Auðkenni viðskiptavinar og földuð gögn hans.
customer_reference	Tilvísun viðskiptavinar.
state	inactive, active, paused, canceled eða ended.
currency	Gjaldmiðill samnings.
recurring	Hvort samningurinn innheimtir áfram. Verður false við uppsögn.
contract_version	Hækkar við hverja breytingu á samningnum.
billing_anchor_at	Viðmiðunartími innheimtu.
billing_timezone / billing_time	Tímabelti og tími dags sem innheimta er keyrð á.
billing_advance_policy	Hvenær innheimtulotan færist fram: on_run_created eða on_run_succeeded.
next_billing_at	Næsta skipulagða innheimta. null eftir uppsögn.
trial_start_at / trial_end_at	Prufutímabil, ef við á.
cancel_at_period_end	Sjá Gildistími og uppsögn.
cancel_at	Sjá Gildistími og uppsögn.
canceled_at	Sjá Gildistími og uppsögn.
ended_at	Sjá Gildistími og uppsögn.
service_active / service_state	Hvort veita eigi þjónustu núna og heildarstaða þjónustu (active, inactive, partial, past_due).
entitlement_summary	Samantekt á þjónusturéttindum samningsins.
billing_attention_required	Innheimta samningsins þarfnast athygli, til dæmis eftir misheppnaða skuldfærslu.
has_future_pause / paused_until	Hvort hlé er skipulagt fram í tímann og dagsetningin sem hléið stendur til.
pauses og current_pauses / future_pauses / past_pauses	Skráð hlé á samningnum.
items	Samningsliðir með verði, magni og þjónustutímabilum.
latest_billing_run	Nýjasta innheimtulotan með period_start_at og period_end_at.
initial_billing_run	Upphaflega innheimtulotan, ef hún var stofnuð.
discount	Virkur afsláttur af samningnum, ef einhver er.
delivery_address / shipping_selection	Afhendingarheimilisfang og valin sendingarleið.
legacy_subscription_ids	Auðkenni eldri áskrifta sem fluttar voru yfir í samninginn.
metadata	Frjáls gögn samþættingarinnar.
subscriber_page	Slóð á áskrifendasíðu samningsins.
created_at / updated_at	Stofn- og breytingartími.

subscriber_page er slóð á áskrifendasíðu samningsins þar sem viðskiptavinur getur sýslað með áskriftina sína. Þetta er sama slóð og birtist í stjórnborðinu og reiturinn er aðeins til lestrar.

{
  "id": 33,
  "subscriber_page": "https://askell.is/change_contract/<token>/"
}

Gildistími og uppsögn

Mikilvægt

V2 samningar hafa hvorki active_from né active_until. active_until er reitur á eldra Subscription líkaninu og er reiknaður út frá síðustu innheimtufærslu þess. Samsvarandi upplýsingar í V2 koma úr stöðu samningsins, þjónustutímabilum liðanna og innheimtulotunum.

Til að svara spurningunni „er þessi áskrift virk og hversu lengi?“ skal nota:

• state og service_active / service_state fyrir stöðuna núna.

• next_billing_at fyrir næstu innheimtu.

• latest_billing_run.period_end_at fyrir lok tímabilsins sem síðast var innheimt.

• items[].current_service_period_end_at og items[].entitled_until fyrir þjónusturéttindi einstakra liða.

• paused_until ef samningurinn er í hléi.

Uppsögn birtist í fjórum reitum:

Reitur	Merking
cancel_at_period_end	true á meðan uppsögn er skipulögð við lok yfirstandandi tímabils. Reiturinn fer aftur í false þegar uppsögnin er framkvæmd.
cancel_at	Tíminn sem uppsögnin tekur eða tók gildi. Settur bæði fyrir skipulagða og tafarlausa uppsögn.
canceled_at	Tíminn sem uppsögnin var í raun framkvæmd. null á meðan uppsögn er aðeins skipulögð.
ended_at	Tíminn sem samningurinn endaði.

Dæmigerð tilvik:

1. POST /cancel/ með cancel_at_period_end=true: state helst active, cancel_at_period_end verður true, cancel_at er sett á lok yfirstandandi tímabils og canceled_at og ended_at eru áfram null.

2. POST /cancel/ með cancel_at fram í tímann: cancel_at_period_end er false, cancel_at geymir valda tímann og canceled_at og ended_at eru áfram null.

3. POST /cancel/ án cancel_at_period_end og cancel_at: uppsögnin er tafarlaus. state verður canceled, allir þrír tímareitirnir eru settir á tímann núna, recurring verður false og next_billing_at verður null.

4. Þegar skipulögð uppsögn er framkvæmd: state verður canceled, cancel_at_period_end fer í false, canceled_at er tíminn sem uppsögnin var keyrð og ended_at er sá tími sem uppsögnin átti að taka gildi.

5. POST /restart/ á samning með skipulagða uppsögn hreinsar cancel_at_period_end og cancel_at.

Samningur getur einnig endað án uppsagnar, til dæmis þegar samningi um stök kaup lýkur. Þá verður state ended og ended_at er sett, en canceled_at helst null.

Sömu reitir fylgja með í subscription_contract.* vefkrókum, sjá Vefkrókar.

Blaðskipting á listum

V2 listar nota blaðskiptingu aðeins ef page_size er sent inn.

• page_size virkjar blaðskiptingu

• sjálfgefið page_size er 10 þegar blaðskipting er virk

• hámarks page_size er 1000

• page velur síðu

Dæmi:

GET /api/v2/subscription-contracts/?page_size=25&page=2

Þegar blaðskipting er virk er svarið á hefðbundnu formi með count, next, previous og results. Ef page_size er ekki sent inn fæst óblaðskiptur listi.

V2 smáatriðaslóðin leyfir aðeins takmarkaðar uppfærslur með PATCH. Aðeins metadata, payment_processor_override, delivery_address, accounting_department og accounting_cost_center má breyta þar; aðrir reitir skila 400 villu. Samningurinn er ekki hugsaður sem frjálslega breytanlegur pöntunardráttur, heldur sem viðskiptalega mikilvæg staða sem á að lifa í gegnum skilgreind lífsferilsköll.

Vörubreytingar á virkum samningi

Athugasemd

Uppfært 19. ágúst 2026: unit_amount_override er nú stutt í items/add, items/update og proration-preview, og óstuddir reitir skila nú 400 villu í stað þess að vera hunsaðir. Sjá Breytingaskrá.

V2 styður hlutfallsreiknaðar breytingar á liðum virks samnings:

Slóð	Lýsing
POST /proration-preview/	Forskoðar áhrif breytingar án þess að framkvæma hana.
POST /items/add/	Bætir nýjum lið á samninginn.
POST /items/update/	Uppfærir verð, magn, afslátt eða fast verð liðar.
POST /items/remove/	Fjarlægir lið af samningnum.

Helstu beiðnireitir:

Aðgerð	Reitir	Skylda
POST /proration-preview/	operation (add_item, update_item, remove_item, pause, resume, cancel, restart) ásamt reitum viðkomandi aðgerðar	operation valkvæður, sjálfgefið update_item
POST /items/add/	price, quantity, discount_percent, unit_amount_override, effective_at, proration_behavior, settlement_behavior, include_pending_adjustments, reason, idempotency_key, preview_token	price skylda; aðrir valkvæðir
POST /items/update/	contract_item, price, quantity, discount_percent, unit_amount_override, effective_at, proration_behavior, settlement_behavior, include_pending_adjustments, reason, idempotency_key, preview_token	contract_item skylda; aðrir valkvæðir
POST /items/remove/	contract_item, effective_at, proration_behavior, settlement_behavior, include_pending_adjustments, reason, idempotency_key, preview_token	contract_item skylda; aðrir valkvæðir

Í items/update þarf aðeins að senda þá reiti sem á að breyta; reitir sem er sleppt halda núverandi gildi liðarins. Ef engin raunveruleg breyting felst í beiðninni fæst 400 svar með code sem er no_change.

Óþekktir reitir í beiðnum á þessar slóðir skila 400 villu í stað þess að vera hunsaðir þegjandi. Sama gildir um reiti sem viðkomandi operation styður ekki, til dæmis unit_amount_override í items/remove.

Fast verð á lið (unit_amount_override)

unit_amount_override setur fasta einingarupphæð á lið í stað verðs úr vörulista. Reiturinn er studdur við stofnun samnings og einnig í items/add, items/update og proration-preview.

Í items/update gildir:

• Ef reitnum er sleppt helst núverandi fast verð liðarins óbreytt.

• Ef sent er skýrt null er fasta verðið fjarlægt og liðurinn fer aftur á verð úr vörulista.

• Breyting á fasta verðinu einu og sér telst gild breyting og skilar ekki no_change.

Hlutfallslínur sem verða til þegar fasta verðinu einu er breytt fá proration_reason gildið unit_amount_changed.

Dæmi um að setja fast verð á lið:

curl -X POST https://askell.is/api/v2/subscription-contracts/123/items/update/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_item": 456,
    "unit_amount_override": "8000.0000",
    "settlement_behavior": "invoice_now",
    "idempotency_key": "item-456-fast-verd"
  }'

Sama forskoðunarmynstur gildir og fyrir lífsferilsaðgerðir: kalla fyrst á proration-preview með sömu reitum, vista preview_token úr svarinu og senda það með framkvæmdarkallinu.

Lífsferilsaðgerðir

V2 styður eftirfarandi lífsferilsköll á samninga:

Slóð	Lýsing
POST /cancel/	Hættir við samningi, annaðhvort strax eða við lok tímabils.
POST /restart/	Endurræsir samning sem hefur verið stöðvaður.
POST /pause/	Setur tímabundið hlé á samning.
POST /resume/	Tekur samning úr hléi.
DELETE /pause/{pause_id}/	Eyðir fyrirfram skráðu hléi.
POST /activate/	Virkjar óvirkan samning ef hann má færast í virka stöðu.

Helstu beiðnireitir:

Aðgerð	Reitir	Skylda
POST /cancel/	cancel_at_period_end, cancel_at, effective_at, reason, proration_behavior, settlement_behavior, include_pending_adjustments, idempotency_key, preview_token	Allir valkvæðir
POST /restart/	effective_at, reason, proration_behavior, settlement_behavior, include_pending_adjustments, idempotency_key, preview_token	Allir valkvæðir
POST /pause/	start_date, end_date, reason, proration_behavior, settlement_behavior, include_pending_adjustments, idempotency_key, preview_token	start_date og end_date skyldar; aðrir valkvæðir
POST /resume/	effective_at, reason, proration_behavior, settlement_behavior, include_pending_adjustments, idempotency_key, preview_token	Allir valkvæðir

Lífsferilsaðgerðir sem geta haft áhrif á verð innan virks þjónustutímabils styðja sama hlutfallsreikningsmynstur og vörubreytingar:

1. Kalla POST /api/v2/subscription-contracts/{id}/proration-preview/ með operation sem er cancel, pause, resume eða restart.

2. Vista preview_token úr svarinu ef framkvæma á sömu aðgerð strax á eftir.

3. Senda sama preview_token aftur í framkvæmdarkallið ásamt sömu stillingum fyrir proration_behavior og settlement_behavior.

include_pending_adjustments=true er aðeins gilt þegar settlement_behavior=invoice_now og þarf þá að vera sent bæði í forskoðun og framkvæmd.

proration_behavior getur verið none, create_prorations eða always_invoice. settlement_behavior getur verið next_invoice, invoice_now eða credit_balance. refund_manual og aðgerðir fyrir stakar endurgreiðslur eða handvirkar leiðréttingar eru ekki hluti af ytra V2 API flæðinu eins og er.

Inneign á samningi

Hlutfallsreiknaður kredit, til dæmis vegna lokunar, hlés eða breytinga á liðum, getur stofnað inneignarfærslu á samningi. Slík inneign er skráð sem óbreytanleg færslusaga á samningnum.

Núverandi regla fyrir framtíðarinnleiðingu er að inneign dragist frá eftir að skattar og línusamtölur hafa verið reiknaðar, en áður en reynt er að skuldfæra færsluhirði. Inneign má nota að hluta eða að fullu, og ef inneign nær yfir alla innheimtulotuna er ekki reynt að skuldfæra færsluhirði. Inneign sem verður til í sömu innheimtulotu má ekki nýtast þeirri sömu lotu.

Sjálfvirk nýting inneignar í næstu innheimtulotu er ekki komin inn í ytra API flæðið enn. Þangað til er inneign skráð og sýnileg í stjórnborði/sögu, en hún lækkar ekki sjálfkrafa næstu skuldfærslu.

Dæmi um að hætta við samning við lok tímabils:

curl -X POST https://askell.is/api/v2/subscription-contracts/123/cancel/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_at_period_end": true,
    "reason": "Viðskiptavinur óskaði eftir lokun"
  }'

Sjá Gildistími og uppsögn um það hvernig uppsögn birtist í cancel_at_period_end, cancel_at, canceled_at og ended_at eftir að kallið hefur verið framkvæmt.

Dæmi um forskoðun á hlutfallsreiknaðri endurræsingu:

curl -X POST https://askell.is/api/v2/subscription-contracts/123/proration-preview/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "restart",
    "proration_behavior": "create_prorations",
    "settlement_behavior": "invoice_now"
  }'

Greiðslugangur

Þegar óskað er eftir greiðsluforvinnu áður en samningur verður virkur er mælt með checkout ferlinu:

1. Reikna eða staðfesta verðútreikning.

2. Sækja mögulega færsluhirða með POST /api/v2/payment-processor-options/.

3. Stofna checkout með POST /api/v2/checkouts/.

4. Ganga frá checkout með POST /api/v2/checkouts/{token}/finalize/.

POST /api/v2/payment-processor-options/ skilar þeim færsluhirðum sem eru löglegir fyrir viðkomandi verðútreikning, gjaldmiðil og innheimtuaðferð. Ef aðeins einn færsluhirðir er í boði má nota hann sjálfgefinn. Ef fleiri en einn kemur til greina ætti samþættingin að leyfa val.

Stytt svar gæti litið svona út:

{
  "currency": "ISK",
  "collection_method": "card",
  "selected_account_payment_processor_id": 7,
  "selection_reason": "single_eligible",
  "requires_selection": false,
  "results": [
    {
      "account_payment_processor_id": 7,
      "display_name": "Straumur / Adyen",
      "payment_processor": "adyen",
      "collection_method": "card",
      "resolution_source": "eligible",
      "supports_initial_charge": true,
      "supports_recurring_charge": true,
      "render_mode": "adyen_checkout",
      "payment_processor_type": "adyen",
      "is_3d_secure": true,
      "card_collection_in_frontend": true,
      "supports_checkout": true,
      "address_required": false,
      "registration_mode": "delayed_tokenization",
      "public_registration_config": {}
    }
  ]
}

render_mode segir viðmótinu hvernig kortaupplýsingar eru sóttar: generic_card_form (kortaform hýst af Áskel), verifone_encrypted_card (dulkóðun í vafra), adyen_checkout (Straumur/Adyen drop-in) eða teya_checkout (Teya Embedded Checkout). Bæði adyen_checkout og teya_checkout nota delayed-tokenization: kortið er vistað hjá færsluhirðinum eftir að greiðslusíðan hefur lokið checkout og greiðslulotan er kláruð með vefkróki (eða samstilltri staðfestingu hjá Teya).

POST /api/v2/checkouts/ býr til checkout hlut sem geymir verðútreikningsmynd, viðskiptavin, valinn færsluhirði og önnur forsendar-gögn.

GET /api/v2/checkouts/{token}/ sækir stöðu checkout hlutarins. checkout_url vísar á þessa slóð.

POST /api/v2/checkouts/{token}/finalize/ reynir að ljúka stofnun samnings og fyrstu innheimtu.

Forsendur áður en finalize er kallað

finalize kallar nú á forskoðun áður en samningur er stofnaður. Eftirfarandi þarf því að vera í lagi áður en finalize er reynt:

1. Viðskiptavinur þarf að vera til.

2. Valinn færsluhirðir þarf að vera löglegur fyrir verðútreikninginn.

3. Viðskiptavinur þarf að vera með staðfestan greiðslumáta sem passar við valinn færsluhirði, nema fyrsta innheimta sé 0 kr.

Ef þessar forsendur standast ekki fæst villusvar og enginn samningur eða innheimtulota verður stofnuð.

Mikilvægt er að greina á milli tveggja tegunda af 400 svörum úr finalize:

1. Forsendubrestur: enginn samningur og engin innheimtulota verða stofnuð.

2. Misheppnuð greiðslutilraun: samningur og innheimtulota geta þegar verið orðin til, en checkout.status verður failed.

Stytt svar úr finalize gæti litið svona út:

{
  "id": 15,
  "token": "f2dd7db2-4ae1-45c0-b8f6-2f98d1b70a9a",
  "checkout_url": "https://askell.is/api/v2/checkouts/f2dd7db2-4ae1-45c0-b8f6-2f98d1b70a9a/",
  "status": "succeeded",
  "customer_id": 1008,
  "customer_reference": "customer-123",
  "currency": "ISK",
  "subtotal_amount": "4500.0000",
  "tax_amount": "0.0000",
  "total_amount": "4500.0000",
  "contract_id": 33,
  "initial_billing_run_id": 32,
  "account_payment_processor_id": 7,
  "quote_snapshot": {
    "input_mode": "bundle",
    "total_amount": "4500.0000"
  }
}

Niðurstöður úr finalize

Staða	HTTP	Lýsing	Næsta skref
succeeded	200	Samningur hefur verið stofnaður og fyrstu innheimtu lokið.	Vista contract_id og hefja reglulega stöðuvöktun eftir þörfum.
pending_external	200	Ytri færsluhirðir þarf að ljúka ferli áður en innheimta telst kláruð.	Fylgjast með checkout og tengdri innheimtulotu þar til staða breytist.
failed	400	Greiðslutilraun mistókst eftir að samningur og innheimtulota voru stofnuð.	Athuga contract_id og initial_billing_run_id í svari, lesa villusvar og meta hvort reyna eigi aftur eða bíða eftir annarri aðgerð.
Forsendubrestur	400	Beiðnigögn eða greiðsluforsendur stóðust ekki; enginn samningur stofnaður.	Leiðrétta beiðnigögn eða greiðslumáta áður en reynt er aftur.

Innheimtulotur og endurtekning

V2 innheimtulotur eru lesnar á:

GET /api/v2/billing-runs/
GET /api/v2/billing-runs/{id}/

Innheimtulotu sem hefur mistekist má reyna aftur með eftirfarandi slóð:

POST /api/v2/billing-runs/{id}/retry/

Svar frá smáatriðaslóð innheimtulotu sýnir meðal annars línur, tilraunir, tengdar færslur og stöðu.

Stytt svar gæti litið svona út:

{
  "id": 32,
  "contract_id": 33,
  "customer_id": 1008,
  "customer_reference": "customer-123",
  "period_start_at": "2026-05-20T00:00:00Z",
  "period_end_at": "2026-06-20T00:00:00Z",
  "state": "succeeded",
  "currency": "ISK",
  "subtotal_amount": "4500.0000",
  "tax_amount": "0.0000",
  "total_amount": "4500.0000",
  "attempt_count": 1,
  "lines": [
    {
      "id": 71,
      "price_id": 200,
      "price_version_id": 15,
      "product_name": "Vefáskrift",
      "quantity": 2,
      "line_total_amount": "4000.0000",
      "service_period_start_at": "2026-05-20T00:00:00Z",
      "service_period_end_at": "2026-06-20T00:00:00Z"
    }
  ],
  "attempts": [
    {
      "id": 44,
      "attempt_no": 1,
      "state": "succeeded",
      "transaction_id": 19,
      "fail_code": null,
      "fail_message": null
    }
  ]
}

Útgáfustefna og hraðatakmarkanir

V2 er útgáfustýrt með slóð, þ.e. undir /api/v2/. Ný samhæfisbrot ættu því að birtast undir nýrri aðalútgáfuslóð fremur en að breyta merkingu núverandi slóða í kyrrþey.

Engar skjalaðar hraðatakmarkanir eru skilgreindar á þessari síðu. Samþættingar ættu samt að gera ráð fyrir tímabundnum mistökum, nota endurtekningu með biðtíma og skrá svör með stöðukóðum á borð við 400, 404 og 5xx.

Dæmi um heildarflæði í Python

• python

import requests

API_KEY = 'your api key here'
headers = {
    "Authorization": f"Api-Key {API_KEY}",
    "Content-Type": "application/json",
}

quote_payload = {
    "customer_reference": "customer-123",
    "currency": "ISK",
    "bundle_template": 42,
    "bundle_item_selections": [
        {
            "bundle_item": 100,
            "selected_price": 200,
        }
    ],
    "initial_items": [
        {
            "price": 500,
            "quantity": 1,
        }
    ],
}

try:
    quote_response = requests.post(
        "https://askell.is/api/v2/subscription-offer-quotes/",
        json=quote_payload,
        headers=headers,
    )
    quote_response.raise_for_status()

    processor_response = requests.post(
        "https://askell.is/api/v2/payment-processor-options/",
        json=quote_payload,
        headers=headers,
    )
    processor_response.raise_for_status()
    processor_options = processor_response.json()["results"]

    # Hér er gert ráð fyrir að aðeins einn færsluhirðir komi til greina.
    # Ef fleiri en einn er í boði þarf samþættingin að leyfa val.
    checkout_payload = {
        **quote_payload,
        "collection_method": "card",
        "account_payment_processor": processor_options[0]["account_payment_processor_id"],
    }

    checkout_response = requests.post(
        "https://askell.is/api/v2/checkouts/",
        json=checkout_payload,
        headers=headers,
    )
    checkout_response.raise_for_status()
    checkout = checkout_response.json()

    finalize_response = requests.post(
        f"https://askell.is/api/v2/checkouts/{checkout['token']}/finalize/",
        json={},
        headers=headers,
    )
    finalized_checkout = finalize_response.json()

    if finalize_response.status_code == 400:
        contract_id = finalized_checkout.get("contract_id")
        initial_billing_run_id = finalized_checkout.get("initial_billing_run_id")

        if contract_id:
            # Greiðslutilraun mistókst, en samningur og innheimtulota gætu þegar verið til.
            # Hér ætti raunveruleg samþætting að skrá þetta og meta hvort reyna eigi aftur.
            print(
                "Checkout failed after contract creation",
                contract_id,
                initial_billing_run_id,
            )
        else:
            # Forsendubrestur: enginn samningur var stofnaður.
            finalize_response.raise_for_status()
    else:
        finalize_response.raise_for_status()
except requests.HTTPError as exc:
    response = exc.response
    try:
        error_body = response.json()
    except ValueError:
        error_body = {"raw": response.text}
    print(response.status_code, error_body)
    raise

Algengar villur

Villa	HTTP	Lýsing
customer_reference	400	Viðskiptavinur fannst ekki eða vantar í beiðnigögn.
account_payment_processor	400	Valinn færsluhirðir er ekki löglegur fyrir verðútreikninginn.
payment_method	400	Enginn staðfestur greiðslumáti fannst fyrir viðskiptavin.
bundle_item_selections	400	Verðval vantar eða passar ekki við pakkann.
additional_items	400	Val á viðbótarvöru passar ekki við virka reglu fyrir viðbótarvöru.
items	400	Beint verðval er ógilt eða passar ekki við gjaldmiðil.
Ekki fundið	404	Samningur, checkout eða innheimtulota fannst ekki fyrir aðganginn.