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 (250000 for 2,500 CDF). PATCH /v1/products/{id}, POST /v1/payment-links and PATCH /v1/payment-links/{id} refuse an amount with centimes: 400 amount_not_whole. Other currencies do not change.

A breaking change, with no version change.

  • Payment links: coverUrl no longer exists in the responses of GET /v1/payment-links, GET /v1/payment-links/{id}, POST /v1/payment-links, PATCH /v1/payment-links/{id}, POST /v1/payment-links/{id}/disable and POST /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 coverUrl no longer answer.

2026-10 — checkout sessions without a promo code

A breaking change.

  • Checkout sessions: POST /v1/checkouts no longer accepts couponCode. A promo code never applies to a license. A request that still sends it gets 400 validation_failed. amount is 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/checkouts accepts country, 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 (null without one), in POST /v1/checkouts, GET /v1/checkouts/{id} and GET /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} and GET /v1/checkouts, with the scopes checkouts:read and checkouts: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), null for an order placed in the store, in GET /v1/orders, GET /v1/orders/{id} and the order.paid, order.failed, order.refunded and payment_link.paid events.
  • License keys: checkout, always null so far, names the session that sold the key, in GET /v1/license-keys and the license_key.* events.
  • Products: license.appOnly says a license is sold only from your application. It then has no page in the store: url is null.

2026-10 — licenses

A backward-compatible addition: no version changes.

  • Products: the LICENSE type, a license that delivers one license key per order, appears in GET /v1/products (filter type=LICENSE), GET /v1/products/{id}, the order lines (items[].type) and the product.published and product.archived events.
  • A new resource, license keys, with the scopes license_keys:read and license_keys:write:
    • in read, POST /v1/license-keys/validate checks the key your user entered, and GET /v1/license-keys, GET /v1/license-keys/{id} and GET /v1/license-keys/{id}/activations list and read the store’s keys;
    • in write, POST /v1/license-keys/activate and POST /v1/license-keys/deactivate manage a key’s devices, and POST /v1/license-keys/{id}/revoke revokes it.
  • Webhooks: six new events, license_key.issued, license_key.activated, license_key.deactivated, license_key.revoked, license_key.expiring and license_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 COURSE type, a course made of video lessons the buyer follows on Kivoo, appears in GET /v1/products (filter type=COURSE), GET /v1/products/{id}, the order lines (items[].type) and the product.published and product.archived events.
  • Publishing a course with PATCH /v1/products/{id} needs at least one displayed lesson with a ready video. Otherwise Kivoo answers 422 product_incomplete with details.missing: ["lesson"], where it used to answer product_type_unavailable. The values of details.missing are 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: amount is 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, 0 without a promo code) and couponCode (the code entered, null without one), in GET /v1/orders, GET /v1/orders/{id} and the order.paid, order.failed, order.refunded and payment_link.paid events.
  • 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. data is the order, as GET /v1/orders/{id}, with status: "REFUNDED". Webhooks created before are not subscribed to it: check it on their page to receive it.
  • Orders: the REFUNDED status, already in the enumeration, can now be reached. An order waiting for its refund stays PAID.

2026-10 — names of the images of a product

A breaking change, with no version change.

  • Products: coverUrl becomes imageUrl (the image of the store’s cards) and pageImageUrl becomes coverImageUrl (the 16:9 image at the top of the page of a downloadable product). This applies to GET /v1/products, GET /v1/products/{id}, PATCH /v1/products/{id} and the product.published and product.archived events. 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 (FIXED or OPEN) and maxPriceAmount in GET /v1/products, GET /v1/products/{id} and the product.published and product.archived events. An open-priced product (OPEN, downloadable products only) lets the buyer choose the price, from priceAmount up to maxPriceAmount, or ten times priceAmount when it is null.
  • 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 (GET and POST /v1/customers, GET and PATCH /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, plus ping for tests.
  • A Kivoo-Signature signature (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.

On this page