Error codes.

Cause: No billing customer with this externalId – it is created on the first subscription or with upsertCustomer().

Fix: Call upsertCustomer({ externalId, email, name }) first, or check the id.

Cause: The planId is not among the plans passed to subkit().

Fix: Use an id from the configured plans (the MCP tool list_plans lists them).

Cause: The plan has no price for this interval, or it is hidden (no longer sold).

Fix: Offer only the intervals in plan.prices. A hidden plan stays with its subscribers but cannot be bought.

Cause: The customer already has a running subscription.

Fix: Change the plan with changePlan() instead of subscribe().

Cause: The action needs a running subscription, and the customer has none (never subscribed, or it ended).

Fix: Start one with subscribe(). getOverview() shows the current state.

Cause: Not possible in the current state: the checkout of the subscription is unfinished, or an open invoice has to be settled before a plan change.

Fix: Finish or cancel the checkout, or pay the open invoice, then try again.

Cause: An upgrade is charged right away and needs a saved card or TWINT – there is none.

Fix: Let the customer add one (POST …/payment-method) or switch to invoice.

Cause: The charge of an upgrade was declined (card declined, not enough funds, TWINT refused). The plan stays as it was.

Fix: Ask the customer to update the payment method, then try again.

Cause: The payment provider could not be reached or answered with an error (this is not a declined card).

Fix: Try again later. Check the provider’s status and the API key (zahls.ch: instance and key).

Cause: No invoice with this id for this customer – or, when paying, no open one.

Fix: Check the id and that the invoice belongs to the signed-in customer.

Cause: An invoice of the customer is overdue or written off; nothing new is sold until it is paid.

Fix: Pay it first (POST …/invoices/:id/pay or by QR-bill), then try again.

Cause: This payment option (card / TWINT or invoice) is not enabled in collectionMethods of the handler.

Fix: Add it to collectionMethods, or offer only the enabled options.

Cause: Another request is changing the same subscription, order, cart or stock at this moment (e.g. a renewal or a webhook).

Fix: Try again in a moment – nothing is lost.

Cause: Your rateLimit callback refused the request, or too many webhooks arrived for one payment.

Fix: Wait the seconds in Retry-After. If real customers hit the limit, raise it.

Cause: A webhook could not be verified: unknown transaction, amount or currency differ, or the body is not JSON.

Fix: Point the provider’s webhook (format JSON) to …/webhook and use the same instance and API key as the kit. Forged requests end here on purpose.

Cause: The authorize (or identify) callback of the handler did not accept the request – no session, or no access.

Fix: Send the session cookie or token with the request and check the callback.

Cause: A POST without Content-Type: application/json. The handlers require it as CSRF protection.

Fix: Send JSON with exactly this content type – the React clients of the kits already do.

Cause: The request body is not valid JSON.

Fix: Send a JSON object as the body.

Cause: A field is missing, has the wrong type or is out of range (e.g. an unknown interval, a negative amount, a link that is not http(s)).

Fix: Check the field the message names against the README of the kit.

Cause: No route for this method and path below the basePath of the handler.

Fix: Check that basePath matches where the route is mounted, and the HTTP method.

Cause: An unexpected error (database, bug). The details are not sent to the client.

Fix: Look at onError and the server log. A bug in a kit: report it with the stack trace.

Cause: No product with this id or slug.

Fix: Check id or slug. Archived products are only in the back office.

Cause: No variant with this id.

Fix: Use an id from product.variants.

Cause: The product or variant is a draft or archived.

Fix: Activate it in the back office, or remove it from the cart.

Cause: Fewer items in stock than asked for (stock is reserved at checkout).

Fix: Lower the quantity – the message says how many are left.

Cause: A quantity below 1 or above the maximum per line, or too many items in the cart.

Fix: Use a whole number within the limit the message names.

Cause: No cart with this token (a wrong token, or an old cart that was abandoned).

Fix: Create a new cart – the React provider does this by itself.

Cause: Checkout of a cart without items.

Fix: Add items first.

Cause: The cart was already turned into an order.

Fix: Show the order, or start a new cart.

Cause: Unknown, expired, inactive or used-up discount code.

Fix: Check the code in the back office (list_discounts).

Cause: The code is valid, but this cart does not qualify (minimum order value, products).

Fix: Meet the conditions, or remove the code.

Cause: Unknown, disabled or expired gift card, or its balance is too low.

Fix: Check the code (dashes and case do not matter) and the balance.

Cause: Checkout without an email address.

Fix: Set email in the cart details (updateCartDetails()).

Cause: Physical items need a shipping address.

Fix: Set shippingAddress in the cart details.

Cause: Physical items, but no shipping method chosen.

Fix: Set shippingRateId to one of the offered rates.

Cause: The chosen shipping method does not exist or does not fit this cart.

Fix: Pick one of the shippingOptions of the cart.

Cause: The chosen shipping rate has a schedule, but the cart has no pickup or delivery day yet – or no time window although there are some.

