Order API Integration Guide

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

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 on Keeta's platform, regardless of the payment method (online payment or cash on delivery):

1. The system instantly generates the order
2. 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:

1. Merchant Workflow:

   • Begins meal preparation

2. Platform Workflow:

   • Keeta automatically dispatches riders
   • Matching criteria: order location, delivery distance

Meal Readiness Reporting & Rider Dispatch

When meal preparation completes:

1. Developer calls /api/open/order/prepare
2. 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

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:

1. Merchant begins meal preparation
2. 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

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.

The partial refund workflow involves three sequential steps:

1. Query Refundable Items Call /api/open/order/refund/part/products/preview to retrieve refund-eligible products

2. Select Products Merchant chooses specific products for refund from the query results

3. 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

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:

1. Resolving specific issues promptly
2. Preventing excessive merchant losses
3. Ensuring smoother refund processing

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