Changelog
What changes in the public API and the webhooks of Kivoo.
2026-11 — amounts in Congolese francs
A backward-compatible addition: no version changes.
- Products and payment links: an amount in Congolese francs (
CDF) is in whole francs, a multiple of 100 in minor units (250000for 2,500 CDF).PATCH /v1/products/{id},POST /v1/payment-linksandPATCH /v1/payment-links/{id}refuse an amount with centimes:400 amount_not_whole. Other currencies do not change.
2026-10 — payment links without an image
A breaking change, with no version change.
- Payment links:
coverUrlno longer exists in the responses ofGET /v1/payment-links,GET /v1/payment-links/{id},POST /v1/payment-links,PATCH /v1/payment-links/{id},POST /v1/payment-links/{id}/disableandPOST /v1/payment-links/{id}/enable. A link has no image any more: its page and its share preview show the store’s logo. - The image addresses already returned in
coverUrlno longer answer.
2026-10 — checkout sessions without a promo code
A breaking change.
- Checkout sessions:
POST /v1/checkoutsno longer acceptscouponCode. A promo code never applies to a license. A request that still sends it gets400 validation_failed.amountis the license’s price. - Orders: a license order placed with a promo code is refused (
400 coupon_not_applicable).
2026-10 — country of a checkout session
A backward-compatible addition: no version changes.
- Checkout sessions:
POST /v1/checkoutsacceptscountry, the user’s country as an ISO 3166-1 alpha-2 code (GA). Any country Kivoo knows is accepted, even one with no open payment method. - The session returns that country in
country(nullwithout one), inPOST /v1/checkouts,GET /v1/checkouts/{id}andGET /v1/checkouts. - The session’s page opens on that country, and the user may pick another one. See Accept payments from your app.
2026-10 — checkout sessions
A backward-compatible addition: no version changes.
- A new resource, checkout sessions:
POST /v1/checkouts,GET /v1/checkouts/{id}andGET /v1/checkouts, with the scopescheckouts:readandcheckouts:write. Your application creates a payment page for one license and one of its users, who comes back to it once the payment is received. See Accept payments from your app. - Orders: a new field
checkout(id,externalReference,metadata),nullfor an order placed in the store, inGET /v1/orders,GET /v1/orders/{id}and theorder.paid,order.failed,order.refundedandpayment_link.paidevents. - License keys:
checkout, alwaysnullso far, names the session that sold the key, inGET /v1/license-keysand thelicense_key.*events. - Products:
license.appOnlysays a license is sold only from your application. It then has no page in the store:urlisnull.
2026-10 — licenses
A backward-compatible addition: no version changes.
- Products: the
LICENSEtype, a license that delivers one license key per order, appears inGET /v1/products(filtertype=LICENSE),GET /v1/products/{id}, the order lines (items[].type) and theproduct.publishedandproduct.archivedevents. - A new resource, license keys, with the scopes
license_keys:readandlicense_keys:write:- in read,
POST /v1/license-keys/validatechecks the key your user entered, andGET /v1/license-keys,GET /v1/license-keys/{id}andGET /v1/license-keys/{id}/activationslist and read the store’s keys; - in write,
POST /v1/license-keys/activateandPOST /v1/license-keys/deactivatemanage a key’s devices, andPOST /v1/license-keys/{id}/revokerevokes it.
- in read,
- Webhooks: six new events,
license_key.issued,license_key.activated,license_key.deactivated,license_key.revoked,license_key.expiringandlicense_key.expired. Webhooks created before are not subscribed to them: check them on their page to receive them.
See Check a license key.
2026-10 — courses
A backward-compatible addition: no version changes.
- Products: the
COURSEtype, a course made of video lessons the buyer follows on Kivoo, appears inGET /v1/products(filtertype=COURSE),GET /v1/products/{id}, the order lines (items[].type) and theproduct.publishedandproduct.archivedevents. - Publishing a course with
PATCH /v1/products/{id}needs at least one displayed lesson with a ready video. Otherwise Kivoo answers422 product_incompletewithdetails.missing: ["lesson"], where it used to answerproduct_type_unavailable. The values ofdetails.missingare listed in Conventions. - Open pricing (
pricing: "OPEN") and the cover image (coverImageUrl), so far for downloadable products only, apply to courses too.
2026-10 — promo codes
A backward-compatible addition in shape, but the meaning of a field changes: check your integration if it reconciles an order’s amount with its lines.
- Orders:
amountis now what the buyer paid, net of the discount of a promo code. It can therefore be lower than the sum of the lines. Two new fields:discountAmount(the discount,0without a promo code) andcouponCode(the code entered,nullwithout one), inGET /v1/orders,GET /v1/orders/{id}and theorder.paid,order.failed,order.refundedandpayment_link.paidevents. - The discount applies to fixed-price lines only:
amount= sum of the lines −discountAmount.
2026-10 — refunds
A backward-compatible addition: no version changes.
- Webhooks: a new event,
order.refunded, sent when a paid order is refunded to the buyer.datais the order, asGET /v1/orders/{id}, withstatus: "REFUNDED". Webhooks created before are not subscribed to it: check it on their page to receive it. - Orders: the
REFUNDEDstatus, already in the enumeration, can now be reached. An order waiting for its refund staysPAID.
2026-10 — names of the images of a product
A breaking change, with no version change.
- Products:
coverUrlbecomesimageUrl(the image of the store’s cards) andpageImageUrlbecomescoverImageUrl(the 16:9 image at the top of the page of a downloadable product). This applies toGET /v1/products,GET /v1/products/{id},PATCH /v1/products/{id}and theproduct.publishedandproduct.archivedevents. The former fields no longer exist. - Image addresses already returned remain valid: they redirect to the new ones.
2026-09-29 — open pricing
A backward-compatible addition: no version changes.
- Products:
pricing(FIXEDorOPEN) andmaxPriceAmountinGET /v1/products,GET /v1/products/{id}and theproduct.publishedandproduct.archivedevents. An open-priced product (OPEN, downloadable products only) lets the buyer choose the price, frompriceAmountup tomaxPriceAmount, or ten timespriceAmountwhen it isnull. PATCH /v1/products/{id}writes both fields, with the same rules as the dashboard:open_pricing_unsupported,open_price_below_floor(details.floor),open_price_max_invalid,compare_at_not_allowed.
2026-09 — v1
The first version of Kivoo’s public API.
API keys
- Keys per store, prefixed
kv_live_, shown once, with an optional expiry and at most ten active keys per store. - Scopes per resource: Store and Orders read-only, Products, Customers and Payment links read and write.
- A rate limit of 120 requests per minute and per key.
Public API (https://api.kivoo.africa/v1)
- Store:
GET /v1/store. - Products: list, read, update and publish (
GET /v1/products,GET /v1/products/{id},PATCH /v1/products/{id}). - Orders: list and read (
GET /v1/orders,GET /v1/orders/{id}). - Customers: list, read, create, update (
GETandPOST /v1/customers,GETandPATCH /v1/customers/{id}). - Payment links: list, read, create, update, pause and resume (
/v1/payment-links).
Webhooks
- Up to five HTTPS webhooks per store and six webhook events:
order.paid,order.failed,customer.created,product.published,product.archived,payment_link.paid, pluspingfor tests. - A
Kivoo-Signaturesignature (HMAC-SHA256) and a stable event id for idempotency. - Eight attempts over a little more than twenty-two hours, a thirty-day delivery journal, manual resend and automatic disabling after three days of failures.