Fix: Set a day from shippingOptions[].schedule.dates (and a window from timeWindows) with updateCartDetails({ fulfillmentDate, fulfillmentWindow }).

Cause: The day or time window is not (or no longer) offered: before the lead time, after the cutoff, on a closed day or beyond maxDays.

Fix: Choose a day from the current schedule.dates of the shipping rate – the list changes over time and with the products in the cart.

Cause: The payment method (online or invoice) is not offered for this shop or order, or no provider is configured.

Fix: Configure the provider and the methods in createShop(), or choose another method.

Cause: The customer has no (such) saved payment method: none saved yet, removed, refused by the provider and deactivated, or it belongs to another customer.

Fix: Order without useSavedPaymentMethod (payment link) and let the customer save one with savePaymentMethod: true.

Cause: The amount due differs from the one the customer confirmed (expectedAmount), e.g. because a price, discount or shipping changed. Nothing was charged.

Fix: Quote the order again (quoteOrder / quote_order), show the customer the new amount and order again with the confirmed amount.

Cause: No order with this id, or the token of the order link does not match.

Fix: Check the id and the token of the order link.

Cause: Not possible in the state of the order: paid already, cannot be paid, not paid yet (refund), canceled.

Fix: Read status, paymentStatus and fulfillmentStatus of the order first.

Cause: The refund is more than what is left to refund, or the gift cards of the order were used already.

Fix: Refund at most the amount in the message.

Cause: A product slug, SKU or discount code with this value exists already.

Fix: Choose another one, or change the existing record.

Cause: The payment provider could not be reached or answered with an error (this is not a declined card).

Fix: Try again later. Check the provider’s status and the API key (zahls.ch: instance and key).

Cause: Another request is changing the same subscription, order, cart or stock at this moment (e.g. a renewal or a webhook).

Fix: Try again in a moment – nothing is lost.

Cause: Your rateLimit callback refused the request, or too many webhooks arrived for one payment.

Fix: Wait the seconds in Retry-After. If real customers hit the limit, raise it.

Cause: A webhook could not be verified: unknown transaction, amount or currency differ, or the body is not JSON.

Fix: Point the provider’s webhook (format JSON) to …/webhook and use the same instance and API key as the kit. Forged requests end here on purpose.

Cause: A bank import, but the back office handler has no payment slip to compute the references.

Fix: Pass receipts.paymentSlip (e.g. swissQrBill()) to createShopAdminHandler().

Cause: The bank file is not a camt.053 or camt.054 XML document.

Fix: Export camt.054 (or camt.053) as XML from e-banking and send it as { "camt": "<?xml …" }.

Cause: HS-Soft (WaWiAssist) refused the request: invalid API key, a channel the key may not write, a locked order date, an order that is already invoiced or an unknown article. error.details.type names the reason.

Fix: Fix the cause (check the API key with HS-Soft, correct the date or article) and send the order again with syncOrder(id, { force: true }). Retrying unchanged will not help.

Cause: HS-Soft could not be reached or failed temporarily (503, timeout, gateway error).

Fix: syncOrders() tries again by itself after retryMinutes. If the order is uncertain, first check in WaWiAssist whether it arrived – only then send it again.

Cause: An order line or the shipping costs have no HS-Soft article – the product does not come from the import.

Fix: Import the product from HS-Soft, set orders.articleId or orders.shippingArticleId, or leave the order out with orders.filter.

Cause: Swiss Post refused the request: client or scopes of the Digital Commerce API, the franking licence, a combination of services the item cannot have, an address Swiss Post cannot deliver to – or an item abroad (labels are for Switzerland and Liechtenstein). error.details.errors lists the Swiss Post codes (E2001 …).

Fix: Fix the cause (check client and scopes with Swiss Post, the licence, the services of the shipping rate or the address) and create the label again. Retrying unchanged will not help.

Cause: Swiss Post could not be reached or failed temporarily (timeout, 5xx, E9999).

Fix: Create the label again later. Address suggestions and the address check at checkout do not fail because of it – the order goes on without them.

Cause: The authorize (or identify) callback of the handler did not accept the request – no session, or no access.

Fix: Send the session cookie or token with the request and check the callback.

Cause: A POST without Content-Type: application/json. The handlers require it as CSRF protection.

Fix: Send JSON with exactly this content type – the React clients of the kits already do.

Cause: The request body is not valid JSON.

Fix: Send a JSON object as the body.

Cause: A field is missing, has the wrong type or is out of range (e.g. an unknown interval, a negative amount, a link that is not http(s)).

Fix: Check the field the message names against the README of the kit.

Cause: No route for this method and path below the basePath of the handler.

Fix: Check that basePath matches where the route is mounted, and the HTTP method.

Cause: The back office API accepts only GET and POST.

Fix: Use POST for changes.

Cause: The request body is too large (100 kB; bank files 20 MB).

Fix: Send less – split a large bank file, for example.

Cause: An unexpected error (database, bug). The details are not sent to the client.

Fix: Look at onError and the server log. A bug in a kit: report it with the stack trace.