# Order API Integration Guide

## 1. Overview

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


### 1.1 Order Webhooks

| **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 |


### 1.2 Order APIs

| **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](/apis/standard/order)

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

## 2. Keeta Order Workflow

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.


### 2.1 Forward Transaction (standard fulfillment flow)

#### 2.1.1 Forward Transaction of delivery

**Forward Transaction Workflow Description**

**Order Creation & Notification**

When an order is successfully placed and paid on Keeta's platform:

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**


div
Forward Transaction


```mermaid
flowchart TD

    A((Start)) --> B[User Places Order]

    B --> C[Push New Order]

    C --> D{Push Success?}

    

    D -->|No| E[Repush]

    E --> |No response within 5 minutes|F[Timeout Cancell]

    F --> K((End))

    

    D -->|Yes| G[Merchant Confirms Order]

    G --> H[Food Ready]

    H --> I[Rider Arrives at Store]

    I --> J[Rider Picks Up Food]

    J --> L[User Receives Food]

    L --> K
```

#### 2.1.2 Pickup Order 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](/apis/standard/docs/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


div
Customer Pickup Workflow


```mermaid
flowchart TD

    A((Start)) --> B[User Places Order]

    B --> C[Push New Order]

    C --> D{Push Success?}

    

    D -->|No| E[Repush]

    E --> |No response within 5 minutes|F[Timeout Cancel]

    F --> I((End))

    

    D -->|Yes| G[Merchant Confirms Order]

    G --> H[Food Ready]

    H --> J[Merchant Confirms User Pickup]

    J --> I

    

    %% Retry logic

    E -.Retry 3 times.-> D

    

    %% API identifiers

    M[Push API]

    N[Request API]

    

    %% Style definitions

    classDef white fill:#ffffff,stroke:#333,stroke-width:1px

    classDef orange fill:#ffd8a8,stroke:#333,stroke-width:1px

    classDef blue fill:#b3d9ff,stroke:#333,stroke-width:1px

    

    %% Apply styles

    class A,B,D,E,I white

    class C,F,M orange

    class G,H,J,N blue
```

### 2.2 Reverse Transaction Workflow

Keeta allows order cancellation by **users, customer service, merchants, and the platform**. Below demonstrates merchant and user cancellation scenarios:

#### 2.2.1 Merchant-Initiated Order Cancellation (Full Refund)

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)

#### 2.2.2 Merchant-Initiated Partial Refund

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.

div
Merchant-Initiated Partial Refund Workflow


```mermaid
flowchart TD

    A((Start)) --> B[User Payment]

    B --> C{Merchant Accepts Order?}

    C -->|Yes| D[Merchant Prepares Food]

    D -->|Item Out of Stock| E[Merchant Initiates Partial Refund]

    E --> F[Partial Food Ready]

    F --> G[Rider Arrives at Store]

    G --> H[Rider Picks Up Food]

    H --> I[User Receives Food]

    I --> J((End))

    

    %% API identifiers

    K[Push API]

    L[Request API]

    

    %% Style definitions

    classDef white fill:#ffffff,stroke:#333,stroke-width:1px

    classDef orange fill:#ffd8a8,stroke:#333,stroke-width:1px

    classDef blue fill:#b3d9ff,stroke:#333,stroke-width:1px

    

    %% Apply styles

    class A,B,C,D,J white

    class E,F,L blue

    class G,H,I,K orange
```

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


#### 2.2.3 User Refund (Full Refund)

**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

div
**ℹ️ Common Refund Scenarios**

div
**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.


div
User-initiated Refund Workflow


```mermaid
flowchart TD

    A((Start)) --> B[User Cancellation]

    B --> C{Has Merchant Accepted Order?}

    

    C -->|No| I[Cancel Order]

    C -->|Yes| D[Push a Refund Request Message]

    

    D --> E[No response within 15 minutes]

    D --> F{Does Merchant Agree?}

    

    E --> I

    F -->|Yes| I

    F -->|No| G[Merchant Rejection Synced to user app]

    

    G --> H[No more appeals from user]

    G --> J[Customer Requests Customer Service Intervention]

    

    J --> K[Platform Makes Decision]

    

    I --> L((End))

    H --> L

    K --> L

    

    %% API identifiers

    M[Push API]

    N[Request API]

    

    %% Style definitions

    classDef white fill:#ffffff,stroke:#333,stroke-width:1px

    classDef orange fill:#ffd8a8,stroke:#333,stroke-width:1px

    classDef blue fill:#b3d9ff,stroke:#333,stroke-width:1px

    

    %% Apply styles

    class A,B,C,G,H,L,K,J,E white

    class D,I,M orange

    class F,N blue
```

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


#### 2.2.4 User-Initiated Partial Refund

**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


div
User-Initiated Partial Refund Workflow


```mermaid
flowchart TD

    A((Start)) --> B[User Cancellation]

    B --> C{Has Merchant Accepted Order?}

    

    C -->|No| I[Cancel Order]

    C -->|Yes| D[Push a Partial Refund Request Message]

    

    D --> E[No response within 15 minutes]

    D --> F{Does Merchant Agree?}

    

    E --> I

    F -->|Yes| I

    F -->|No| G[Merchant Rejection Synced to user app]

    

    G --> H[No more appeals from user]

    G --> J[Customer Requests Customer Service Intervention]

    

    J --> K[Platform Makes Decision]

    

    I --> L((End))

    H --> L

    K --> L

    

    %% API identifiers

    M[Push API]

    N[Request API]

    

    %% Style definitions

    classDef white fill:#ffffff,stroke:#333,stroke-width:1px

    classDef orange fill:#ffd8a8,stroke:#333,stroke-width:1px

    classDef blue fill:#b3d9ff,stroke:#333,stroke-width:1px

    

    %% Apply styles

    class A,B,C,G,H,L,K,J,E white

    class D,I,M orange

    class F,N blue
```

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.


#### 2.2.5 Keeta or Customer Service Initiated Order Cancellation

For cancellations initiated by **Keeta platform or customer service**:

- Developers need **no additional processing**
- Please just synchronize cancellation notifications to their systems