Checkout

What checkout() does

const response = await komerza.checkout(emailAddress, couponCode);

Checks the basket and the form

The basket can’t be empty, the email address has to be valid, and a coupon code, if you pass one, has to be 3 to 32 characters. Nothing is sent until these pass.

Runs a bot check

Most buyers never see it. Now and then one is asked to confirm they’re human in a small dialog. See Security.

Creates the order

Komerza prices it from the basket’s product IDs and quantities, and checks stock, quantity limits and the coupon.

Redirects to the hosted checkout

The browser goes to checkout.komerza.com, where the buyer chooses a payment method, answers any custom fields, links Discord if the product needs it, and pays.

You don’t redirect anyone yourself. By the time checkout() resolves successfully, the page is already on its way to the hosted checkout.

Parameters

Parameter	Type	Notes
`emailAddress`	`string`	Required. Where the receipt and the delivery go. Up to 256 characters
`couponCode`	`string`	Optional. 3 to 32 characters, not case-sensitive. Pass `undefined` when the field is empty

Returns

Promise<ApiResponse<Order>>. The call doesn’t throw when checkout fails - it resolves with success: false and says why:

interface ApiResponse<Order> {
  success: boolean;
  data?: Order; // the created order, when success is true
  message?: string; // why it failed, written for the buyer
  code?: string; // a machine-readable code for server-side failures
  invalidFields?: {
    fieldName: "emailAddress" | "couponCode";
    reason: string;
  }[];
}

When checkout fails

Show invalidFields next to the field they name, and message for everything else. Both are written for the buyer, so you can display them as they are. Caught in the browser, before anything is sent:

What	`message`	`invalidFields`
Empty basket	`Basket is empty`	-
Missing or invalid email	`A validation error has occurred`	`emailAddress`: “This is required”, “Must be a valid email address”
Coupon code too short or long	`A validation error has occurred`	`couponCode`: “Must be at least 3 characters”, “Cannot be longer than 32 characters”

Refused by Komerza when it creates the order:

What	`message`, for example	`code`
A likely typo in the email domain	In `invalidFields`: `emailAddress`: “Did you mean buyer@gmail.com?”	-
An email domain that can’t receive mail	”The email domain does not appear to accept emails. Please check for typos and try again.”	`ValidationError`
Not enough stock	”Sorry, Premium License cannot be purchased due to a lack of stock.”	`ProductUnavailable`
Under the minimum quantity	”Sorry, the minimum quantity for 1 Month is 2.”	`ProductUnavailable`
Over the maximum quantity	”Sorry, the maximum quantity for 1 Month is 5.”	`ProductUnavailable`
The product is on hold	”This product is marked as on hold, try again later.”	`ProductUnavailable`
Subscription and one-time items together	”Subscription and one-time products cannot be combined in a single order.”	`ValidationError`
A coupon code that doesn’t exist	”Please enter a valid coupon code.”	`CouponNotFound`
A coupon that can’t be used on this order	”Coupon cannot be applied to this order.”	`CouponNotApplicable`
The store can’t take orders right now	”This store is temporarily unavailable.”	`StoreUnavailable`
The store has no payment method for the order	”No available payment methods for this order.”	`NoPaymentGateway`

A coupon that doesn’t apply fails the whole checkout - the order isn’t created without it - so the buyer can fix or remove the code and try again. Network problems resolve too: after 15 seconds without an answer, message is Request timed out.

The basket afterwards

checkout() doesn’t empty the basket, and your storefront isn’t told when the buyer finishes paying. To give buyers a fresh cart once they’ve ordered, clear it as soon as checkout() succeeds:

const response = await komerza.checkout(email, coupon || undefined);
if (response.success) {
  komerza.clearBasket(); // the page is already leaving for the hosted checkout
}

The trade-off: a buyer who backs out of paying comes back to an empty cart. Leave the call out if you’d rather keep it.

Affiliates

If the buyer arrived through an affiliate link, checkout() credits the affiliate automatically. There’s nothing to pass. See Affiliate links.

Complete example

<form id="checkout-form" novalidate>
  <p id="summary"></p>

  <label for="email">Email address</label>
  <input id="email" type="email" autocomplete="email" required />
  <p class="error" data-error-for="emailAddress"></p>

  <label for="coupon">Coupon code (optional)</label>
  <input id="coupon" type="text" maxlength="32" />
  <p class="error" data-error-for="couponCode"></p>

  <p class="error" id="form-error"></p>
  <button type="submit" id="pay">Continue to payment</button>
</form>

<script>
  const form = document.getElementById("checkout-form");
  const pay = document.getElementById("pay");

  function renderSummary() {
    const count = komerza.getBasketItemCount();
    document.getElementById("summary").textContent =
      count === 0 ? "Your cart is empty" : `${count} item(s) in your cart`;
    pay.disabled = count === 0;
  }

  function clearErrors() {
    form.querySelectorAll(".error").forEach((element) => {
      element.textContent = "";
    });
  }

  form.addEventListener("submit", async (event) => {
    event.preventDefault();
    clearErrors();

    const email = document.getElementById("email").value.trim();
    const coupon = document.getElementById("coupon").value.trim();

    pay.disabled = true;
    pay.textContent = "Please wait…";

    const response = await komerza.checkout(email, coupon || undefined);

    if (response.success) {
      komerza.clearBasket();
      return; // on the way to the hosted checkout
    }

    // A field can fail more than one rule; show the first reason for each.
    let shown = false;
    for (const field of response.invalidFields ?? []) {
      const slot = form.querySelector(`[data-error-for="${field.fieldName}"]`);
      if (slot && !slot.textContent) {
        slot.textContent = field.reason;
        shown = true;
      }
    }
    if (!shown) {
      document.getElementById("form-error").textContent =
        response.message || "Checkout failed. Please try again.";
    }

    pay.disabled = false;
    pay.textContent = "Continue to payment";
  });

  komerza.on("basketchange", renderSummary);
  renderSummary();
</script>

Good practice

Show progress and block double clicks. The bot check and order creation can take a few seconds. Disable the button until checkout() resolves.
Check stock and limits while the buyer shops, not at checkout - see what the basket doesn’t check.
Keep subscriptions apart from one-time products. buyNow() is the simple way.
Only call checkout() from a user action, like a form submit - never on page load.

Basket

Managing what goes into the order

Built-in features

Affiliates, analytics and security

Getting Started

Client Library

What checkout() does

Parameters

Returns

When checkout fails

The basket afterwards

Affiliates

Complete example

Good practice

Next

Basket

Built-in features

​What checkout() does

​Parameters

​Returns

​When checkout fails

​The basket afterwards

​Affiliates

​Complete example

​Good practice

​Next

Basket

Built-in features

What checkout() does

Parameters

Returns

When checkout fails

The basket afterwards

Affiliates

Complete example

Good practice

Next