Skip to Content
RewardsOrders

Simple Order Flow with KamioKash API

The flow for placing a simple voucher order through the KamioKash API, from the view of an end user in a customer application.

This document describes the interaction flow for placing a simple voucher order through the KamioKash system, from the perspective of an end user interacting via a customer application. It details both the successful "happy path" and failure handling mechanisms.

🧩 Components Involved

  • User: The end user initiating the order.
  • Customer App: The frontend or interface where the user interacts.
  • Customer API: The backend API maintained by the customer, acting as a middle layer.
  • KamioKash API: The external rewards platform API used to fulfill the voucher.
  • Customer DB: The customer's internal database used to persist order data.

▶️ Sequence of Events

1. Order Initiation

  • User → Customer App: The user initiates an order (e.g., clicks a "Redeem Now" button).
  • Customer App → Customer API: Sends POST /order.

2. Voucher Request

  • Customer API → KamioKash API: Sends POST /order/simple to request a voucher.

✅ Happy Path: Voucher Code Issued

  • KamioKash API → Customer API: Responds with { voucherCode }.
  • Customer API → Customer DB: Stores the voucherCode.

If storage succeeds:

  • Customer API → Customer App: Returns { voucherCode }.
  • Customer App → User: Displays the voucher code.

📝 Note: User sees the exact voucher code that was stored in the database.

Simple Flow

❌ Failure Handling

A. Failure to Store Voucher Code

If saving the voucher code fails:

  • Customer API → KamioKash API: Sends DELETE /order to roll back.
  • KamioKash API → Customer API: Confirms deletion.
  • Customer API → Customer App: Returns an error.
  • Customer App → User: Shows error message.

🧪 Test Case: Simulate DB failure and verify rollback on KamioKash.

B. KamioKash Fails or No Voucher Returned

If KamioKash responds with an error or no voucher code:

  • KamioKash API → Customer API: Returns an error or empty result.
  • Customer API → Customer App: Sends an error response.
  • Customer App → User: Shows a failure message.

🧪 Test Case: Assert correct error propagation from KamioKash to the user.

🔍 Testing & Observability

  • ✅ Confirm rollback logic triggers if DB storage fails.
  • ✅ Ensure voucher shown to user matches stored value.
  • ✅ Validate clear error messaging.
  • ✅ Monitor external API success/failure rates.
  • ✅ Retry logic and idempotency considerations.

Error Flow

✅ Summary

This flow ensures:

  • Reliable voucher issuance.
  • Safe rollback on failure.
  • Clear user feedback.
  • Data consistency between systems.

Integrating with KamioKash requires careful attention to both success and error paths to deliver a seamless user experience.

Voucher Codes

Voucher codes on the KamioKash platform allow users to apply discounts or promotions to their transactions.

Uploading/Importing Data

This documentation will guide you through the process of uploading or importing data into the KamioKash system.

On this page

🧩 Components Involved▶️ Sequence of Events1. Order Initiation2. Voucher Request✅ Happy Path: Voucher Code IssuedIf storage succeeds:❌ Failure HandlingA. Failure to Store Voucher CodeB. KamioKash Fails or No Voucher Returned🔍 Testing & Observability✅ Summary