Developers can receive and manage orders from Keeta after Order API integration. The API comprises two categories:
- Webhook: For receiving order notifications from Keeta
- Order API: For updating order statuses
| eventId | Event Description |
|---|---|
| 1001 | Order Placement Notification |
| 1002 | Order Acceptance Notification |
| 1003 | Order Completion Notification |
| 1004 | Order Cancellation Notification |
| 1005 | Refund Initiation Notification |
| 1006 | Delivery Status Update Notification |
| 1007 | Partial Refund Initiation Notification |
| Endpoint | Functionality |
|---|---|
| /api/open/order/confirm | Check order acceptance status (Verifies if the order has been accepted by the merchant) |
| /api/open/order/get | Retrieve order details (Obtains extended order information) |
| /api/open/order/prepare | Confirm meal readiness (Merchant marks order as prepared. Critical: Failure to accept orders impacts store EAT metrics) |
| /api/open/order/cancel | Cancel order (The endpoint allows a merchant to terminate the entire transaction chain. Please be cautious when calling this endpoint to prevent unintended financial losses.) |
| /api/open/order/agree | Merchant approval of user-initiated refund (Confirms acceptance of customer's refund request) |
| /api/open/order/reject | Merchant rejection of user-initiated refund (Rejects customer's refund request) |
| /api/open/order/collect | Merchant confirmation of customer pickup (Exclusively for pickup orders; marks order as received by customer) |
| /api/open/order/refund/part/products/preview | Merchant preview of partially refundable items (Queries product eligibility and amounts for partial refunds) |
| /api/open/order/refund/part/apply | Merchant-initiated partial refund processing (Executes refund for specific items in an order) |
For more details, please refer to Order API Reference
Core API Capabilities:
- Receive Keeta order notifications:
- New order alerts
- Order completion confirmations
- Order cancellation notices
- User-initiated refund requests
- Update order statuses:
- Order acceptance
- Meal preparation completion
- Customer pickup confirmation
- Order cancellation
Orders are categorized into forward transactions (standard fulfillment flow) and reverse transactions (refund/cancellation flow). Please refer to the workflow diagram for detailed sequence logic.
Keeta's order processing comprises two workflows:
- Forward Transaction: The complete process from order placement to fulfillment, without refunds or cancellations.
- Reverse Transaction: The inverse process handling refunds and cancellations.
Forward Transaction Workflow Description
Order Creation & Notification
When an order is successfully placed and paid on Keeta's platform:
- The system instantly generates the order
- Pushes a New Order Notification (Webhook Event 1001) to developers, it includes order details, merchant settlement information
Merchant Decision-Making
Upon receiving the new order notification, merchants evaluate:
- Inventory status: Confirm sufficient ingredients/products
- Operating status: Verify current business hours and order acceptance capacity
- Order load: Assess real-time processing capability
Based on evaluation results, merchants may:
- Accept order: Via /api/open/order/confirm
- Reject order: Via /api/open/order/cancel
Parallel Processing Post-Acceptance
After order acceptance, two parallel workflows initiate:
Merchant Workflow:
- Begins meal preparation
Platform Workflow:
- Keeta automatically dispatches riders
- Matching criteria: order location, delivery distance
Meal Readiness Reporting & Rider Dispatch
When meal preparation completes:
- Developer calls /api/open/order/prepare
- System notifies rider for store pickup
Real-Time Delivery Status Updates
Keeta pushes Delivery Status Updates (Webhook Event 1006) during transit:
- Rider order acceptance
- Rider arrival at store
- Rider meal retrieval
- Order delivery completion
Order Completion
After the rider successfully delivers the meal to the customer:
- The order status is updated to Completed
Forward Transaction
Pickup Order is an alternative fulfillment mode offered by Keeta, allowing customers to collect meals directly at stores without delivery service. The workflow resembles standard orders but excludes rider delivery. The order completes upon Customer Pickup.
Pickup Workflow Description
Pickup Order Creation & Notification
Identical to standard Order Placement:
- Triggers New Order Push (Webhook 1001) upon payment
- If the webhook message is not processed correctly, Keeta will perform a push retry. The system will retry up to three times with one-minute intervals. For details, see Webhook
Merchant Decision-Making
Same process as standard orders, it requires evaluation based on inventory/operating status
- Merchant Acceptance via /api/open/order/confirm
- Order rejection via /api/open/order/cancel
Post-Acceptance Processing
Single merchant-focused workflow:
- Merchant begins meal preparation
- Platform skips rider dispatch
Meal Readiness Confirmation
When Meal Preparation Complete:
- Call /api/open/order/prepare
- System notifies customer for collection
Customer Pickup
Upon customer arrival:
- Optional: Call /api/open/order/collect to confirm Customer Pickup
- System auto-completes order after preset timeout if not called
Order Completion
After successful Customer Pickup:
- Order status updates to Completed
- Triggers Webhook 1003
Customer Pickup Workflow
Keeta allows order cancellation by users, customer service, merchants, and the platform. Below demonstrates merchant and user cancellation scenarios:
Keeta allows merchants to cancel orders at any stage. Since order cancellation is a high-impact operation, developers should implement additional exception handling and verification mechanisms to ensure system stability and prevent accidental cancellations.
Key endpoint for developers: /api/open/order/cancel (Merchant-initiated order cancellation)
During meal preparation, merchants may encounter missing items or spillage issues. To protect both user and merchant interests, merchants can initiate partial refunds for affected items. This ensures user compensation while preserving the main transaction.
Merchant-Initiated Partial Refund Workflow
The partial refund workflow involves three sequential steps:
Query Refundable Items Call /api/open/order/refund/part/products/preview to retrieve refund-eligible products
Select Products Merchant chooses specific products for refund from the query results
Execute Refund Call /api/open/order/refund/part/apply to complete the partial refund operation
Pre-Merchant Acceptance
- Users may cancel orders directly without merchant approval
Post-Merchant Acceptance
- Order cancellation requires merchant approval
Refund Eligibility Windows
Users may request refunds at multiple stages, including after order placement, during delivery, after receiving meals
ℹ️ Common Refund Scenarios
Subjective Reasons
- User changes mind (no longer wants order)
- Excessive wait time prompts alternative dining
- Incorrect restaurant/dish selection
Product Quality Issues
- Spoiled/contaminated food upon delivery
- Undercooked or improperly prepared meals
- Damaged packaging or spillage
Order Accuracy Issues
- Received items differ from order (missing items/incorrect dishes)
- Incorrect specifications (e.g., spice level)
Delivery Problems
- Late delivery affecting meal plans
- Wrong delivery address or unreachable rider
Resolution Path: Merchants/platforms handle refunds based on actual circumstances.
User-initiated Refund Workflow
Merchant Refund Handling Process
Upon receiving a User-initiated Refund request via Webhook Event 1005, merchants process it based on actual circumstances by either approving or rejecting. If the user disputes the merchant's decision, customer service handles secondary resolution.
Common Processing Scenarios:
- Merchant approves refund request: Call /api/open/order/agree
- Merchant rejects refund request: Call /api/open/order/reject
- Customer service approves refund: Result delivered via Webhook Event 1005
- Customer service rejects refund: Result delivered via Webhook Event 1005
Different refund reasons and handling methods yield varied outcomes, requiring system flexibility to manage diverse refund scenarios.
Partial Refund: Keeta allows users to request refunds for specific items within an order, providing more flexible resolution options.
In real business context, when only full refunds are available for partially problematic orders:
Impact on Merchants:
- Non-issue items get refunded unnecessarily
- Damages merchant profitability and platform partnership willingness
Impact on Users:
- Refund process obstructed by merchant objections
- Extended resolution cycles degrade user experience
Value of Partial Refunds
Partial refund balances user needs with merchant protection by:
- Resolving specific issues promptly
- Preventing excessive merchant losses
- Ensuring smoother refund processing
User-Initiated Partial Refund Workflow
Upon receiving a User-initiated Partial Refund request via Webhook Event 1007, merchants process it by approving or rejecting based on actual circumstances. If the user disputes the decision, customer service handles secondary resolution.
Processing Scenarios:
- Merchant approves partial refund: Call /api/open/order/agree
- Merchant rejects partial refund: Call /api/open/order/reject
- Customer service approves: Result delivered via Webhook Event 1007
- Customer service rejects: Result delivered via Webhook Event 1007
Different refund reasons and handling methods yield varied outcomes, requiring system flexibility to manage diverse refund scenarios.
For cancellations initiated by Keeta platform or customer service:
- Developers need no additional processing
- Please just synchronize cancellation notifications to their systems