Á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.

Hafi sendingarleiðin verðskrá eftir svæðum og þyngdarbilum er gjaldið reiknað við stofnun checkout út frá póstnúmeri afhendingarheimilisfangsins (delivery_address í beiðninni, annars heimilisfang viðskiptavinarins) og þyngd vörunnar (weight_grams á vörunum margfaldað með magni; vörur með stærðir fá rúmmálsþyngd sé hún hærri). Nái verðskráin ekki yfir sendinguna — póstnúmerið er utan allra svæða, einhverja vöru vantar þyngd eða sendingin er þyngri en efsta bilið — er beiðninni hafnað með 400, shipping skýringu og shipping_code með gildið shipping_not_available. Afritið á samningnum skráir þá zone_name og weight_band (lágmark-hámark í grömmum) sem verðið var lesið úr; bæði eru tómir strengir fyrir leið með fast verð.

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

Sendingargjaldið er hluti af tilboðinu: subtotal_amount, tax_amount og total_amount á checkout-svarinu innihalda það, og shipping_fee sýnir gjaldið sundurliðað (amount, subtotal_amount, tax_amount, total_amount) eða null. Upphæðin sem kortið er staðfest fyrir er því sú sama og innheimt er. Sendi fyrsta tímabilið enga vöru — prufutímabil frestar vörunum til fyrstu endurnýjunar — er shipping_fee null og gjaldið er hvorki í checkout-upphæðinni né fyrstu innheimtunni; samþykkta verðið er samt skráð í afritinu og fyrsta innheimtan sem sendir vöru rukkar það.

Hver innheimta sem sendir vöru fær línu af gerðinni shipping í lines með gjaldinu, og total_amount innheimtunnar (og færslan sem er rukkuð) inniheldur það. Fyrsta innheimtan sem sendir vöru — fyrsta innheimtan, eða fyrsta endurnýjunin eftir prufutímabil — rukkar nákvæmlega samþykkta gjaldið úr afritinu; síðari endurnýjanir nota gildandi verð sendingarleiðarinnar og meta frísendingarmörkin á móti vöruupphæð endurnýjunarinnar eftir afslætti. Afsláttarkóðar lækka ekki gjaldið. Sé leiðinni eytt er samþykkta gjaldið úr afritinu notað. Gjaldið er aðeins innheimt þegar shipping eiginleikinn er virkur fyrir reikninginn; sendingarval sem var skráð áður en gjöld voru innheimt er ekki rukkað.

Virðisaukaskattur á gjaldið fylgir tax_rate sendingarleiðarinnar (stillt í stjórnborðinu) eða sjálfgefnu skattþrepi reikningsins sé það ekki sett. Rafrænar pantanir og innheimtur án vörulínu fá enga sendingarlínu.

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

• reference, tilvísun samningsins í ytra kerfi, sjá Tilvísun og lýsigögn samnings

• 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.
reference	Tilvísun samnings. Aðeins samningar með nákvæmlega sömu tilvísun eru sýndir.

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 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.
reference	Tilvísun samningsins í ytra kerfi, eða null. Sjá Tilvísun og lýsigögn samnings.
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	Lýsigögn samþættingarinnar, auk uppruna samningsins í askell_source. Sjá Tilvísun og lýsigögn samnings.
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, reference, 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.

Tilvísun og lýsigögn samnings

reference er tilvísun samningsins í ytra kerfi, til dæmis pöntunarnúmer söluaðila. Hún er óháð customer_reference, sem er tilvísun viðskiptavinarins. reference má vera að hámarki 128 stafir og má ekki innihalda kommu; annars er beiðninni hafnað með 400 og villu á reference. Autt gildi eða null þýðir engin tilvísun. Tilvísunina má senda við stofnun samnings, breyta henni eða hreinsa hana með PATCH og sía lista eftir henni með ?reference=.... V2 greiðslusíður setja subscription_reference úr slóð síðunnar í reference, sjá Greiðslusíður. Samningur úr checkout fær contract_reference, sem bakendi söluaðila sendir þegar hann stofnar checkout-lotu eða checkout með POST /api/v2/checkouts/, sjá Tilvísun samnings.

metadata eru lýsigögn samþættingarinnar. Samningur sem verður til í checkout fær lýsigögn checkout-lotunnar og checkout, sjá Innfellt kaupferli, og Áskell skráir uppruna samningsins í askell_source:

askell_source.type	Uppruni samnings
checkout_session	Checkout í checkout-lotu. Með fylgja checkout_session_token, checkout_id og checkout_token.
checkout	POST /api/v2/checkouts/ án lotu. Með fylgja checkout_id og checkout_token.
payment_page	V2 greiðslusíða. Með fylgir payment_page_id.

Samningar sem stofnaðir eru beint með POST /api/v2/subscription-contracts/ fá engan askell_source; þar er metadata vistað eins og það er sent.

Áskell notar sjálfur eftirfarandi lykla í metadata samninga: askell_source, billing_anchor_mode, activation_failure, email_markers, copied_legacy_pauses, copied_legacy_extra_data, migration_source, migration_cadence_mode, legacy_subscription_ids og seed. billing_anchor_mode stýrir til dæmis því hvenær samningurinn er innheimtur. metadata í PATCH kemur í stað lykla samþættingarinnar en þessir lyklar haldast óbreyttir: þeir sem eru á samningnum halda gildi sínu og þeir sem sendir eru í beiðninni eru hunsaðir. {"metadata": {}} hreinsar því aðeins lykla samþættingarinnar. Þessir lyklar eru heldur ekki afritaðir á samninginn úr lýsigögnum checkout eða checkout-lotu.

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.

Skipulagðar breytingar eru afturkallaðar með POST /scheduled-changes/{scheduled_change_id}/cancel/, sjá Skipulagðar breytingar á liðum (apply_at=period_end).

Helstu beiðnireitir:

Aðgerð	Reitir	Skylda
POST /proration-preview/	operation (add_item, update_item, remove_item, pause, resume, cancel, restart, change_anchor) á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, apply_at, 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.

apply_at í items/update og proration-preview (með operation=update_item) segir til um hvenær breytingin tekur gildi:

• now (sjálfgefið): liðnum er breytt strax og breytingin er hlutfallsreiknuð frá effective_at. effective_at má ekki vera fram í tímann; slíkt gildi skilar 400 svari með code sem er future_effective_at_not_supported. Sleppið effective_at til að miða við tímann núna.

• period_end: breytingin bíður næstu endurnýjunar liðarins, sjá Skipulagðar breytingar á liðum (apply_at=period_end).

Forskoðun update_item skilar auk þess apply_at, scheduled_for (tíminn sem skipulögð breyting tekur gildi, annars null), next_billing_at_after_change (næsta innheimta liðarins eftir breytinguna) og billing_cadence_after_change (innheimtutíðni samningsins eftir breytinguna, á sama formi og billing_cadence). Þessir reitir fylgja ekki forskoðun annarra aðgerða.

Skipulagðar breytingar á liðum (apply_at=period_end)

Með apply_at=period_end helst núverandi verð liðarins í gildi út núverandi þjónustutímabil, án endurgreiðslu, og nýtt verð, magn eða afsláttur tekur gildi við næstu endurnýjun. Þetta hentar til dæmis til að lækka áskrift úr Pro í Plus á sama tímabili, eða til að fara af ársverði yfir á mánaðarverð við lok þess árs sem þegar hefur verið greitt fyrir.

• Ekkert er skuldfært og engar hlutfallslínur verða til þegar breytingin er skráð. Forskoðunin skilar net_amount_due_now sem 0, engum línum, og next_billing_estimate miðast við endurnýjun á nýja verðinu.

• effective_at, settlement_behavior og include_pending_adjustments eru ekki leyfð með period_end og proration_behavior má aðeins vera none; annað skilar 400 svari (effective_at sem reitavilla, hitt með code sem er invalid_apply_at).

• items/update skilar change_id sem null og skipulögðu breytingunni í scheduled_change. Liðurinn sjálfur er óbreyttur þar til breytingin tekur gildi.

• Þegar innheimtulota endurnýjunarinnar er stofnuð er breytingunni fyrst beitt á liðinn og lotan síðan reiknuð á nýju gildunum. Þá verður til breyting (update_item með proration_behavior=none) í sögu samningsins. Við breytingu á innheimtutíðni hefst nýja tíðnin við endurnýjunina, til dæmis mánaðartímabil í stað árs.

• Hver liður getur aðeins haft eina skipulagða breytingu. Ný skipulögð breyting eða tafarlaus breyting á sama lið skilar 409 svari með code sem er scheduled_change_exists; afturkallið þá fyrst þá sem fyrir er.

