kapruka_create_order
Idempotent
Create a guest-checkout order on Kapruka and return a click-to-pay link.
Builds a Kapruka order from the supplied cart + recipient + delivery + sender,
then returns a checkout URL the customer opens in a browser to complete payment.
No Kapruka account is required. Prices are locked for the lifetime of the link
(60 minutes) — the customer pays exactly the quoted grand total even if the
catalog price changes meanwhile.
Free public tier limits: 30 orders per hour per client IP. Cart up to 30 items,
quantity up to 99 per item. A fresh idempotency key is generated per call so
retries on transient errors return the same checkout URL rather than duplicates.
Args:
params (CreateOrderInput):
- cart (list[CartItem]): 1–30 lines. Catalogue line: product_id, quantity (default 1), optional icing_text (cakes only).
Custom cake line: custom_cake_request_id + phone — orders the cake Kapruka staff quoted via
kapruka_custom_cake_status (status must be 'quoted'; quantity is always 1; never send a price).
Lines can be mixed in one order — one delivery fee covers everything; the whole cart must be
deliverable to delivery.city. Only place a custom cake order after the customer clearly
accepted the quoted total.
- recipient (Recipient): name + phone (E.164 +9477… or local 077…)
- delivery (Delivery): address, city (must be Kapruka-deliverable — use kapruka_list_delivery_cities), location_type (house/apartment/office/other, default house), date (YYYY-MM-DD, today-or-future Asia/Colombo), optional instructions, type ('standard' default | 'economy')
- sender (Sender): name + anonymous flag
- gift_message (Optional[str]): Up to 300 chars
- currency (str): LKR (default), USD, GBP, AUD, EUR
- response_format (str): 'markdown' (default) or 'json'
Returns:
str: Order confirmation with checkout URL.
JSON schema:
{
"checkout_url": str, # Open in browser to pay (no login required)
"order_ref": str, # e.g. "ORD-20260520-7823"
"order_id": str, # id used by the bank-deposit flow
"summary": {
"items_total": number,
"delivery_fee": number,
"addons_total": number,
"grand_total": number, # items_total + delivery_fee + addons_total
"currency": str,
"delivery_type": "standard" | "economy",
"delivery_date": str, # the date checkout will use — may differ from the one sent
"delivery_promise": str # economy only: quote as given
},
"expires_at": str # ISO 8601 — link stops working after this
}
Error: "Error (<code>): <message>" on failure. Common codes:
empty_cart, missing_field, past_delivery_date, product_not_found,
product_out_of_stock, city_not_deliverable (city not in the network at
all), date_not_deliverable, city_not_deliverable_for_item.
Custom cake lines add: request_not_found (404 — wrong id/phone or staff
removed it), quote_not_ready (409 — staff haven't priced it; check
kapruka_custom_cake_status later), quote_expired (410 — submit a new
kapruka_custom_cake_request). summary.items_total may differ from the
quoted cake total by a few rupees (USD round-trip) — quote the summary
numbers when asking for payment.
economy_not_available (HTTP 422): economy was requested but this order
cannot go economy. Nothing is created. Tell the customer it goes by
standard delivery (fee from kapruka_check_delivery) and, once they agree,
resend with delivery.type 'standard' and their date.
Economy-only items always go economy, even when 'standard' is sent; read
summary.delivery_type and summary.delivery_date and tell the customer the
date checkout will use.
city_not_deliverable_for_item (HTTP 422): at least one cart item (food /
hotel cake / liquor) cannot reach delivery.city. NOTHING is created — the
API never places a partial order and neither should you. The error text
names every blocking item and lists the cities the whole cart CAN go to.
Tell the customer which item blocks the order and offer to (a) change the
city to one of those, or (b) remove/replace that item. Never retry with
the same city. Avoid this entirely by calling kapruka_check_delivery with
`product_id` for each limited item before ordering.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |