Commerce Guide

This guide covers the merchant side of Kubuli eCommerce, used from the mobile app.

Claim your place

1. Open the merchant view in the app and submit a place claim.
2. The claim is created with status pending.
3. Wait for platform approval. Until approved, claim-related APIs return 403.

   NOTE

   Approval has no SLA — it is a manual review step.

4. Once approved, you can manage the storefront.

Rate limit: a maximum of 5 claims per hour per account.

Build your storefront

• Categories & items: managed under each claimed place (/me/places/:place_id). Create categories, then items within them.
• Prices are append-only: you add a new price entry rather than editing the old one. Historical prices are preserved.
• Currency: all amounts are in XCD cents (e.g. 1000 = 10.00 XCD).

Your public menu is available at GET /places/:id/menu with no auth required.

Manage orders

• View your orders at GET /me/orders, or filter by place with GET /me/places/:id/orders.
• Order responses show a customer_short_id only — customer PII is not exposed to merchants.
• State flow you control: paid → confirmed → completed (or cancelled).

WARNING

Refunds are not available to merchants. Refund actions are admin-only and return 403 for merchant tokens. Do not promise refunds to customers from the merchant app.

Checkout & payment expectations

When a customer checks out:

• The request requires an Idempotency-Key header. Missing or empty keys are rejected with 400.
• Checkout is limited to 10 requests/minute per client.
• Stripe verifies each delivery's signature with a 300-second timestamp tolerance. This is separate from webhook idempotency.

Track disbursements

• Disbursements are read-only for merchants.
• notes on a disbursement are admin-only and not visible to you.
• Fetching a disbursement that is not yours returns 404.

WARNING

Payouts are currently manual via Mobanking. There is no automatic payout. Bank-account payout is not implemented.

Limitations (current MVP)

• Cart is single-merchant; adding an item from another merchant returns 409 cart_conflict. Cart entries expire after 24 hours.
• No guest checkout.
• No product variants, stock tracking, delivery, or order reviews.
• Order-item integrity hardening (KUB-207 follow-up F6) is pending — treat order item counts as not yet fully protected against data loss.

See the Commerce API Reference for full request and response details.