• Ef liðurinn er fjarlægður eða samningnum sagt upp (strax, við lok tímabils eða á tilteknum degi sem er á eða fyrir endurnýjunina) er skipulögðu breytingunni sjálfkrafa aflýst. Ekki er hægt að skipuleggja breytingu á samning sem endar við lok tímabils (code contract_cancellation_scheduled).

• Samningur í hléi stofnar engar innheimtulotur, svo breytingin bíður fyrstu endurnýjunar eftir að hléi lýkur. Ef viðmiðunartími innheimtu breytist færist scheduled_for með næstu endurnýjun liðarins.

• Aðeins virkir samningar geta skipulagt breytingar.

Skipulagðar breytingar sem bíða birtast í scheduled_changes á samningnum og í scheduled_change á viðkomandi lið. Hver færsla inniheldur meðal annars id, contract_item, state (scheduled, applied, canceled eða failed), scheduled_for, price_id, price, quantity, discount_percent, unit_amount_override, from_price_id, from_quantity, applied_at, canceled_at, applied_change_id og billing_run_id.

POST /api/v2/subscription-contracts/{id}/scheduled-changes/{scheduled_change_id}/cancel/ afturkallar skipulagða breytingu sem hefur ekki tekið gildi (valkvæður reitur: reason). Svarið inniheldur scheduled_change, replayed og contract. Að afturkalla breytingu sem þegar hefur verið afturkölluð skilar replayed=true; breyting sem hefur tekið gildi skilar 409 með code scheduled_change_not_cancelable.

Vefkrókarnir subscription_contract_scheduled_change.created, subscription_contract_scheduled_change.applied og subscription_contract_scheduled_change.canceled eru sendir þegar breyting er skráð, tekur gildi eða er afturkölluð. Þeir falla ekki undir subscription_contract.*, sjá Skipulagðar breytingar á liðum (subscription_contract_scheduled_change.*).

Dæmi um að lækka lið við næstu endurnýjun:

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,
    "price": 789,
    "apply_at": "period_end",
    "idempotency_key": "item-456-plus-vid-endurnyjun"
  }'

Breyting á innheimtutíðni strax

Ef nýtt verð hefur aðra innheimtutíðni en núverandi verð (annað interval, interval_count, recurrence_type eða dagatal) og apply_at=now, hefst nýtt þjónustutímabil strax:

• Ónotaður hluti núverandi tímabils er kreditfærður miðað við það sem var innheimt fyrir það.

• Heilt tímabil á nýja verðinu er skuldfært frá effective_at (proration_factor er 1 fyrir hefðbundið tíðniverð).

• Viðmiðunartími innheimtu liðarins og samningsins færist á effective_at og næsta innheimta verður við lok nýja tímabilsins, til dæmis um ári síðar þegar farið er af mánaðarverði yfir á ársverð. next_billing_at_after_change í forskoðuninni sýnir þann tíma.

• Breytingin tekur aðeins gildi þegar mismunurinn hefur verið innheimtur. Þangað til helst liðurinn á núverandi verði og tíðni: items/update skilar applies_on_payment=true og liðurinn sýnir breytinguna í pending_interval_change (change_id, billing_run_id, status, price_id, quantity, effective_at, next_billing_at). Forskoðunin skilar einnig applies_on_payment. Þegar innheimtulotan tekst er liðnum breytt, nýja tímabilið veitt frá effective_at og vefkrókurinn subscription_contract_item.entitlement_changed sendur. Ef ekkert er eftir að innheimta (kreditinn nær yfir skuldfærsluna) tekur breytingin gildi strax.

• Á meðan beðið er eftir greiðslunni er endurnýjun liðarins á gömlu tíðninni haldið aftur, og aðrar breytingar á liðnum (tafarlausar eða skipulagðar) skila 409 með code pending_interval_change, sem og tilfærsla viðmiðunartíma innheimtu samningsins (change-anchor). Fjarlæging liðarins er ekki leyfð meðan innheimtulotan er opin (409 billing_run_overlap).

• Ef innheimtulotan mistekst endanlega er engu breytt og liðurinn heldur áfram að innheimtast á gömlu tíðninni. Takist síðar handvirk endurtekning lotunnar tekur breytingin gildi, nema liðnum hafi verið breytt, hann fjarlægður eða samningnum sagt upp í millitíðinni; þá er breytingin ekki framkvæmd. Endurnýjanir á gömlu tíðninni sem innheimtar voru eftir effective_at eru þá kreditfærðar á samninginn fyrir þann tíma sem nýja tímabilið nær yfir.

