Kontorion Billing API
integerstringstringstringstring · enumstring · enumstringstring · enumstringstring · enumstringnumberintegerstringstringstringstringbooleannumberintegerintegerstringstringintegerstringstringstringbooleanbooleanstring · enumstringstringstringintegerstring · enum
string · enumstring · enumstring · enumstringstring · enumstringbooleannumberintegerintegerstringintegerstringbooleanstringstringstring · enumstring · enumstring · enumstringstring · enumstringstring · enumstringnumberintegerstringstringstringstringbooleannumberintegerintegerstringstringintegerstringstringstringbooleanbooleanstring · enumstringstringstringintegerstring · enum
stringstringstringstring[]string
string · requiredstring · enumstring · enumstringstring · enumstringstring · enumstringnumberintegerstringstringstringstringbooleannumberintegerintegerstringstringintegerstringstringstringbooleanbooleanstring · enumstringstringstringintegerstring · enum
string · requiredstring · enumstring · enumstring · enumstringstring · enumstringstringintegerbooleannumberintegerintegerstringintegerstringbooleanbooleanstringstringstring · enumstring · enumstring · enumstringstring · enumstringstring · enumstringnumberintegerstringstringstringstringbooleannumberintegerintegerstringstringintegerstringstringstringbooleanbooleanstring · enumstringstringstringintegerstring · enum
string · requiredstring · enumstring · enumstringstring · enumstringstring · enumstringnumberintegerstringstringstringstringbooleannumberintegerintegerstringstringintegerstringstringstringbooleanbooleanstring · enumstringstringstringintegerstring · enum
string · requiredstringstringstringstringstring · enumstring · enumstringstring · enumstringstring · enumstringnumberintegerstringstringstringstringstringbooleannumberintegerintegerstringstringintegerstringstringstringnumberintegerbooleanbooleanstring · enumstringstringstringintegerstring · enum
string · requiredstring · enumstring · enumstringstring · enumstringstring · enumstringnumberintegerstringstringstringstringbooleannumberintegerintegerstringstringintegerstringstringstringbooleanbooleanstring · enumstringstringstringintegerstring · enum
string · requiredstringbooleanstringstringstring
string · requiredstring[] · style: formstringstringstringstringstringstringstringstringintegerinteger
string · requiredinteger · requiredstringstringstringstringstringstringstringnumberintegerstringintegerstringstringstringstringstringbooleanstringstringstringintegerstring
Promotions allow you to offer discounts, credits, and special pricing to customers through coupon codes, automatic rules, or manual application.
Key concepts:
- Code - the coupon code a customer enters (e.g.,
SAVE20) - Effects - what the promotion does: percentage discount, fixed discount, free trial extension, or credit grant
- Conditions - eligibility rules: minimum spend, specific plans, customer segments, date ranges
- Budget - optional spending cap; the promotion deactivates when the budget is exhausted
- Stackable - whether this promotion can combine with other active promotions
- Simulation - preview the financial impact of a promotion before activating it
List promotions
GET
https://api.kontorion.eu/v1
/promotions
Returns a paginated list of promotions. Supports the unified field.op=value filter grammar (see /docs/pagination).
query Parameters
limitPage size
cursorPagination cursor
statusFilter by status (sugar for status.eq); also supports status.ne, status.in
visibilityFilter by visibility (sugar for visibility.eq); also supports visibility.in
List promotions › Responses
Paginated list wrapped in data envelope
object[]
application_timingEnum values:
NEXT_CYCLE
RETROACTIVE
IMMEDIATE
archetypeEnum values:
generic
coupon_discount
bundle_discount
volume_rebate
first_purchase_credit
free_trial
cross_sell_free
loyalty_ladder
archived_atbudget_behaviorEnum values:
SKIP
PARTIAL
codecondition_modeEnum values:
ALL
ANY
object
created_atcurrent_budget_usedcurrent_redemptionsdeleted_atdescriptionobject
head_version_ididis_phasedmax_budgetmax_redemptionsmax_redemptions_per_customernameorganization_idobject[]
populated when is_phased=true; single Default phase otherwise
prioritypublic_descriptionpublished_atpublished_byrequires_continuous_coveragestackablestatusEnum values:
draft
scheduled
active
archived
object
updated_atvalid_fromvalid_toversionvisibilityEnum values:
INTERNAL
PUBLIC
COUPON
Create a promotion
POST
https://api.kontorion.eu/v1
/promotions
Creates a new promotion in draft status
Create a promotion › Request Body
application_timingEnum values:
NEXT_CYCLE
RETROACTIVE
IMMEDIATE
archetypeEnum values:
generic
coupon_discount
bundle_discount
volume_rebate
first_purchase_credit
free_trial
cross_sell_free
loyalty_ladder
budget_behaviorEnum values:
SKIP
PARTIAL
codecondition_modeEnum values:
ALL
ANY
object
descriptionobject
is_phasedmax_budgetmax_redemptionsmax_redemptions_per_customernameobject[]
required when archetype is loyalty_ladder / growth_ladder
prioritypublic_descriptionstackableobject
valid_fromvalid_tovisibilityEnum values:
INTERNAL
PUBLIC
COUPON
Create a promotion › Responses
Wrapped in data envelope
application_timingEnum values:
NEXT_CYCLE
RETROACTIVE
IMMEDIATE
archetypeEnum values:
generic
coupon_discount
bundle_discount
volume_rebate
first_purchase_credit
free_trial
cross_sell_free
loyalty_ladder
archived_atbudget_behaviorEnum values:
SKIP
PARTIAL
codecondition_modeEnum values:
ALL
ANY
object
created_atcurrent_budget_usedcurrent_redemptionsdeleted_atdescriptionobject
head_version_ididis_phasedmax_budgetmax_redemptionsmax_redemptions_per_customernameorganization_idobject[]
populated when is_phased=true; single Default phase otherwise
prioritypublic_descriptionpublished_atpublished_byrequires_continuous_coveragestackablestatusEnum values:
draft
scheduled
active
archived
object
updated_atvalid_fromvalid_toversionvisibilityEnum values:
INTERNAL
PUBLIC
COUPON
Simulate promotion impact
POST
https://api.kontorion.eu/v1
/promotions/simulate
Runs the invoice pipeline without persisting invoices or incrementing promotion budgets
Simulate promotion impact › Request Body
billing_period_endbilling_period_startcustomer_idpromotion_idssubscription_idSimulate promotion impact › Responses
Wrapped in data envelope
object
object
object
Get a promotion
GET
https://api.kontorion.eu/v1
/promotions/{id}
Retrieves a single promotion by ID
path Parameters
idPromotion UUID
Get a promotion › Responses
Wrapped in data envelope
application_timingEnum values:
NEXT_CYCLE
RETROACTIVE
IMMEDIATE
archetypeEnum values:
generic
coupon_discount
bundle_discount
volume_rebate
first_purchase_credit
free_trial
cross_sell_free
loyalty_ladder
archived_atbudget_behaviorEnum values:
SKIP
PARTIAL
codecondition_modeEnum values:
ALL
ANY
object
created_atcurrent_budget_usedcurrent_redemptionsdeleted_atdescriptionobject
head_version_ididis_phasedmax_budgetmax_redemptionsmax_redemptions_per_customernameorganization_idobject[]
populated when is_phased=true; single Default phase otherwise
prioritypublic_descriptionpublished_atpublished_byrequires_continuous_coveragestackablestatusEnum values:
draft
scheduled
active
archived
object
updated_atvalid_fromvalid_toversionvisibilityEnum values:
INTERNAL
PUBLIC
COUPON
Update a promotion
PUT
https://api.kontorion.eu/v1
/promotions/{id}
Updates an existing promotion
path Parameters
idPromotion UUID
Update a promotion › Request Body
application_timingEnum values:
NEXT_CYCLE
RETROACTIVE
IMMEDIATE
archetypeEnum values:
generic
coupon_discount
bundle_discount
volume_rebate
first_purchase_credit
free_trial
cross_sell_free
loyalty_ladder
budget_behaviorEnum values:
SKIP
PARTIAL
codecondition_modeEnum values:
ALL
ANY
object
descriptionobject
effective_atADR-0006 edit-as-publish controls.
expected_versionis_phasedmax_budgetmax_redemptionsmax_redemptions_per_customernameobject[]
full replacement when non-nil; draft-only
prioritypublic_descriptionsave_as_draftstackableobject
valid_fromvalid_tovisibilityEnum values:
INTERNAL
PUBLIC
COUPON
Update a promotion › Responses
Wrapped in data envelope
application_timingEnum values:
NEXT_CYCLE
RETROACTIVE
IMMEDIATE
archetypeEnum values:
generic
coupon_discount
bundle_discount
volume_rebate
first_purchase_credit
free_trial
cross_sell_free
loyalty_ladder
archived_atbudget_behaviorEnum values:
SKIP
PARTIAL
codecondition_modeEnum values:
ALL
ANY
object
created_atcurrent_budget_usedcurrent_redemptionsdeleted_atdescriptionobject
head_version_ididis_phasedmax_budgetmax_redemptionsmax_redemptions_per_customernameorganization_idobject[]
populated when is_phased=true; single Default phase otherwise
prioritypublic_descriptionpublished_atpublished_byrequires_continuous_coveragestackablestatusEnum values:
draft
scheduled
active
archived
object
updated_atvalid_fromvalid_toversionvisibilityEnum values:
INTERNAL
PUBLIC
COUPON
Activate a promotion
POST
https://api.kontorion.eu/v1
/promotions/{id}/activate
Transitions a promotion from draft to active status
path Parameters
idPromotion UUID
Activate a promotion › Responses
Wrapped in data envelope
application_timingEnum values:
NEXT_CYCLE
RETROACTIVE
IMMEDIATE
archetypeEnum values:
generic
coupon_discount
bundle_discount
volume_rebate
first_purchase_credit
free_trial
cross_sell_free
loyalty_ladder
archived_atbudget_behaviorEnum values:
SKIP
PARTIAL
codecondition_modeEnum values:
ALL
ANY
object
created_atcurrent_budget_usedcurrent_redemptionsdeleted_atdescriptionobject
head_version_ididis_phasedmax_budgetmax_redemptionsmax_redemptions_per_customernameorganization_idobject[]
populated when is_phased=true; single Default phase otherwise
prioritypublic_descriptionpublished_atpublished_byrequires_continuous_coveragestackablestatusEnum values:
draft
scheduled
active
archived
object
updated_atvalid_fromvalid_toversionvisibilityEnum values:
INTERNAL
PUBLIC
COUPON
Copy a promotion as a new draft
POST
https://api.kontorion.eu/v1
/promotions/{id}/copy
Clones an existing promotion (any status) into a new draft
path Parameters
idSource promotion UUID
Copy a promotion as a new draft › Request Body
codenamevalid_fromvalid_toCopy a promotion as a new draft › Responses
Wrapped in data envelope
application_timingEnum values:
NEXT_CYCLE
RETROACTIVE
IMMEDIATE
archetypeEnum values:
generic
coupon_discount
bundle_discount
volume_rebate
first_purchase_credit
free_trial
cross_sell_free
loyalty_ladder
archived_atbudget_behaviorEnum values:
SKIP
PARTIAL
codecondition_modeEnum values:
ALL
ANY
object
object[]
created_atcurrent_budget_usedcurrent_redemptionsdeleted_atderived_statusdescriptionobject
object
head_version_ididis_phasedmax_budgetmax_redemptionsmax_redemptions_per_customernameorganization_idobject[]
populated when is_phased=true; single Default phase otherwise
prioritypublic_descriptionpublished_atpublished_byremaining_budgetremaining_redemptionsrequires_continuous_coveragestackablestatusEnum values:
draft
scheduled
active
archived
object
updated_atvalid_fromvalid_toversionvisibilityEnum values:
INTERNAL
PUBLIC
COUPON
Deactivate a promotion
POST
https://api.kontorion.eu/v1
/promotions/{id}/deactivate
Transitions a promotion from active to archived status
path Parameters
idPromotion UUID
Deactivate a promotion › Responses
Wrapped in data envelope
application_timingEnum values:
NEXT_CYCLE
RETROACTIVE
IMMEDIATE
archetypeEnum values:
generic
coupon_discount
bundle_discount
volume_rebate
first_purchase_credit
free_trial
cross_sell_free
loyalty_ladder
archived_atbudget_behaviorEnum values:
SKIP
PARTIAL
codecondition_modeEnum values:
ALL
ANY
object
created_atcurrent_budget_usedcurrent_redemptionsdeleted_atdescriptionobject
head_version_ididis_phasedmax_budgetmax_redemptionsmax_redemptions_per_customernameorganization_idobject[]
populated when is_phased=true; single Default phase otherwise
prioritypublic_descriptionpublished_atpublished_byrequires_continuous_coveragestackablestatusEnum values:
draft
scheduled
active
archived
object
updated_atvalid_fromvalid_toversionvisibilityEnum values:
INTERNAL
PUBLIC
COUPON
Preview promotion eligibility
POST
https://api.kontorion.eu/v1
/promotions/{id}/preview
Evaluates a single promotion's conditions for a customer and returns per-condition pass/fail details
path Parameters
idPromotion UUID
Preview promotion eligibility › Responses
Wrapped in data envelope
object[]
object
effect_summaryeligiblepromotion_idpromotion_namereasonList promotion versions (with lifecycle filter)
GET
https://api.kontorion.eu/v1
/promotions/{id}/versions
path Parameters
idPromotion UUID
query Parameters
statusLifecycle status filter (repeatable)
List promotion versions (with lifecycle filter) › Responses
200
OK
object[]
archived_reasoncreated_atcreated_byeffective_fromeffective_toidID is the *_versions.id UUID. Phase 2.D needs it so the FE stage-mode chip can wire selection→pin map without a separate number→ID lookup; older clients can ignore the field.
published_atstatususage_countversionobject[]
Get a promotion version snapshot
GET
https://api.kontorion.eu/v1
/promotions/{id}/versions/{version}
path Parameters
idPromotion UUID
versionVersion number
Get a promotion version snapshot › Responses
200
OK
application_timingbudget_behaviorcodedescriptioneffective_fromeffective_toidmax_budgetmax_redemptionsnameprioritypromotion_idpromotion_statuspublished_atpublished_byrelease_strategystackablestatusvalid_fromvalid_toversionvisibility