• Uppsögn samnings (strax eða við lok tímabils), fjarlæging liðarins eða tilfærsla viðmiðunartíma innheimtu eftir misheppnaða greiðslu aflýsir breytingunni og fellir niður innheimtulotu hennar sem ekki hefur verið innheimt.

• Mismunurinn er innheimtur strax, svo settlement_behavior er sjálfgefið invoice_now; next_invoice skilar 400 með code interval_change_requires_invoice_now. Með proration_behavior=none er enginn kredit reiknaður en nýja tímabilið er samt skuldfært að fullu og hefst strax. Ef kreditinn er hærri en skuldfærslan verður mismunurinn að inneign á samningnum.

• Breyting á innheimtutíðni er aðeins studd á samningum með einn innheimtulið; annars fæst 400 með code interval_change_requires_single_item. Sama gildir um apply_at=period_end.

Til að fara af ársverði yfir á mánaðarverð án endurgreiðslu skal nota apply_at=period_end.

Óþ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.
POST /change-anchor/	Færir viðmiðunartíma innheimtu, sjá Viðmiðunartími innheimtu færður.

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
POST /change-anchor/	new_billing_anchor_at, effective_at, reason, proration_behavior, settlement_behavior, include_pending_adjustments, idempotency_key, preview_token	new_billing_anchor_at skylda; aðrir 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, restart eða change_anchor.

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 handvirkar leiðréttingar eru ekki hluti af ytra V2 API flæðinu eins og er, en endurgreiða má alla skuldfærslu innheimtulotu, sjá Endurgreiðsla innheimtulotu.

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.

Inneign dregst sjálfkrafa frá síðari innheimtulotum samningsins, bæði endurnýjunum og hlutfallslotum sem innheimtar eru strax, 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. Ef innheimtulota mistekst endanlega eða er felld niður er inneignin sem hún nýtti losuð aftur.

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"
  }'

Viðmiðunartími innheimtu færður

POST /api/v2/subscription-contracts/{id}/change-anchor/ færir viðmiðunartíma innheimtu á virkum samningi. Næsta innheimta samningsins og allra virkra samningsliða hans færist á new_billing_anchor_at: billing_anchor_at fær nýja tímann, next_billing_at verður sá dagur á innheimtutíma samningsins og næsta reglulega tímabil hefst þar. Nýi tíminn má vera fyrr eða seinna en núverandi next_billing_at.

Reitur	Lýsing
new_billing_anchor_at	Skylda. Nýr tími næstu innheimtu. Verður að vera á eftir effective_at.
effective_at	Tíminn sem hlutfallsreikningurinn miðast við. Sjálfgefið tíminn þegar kallið berst. Til að nota preview_token eða endurtaka kallið með idempotency_key þarf að senda fastan tíma, annars telst endurtekið kall ekki sama kallið.
proration_behavior	none, create_prorations eða always_invoice. Sjálfgefið gildi samningsins, create_prorations nema annað sé stillt. Með none færist tíminn án hlutfallslína.
settlement_behavior	next_invoice eða invoice_now. Sjálfgefið invoice_now með always_invoice en annars next_invoice.
include_pending_adjustments	Tekur biðlínur samningsins með í innheimtulotuna sem er stofnuð strax. Aðeins gilt með settlement_behavior=invoice_now.
reason	Ástæða breytingarinnar.
idempotency_key	Kall með sama lykli og sömu reitum, effective_at meðtöldum, skilar fyrri niðurstöðu með replayed=true í stað þess að færa tímann aftur.
preview_token	preview_token úr proration-preview með operation=change_anchor og sömu reitum.

Með hlutfallsreikningi fær hver virkur liður, nema verð hans sé never_prorate, tvær línur með proration_reason sem er anchor_changed:

• Inneignarlínu (proration_credit) fyrir ónotaðan hluta greidda tímabilsins, frá effective_at til loka þess. Hún verður aðeins til ef liðurinn á greitt tímabil sem nær yfir effective_at.

• Skuldfærslulínu (proration_debit) frá effective_at fram að nýja viðmiðunartímanum, hlutfallsreiknaða af heilu tímabili liðarins sem endar á nýja tímanum. Með mánaðarverð, effective_at 20. janúar og nýjan viðmiðunartíma 1. febrúar er hlutfallið 12/31, þ.e. 12 dagar af tímabilinu 1. janúar til 1. febrúar.

Í heild greiðir viðskiptavinurinn því í meginatriðum fyrir bilið milli loka greidda tímabilsins og nýja tímans, eða fær inneign ef nýi tíminn er fyrr. Með next_invoice bíða línurnar og fara á innheimtuna á nýja tímanum ásamt fyrsta reglulega tímabilinu þaðan. Aðrar biðlínur samningsliðanna, til dæmis frá fyrri breytingu með next_invoice, færast á sömu innheimtu. Með invoice_now er strax stofnuð innheimtulota fyrir mismun línanna; sé inneignin hærri en skuldfærslan verður mismunurinn að inneign á samningnum.

Mikilvægt

Tilfærslan lengir ekki þjónusturéttindi. entitled_until, current_service_period_start_at og current_service_period_end_at liðanna haldast óbreytt, og innheimtulotan sem invoice_now stofnar breytir þeim ekki heldur þótt hún takist, því réttindi eru aðeins veitt út frá reglulegum línum innheimtulotu. Ef nýi tíminn er seinna en lok greidda tímabilsins verður service_state samningsins past_due og service_active false frá lokum greidda tímabilsins þar til innheimtulotan á nýja tímanum veitir réttindi fyrir næsta tímabil, sem gerist sjálfgefið þegar hún tekst.

Kallið skilar 400 eða 409 með code úr eftirfarandi töflu:

code	HTTP	Merking
invalid_contract_state	400	Samningurinn er ekki í stöðunni active.
invalid_billing_anchor	400	new_billing_anchor_at er ekki á eftir effective_at.
no_change	400	new_billing_anchor_at er sami tími og núverandi next_billing_at.
anchor_change_span_too_long	400	Með hlutfallsreikningi er nýi tíminn meira en eitt tímabil liðar á eftir effective_at.
invalid_recurrence	400	Með hlutfallsreikningi: tímabil liðar verður ekki reiknað út frá verði hans.
missing_price_version	400	Verð liðar hefur enga gilda verðútgáfu.
unsupported_settlement_behavior	400	settlement_behavior er credit_balance eða refund_manual.
invalid_include_pending_adjustments	400	include_pending_adjustments=true án settlement_behavior=invoice_now.
invalid_preview_token	400	preview_token er ógilt.
preview_expired	409	preview_token er útrunnið.
preview_stale	409	Samningurinn eða biðlínur hans hafa breyst frá forskoðun, eða reitirnir eru aðrir en þar.
billing_run_processing	409	Innheimtulota í vinnslu nær yfir tímabilið sem breytingin snertir.
billing_run_overlap	409	Áætluð innheimtulota nær yfir tímabilið sem breytingin snertir.
idempotency_key_conflict	409	idempotency_key var áður notaður með öðrum reitum.
pending_interval_change	409	Breyting á innheimtutíðni liðar bíður greiðslu (sjá pending_interval_change liðarins).

Dæmi um að færa næstu innheimtu á 1. júní:

curl -X POST https://askell.is/api/v2/subscription-contracts/123/change-anchor/ \
  -H "Authorization: Api-Key your-secret-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "new_billing_anchor_at": "2026-06-01T00:00:00Z",
    "effective_at": "2026-05-16T00:00:00Z",
    "idempotency_key": "samningur-123-1-juni"
  }'

Svarið er á sama formi og svar items/update: change_id, billing_run_id (innheimtulotan sem invoice_now stofnaði, annars null), pending_adjustment_ids (biðlínur breytingarinnar), consumed_pending_adjustment_ids, replayed og contract.

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.

Með contract_reference má gefa samningnum sem checkout stofnar tilvísun, til dæmis pöntunarnúmer. Hún fer í reference samningsins um leið og hann er stofnaður og er því þegar í subscription_contract.created. Sömu reglur gilda og um reference, sjá Tilvísun og lýsigögn samnings og Tilvísun samnings.

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.

Hýst kortaform og innfelling

Þegar render_mode er generic_card_form má skrá kort í kortaformi sem Áskell hýsir:

POST /api/v2/checkouts/{token}/payment-method-registrations/

Svarið inniheldur checkout_url sem vísar á hýsta kortaformið og status_url sem sækir stöðu skráningarinnar með leynilegum API-lykli.

Hýsta kortaformið sendir Content-Security-Policy haus með frame-ancestors. Sjálfgefið gilda þar uppruna-heimildir reikningsins (checkout_allowed_origins). Til að fella formið inn á eigin vef má senda allowed_origin, annaðhvort þegar checkout er stofnaður eða þegar skráningin er stofnuð:

{
  "mode": "hosted",
  "allowed_origin": "https://shop.example",
  "return_url": "https://shop.example/complete"
}

allowed_origin er einn http(s) uppruni án slóðar. http er aðeins leyft fyrir localhost og loopback-vistföng (127.0.0.0/8 og [::1]). Uppruni á skráningu gengur framar uppruna á checkout, og uppruni sem er sendur með gengur framar uppruna-heimildum reikningsins. Vafraendapunktar checkout-lota taka ekki við allowed_origin; þar gilda uppruna-heimildir sölurásarinnar.

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, endurtekning og endurgreiðsla

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
    }
  ]
}

Sjá einnig

Innheimtulota sem greiðir fyrir áþreifanlega vöru býr til afgreiðslupöntun. Þær eru skjalaðar undir Afgreiðslupantanir V2.

Endurgreiðsla innheimtulotu

Skuldfærslu innheimtulotu sem hefur tekist má endurgreiða með eftirfarandi slóð:

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

Beiðnin hefur ekkert meginmál og krefst leynilegs API lykils. Opnir lyklar og eldri token-auðkenning eru ekki studd á þessari slóð.

Aðeins er hægt að endurgreiða innheimtulotu í stöðunni succeeded sem á uppgerða færslu, og færsluhirðir færslunnar þarf að styðja endurgreiðslur. Endurgreitt er að fullu: öll upphæð færslunnar er endurgreidd á greiðslumátann sem var skuldfærður. Hlutaendurgreiðslur eru ekki studdar.

HTTP	Lýsing	Næsta skref
200	Færsluhirðir endurgreiddi færsluna. Innheimtulotan er komin í stöðuna refunded, endurgreiðslan er skráð í metadata.transaction_refund og billing_run.changed atburður er sendur. Svarið er innheimtulotan.	Engin frekari aðgerð er nauðsynleg.
202	Endurgreiðslan sést ekki enn á innheimtulotunni, sem er enn í stöðunni succeeded. Annaðhvort tók færsluhirðir við endurgreiðslunni en hefur ekki lokið henni, til dæmis þegar Teya svarar með PENDING, eða færsluhirðir endurgreiddi færsluna og verið er að uppfæra innheimtulotuna. Beiðnin er skráð í metadata.refund_requests. Svarið er innheimtulotan.	Ekki meðhöndla svarið sem villu og ekki senda beiðnina strax aftur. Bíða eftir billing_run.changed atburðinum, eða lesa innheimtulotuna aftur, þar til hún er komin í stöðuna refunded.
400	Innheimtulotan er ekki í stöðunni succeeded, á enga uppgerða færslu (til dæmis lota með núllupphæð eða færsla sem þegar hefur verið endurgreidd), færsluhirðir styður ekki endurgreiðslur, eða færsluhirðir lauk ekki endurgreiðslunni.	Lesa villuboðin í error. Innheimtulotan er óbreytt.
404	Innheimtulota með þetta id fannst ekki á aðganginum.	Athuga id innheimtulotunnar.

Hver endurgreiðslubeiðni sem færsluhirðir tekur við er skráð í metadata.refund_requests innheimtulotunnar með actor, requested_at, outcome (refunded eða pending) og transaction_id. Beiðnir sem mistakast eru ekki skráðar.

Samhliða endurgreiðslubeiðnir fyrir sömu innheimtulotu eru afgreiddar ein í einu. Beiðni sem kemur eftir að fyrri beiðni endurgreiddi skuldfærsluna fær svarið 400 og innheimtulotan er í stöðunni refunded. Fáist ekkert svar við beiðni, til dæmis vegna tímamarka, skaltu lesa innheimtulotuna með GET /api/v2/billing-runs/{id}/ og athuga state og metadata.refund_requests áður en beiðnin er send aftur.

V2 payment.* atburðir bera uuid færslunnar og billing_run_id innheimtulotunnar sem skuldfærði hana. Notaðu billing_run_id í slóðinni hér að ofan. Eldri slóðin POST /api/payments/<uuid>/refund/ endurgreiðir aðeins stakar greiðslur. Fái hún uuid færslu sem V2 innheimtulota skuldfærði svarar hún með 400, þar sem billing_run_id fylgir og vísað er á POST /api/v2/billing-runs/{id}/refund/.

Ú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.