Use Cases

Papaya’s API will continue to evolve with innovative capabilities that unlock new possibilities for partners and merchants. The initial focus is on digital ordering, reservation and booking integrations, and access to order data for analytics and reporting.

Setup

The API is scoped to a Papaya outlet, which represents an individual restaurant, shop, or branch at a specific physical location. In Papaya’s structure, an outlet sits under a merchant — the top-level entity that groups together multiple outlets.

To begin using the API, you must first Enable Open API for a specific outlet via the merchant dashboard: https://merchant.papaya.co.th/settings/openapi

Once enabled, you can generate one or more API keys, each linked to a specific use case along with a corresponding webhook URL.

Access tokens are shown only once. Please copy and store them securely. If forgotten, you’ll need to delete and recreate the API key for that use case.

Digital Ordering

Integrate food-delivery aggregators or other online ordering platforms with Papaya’s POS.

Flow

Credential & Channel Setup
1. In the Papaya merchant dashboard, create an API key with the use case set to “Digital Ordering”, and securely store the generated Bearer token for authentication.
2. Under Channels in the merchant dashboard, register your ordering platform as a channel of type “Partner” (e.g. Grab, LINEMAN). This allows it to be retrieved via the GET /api/v1/channels endpoint.
Sync Menu
1. Fetch the current menu for that channelType:
```
GET /api/v1/menus?channelType={channelType}
```
2. Noting that for channelType = partner, you should also include the partnerChannel query parameter with the appropriate string value (e.g. grab) to ensure partner-specific menu overrides are applied.

Create Order

When the ordering platform receives a new order, forward it into Papaya:

POST /api/v1/orders

{
  "channelId": "{channel.id}",
  "partnerInfo": {
    "partnerChannel": "grab",
    "orderId": "GF-123"
  },
  "items": [
    {
      "customerName": "Pim",
      "menuItemId": "{menuItem.id}",
      "quantity": 2,
      "options": [
        {
          "optionId": "{option.id}",
          "quantity": 1
        }
      ]
    }
  ],
  "payments": [
    {
      "offlineMethod": "card",
      "amount": 100,
      "customerName": "Pim",
      "externalId": "stripe-123",
      "currency": "THB",
      "created": "2025-06-22T08:55:26.169Z"
    }
  ],
}

Track & Fulfill
1. Receive live updates via your configured webhook (recommended)
2. or, poll the order using GET /api/v1/orders/:id
To Cancel an Order

Use the update order endpoint to change the order status to cancelled when an order is no longer proceeding.
```
PUT /api/v1/orders/:id

{
  "status":"cancelled"
}
```

Key Endpoints

Endpoint	Method	Description
`/channels`	`GET`	List available channels
`/menus`	`GET`	Retrieve menu for a given channelType
`/orders`	`POST`	Create a new order
`/orders/:id`	`GET`	Fetch order details & status
`/orders/:id`	`PUT`	Cancel an order
Webhook URL	`POST`	Receive order status notifications

Reservations

Connect a restaurant booking system to initiate orders on the POS from reservations and walk-ins, and receive real-time order updates.

Flow

Credential & Channel Setup
1. In the Papaya merchant dashboard, create an API key with the use case set to “Reservations”, and securely store the generated Bearer token for authentication.
2. In the merchant dashboard under Channels, create a channel for each table, ensuring each is set to type “Dine-in”. All channels can then be retrieved via the GET /api/v1/channels endpoint.

Open an Order (Table)

When you mark a customer as arrived on your reservation platform, your system calls:

POST /api/v1/orders/reservations

{
  "channelId": "{channel.id}",
  "guestCount": 4,
  "partnerReservationInfo": {
    "partnerName": "Reservation App Name",
    "reservationId": "res-123",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phoneNumber": "+66922801111"
  },
  "payments": [
    {
      "offlineMethod": "card",
      "amount": 100,
      "currency": "THB",
      "externalId": "stripe-123",
      "created": "2025-06-22T08:55:26.169Z"
    }
  ]
}

This creates an order in Papaya POS linked to the reservation. A payments array is optional and should be included if a deposit has already been paid.

Only channels with type dine-in can be opened using the POST /orders/reservations endpoint.

Listen for Order Updates
1. After initiating an order, your reservation platform will receive order update notifications via the Webhook URL configured when creating the API key in the merchant dashboard.
2. Four events can trigger a reservation order update:
  1. order.totalsUpdated — order totals have changed
  2. order.statusUpdated — order status has changed (e.g. from open to complete)
  3. order.channelUpdated — the order was moved between tables
  4. order.guestCountUpdated — guest count has changed
3. Use the GET /api/v1/orders/:id endpoint to fetch the latest order details and respond as needed based on your platform’s business logic.
  
  Webhook notifications will only be sent for orders initiated from the reservation platform.
Listen for Channel Updates
1. When a merchant updates their channel (table) configuration in the merchant dashboard, those changes are published to reservation partners.
2. You will receive a channels.published notification via the Webhook URL.
3. Upon receiving this event, call GET /api/v1/channels to retrieve the latest channel (table) configuration data.

Key Endpoints

Endpoint	Method	Description
`/channels`	`GET`	List available channels
`/orders/reservations`	`POST`	Open a reservation-linked order in Papaya
`/orders/:id`	`GET`	Fetch latest order details
Webhook URL	`POST`	Receive postbacks for: Reservation order updates Channel / table configuration changes

Order Data

Get complete sales and order data from Papaya’s POS to simplify reporting, reconciliation, and performance tracking.

Flow

Credential Setup
1. In the Papaya merchant dashboard, create an API key with the use case set to “Order Data”, and set a webhook URL for receiving order updates.
2. Securely store the generated Bearer token for authentication.
Listen for Order Completion
1. When orders are placed through Papaya’s POS, regardless of source, you’ll receive real-time updates via your configured webhook URL. These updates are sent as lightweight “thin” events containing only the event name and Order ID.
2. For the Order Data use case, only two event types are sent from the Order status webhook:
  1. order.complete — the order was successfully completed and paid
  2. order.cancelled — the order was cancelled, either before or after payment
  These two events represent the final, permanent state of an order.
```
POST {webhook_url}

{
  "id": "01K7KAT54KQ6544MKY9G5TTEWG",
  "event":"order.complete",
  "updatedAt": "2025-10-10T08:55:26.169Z"
}
```
3. Use the GET /api/v1/orders/:id endpoint to retrieve the latest order details for your integration or reporting needs.
  
  You may receive multiple order updates, as orders can be cancelled after completion or reopened and modified before being completed again. However, merchants should always transition orders back to either a complete or cancelled state.
Historical Data

Fetching historical order data prior to setting up an API key and webhook URL isn’t currently supported by default. However, if this is critical to your needs, please contact our team — we can provide a list of order IDs for the desired period, which you can then use with the GET /orders/:id endpoint to retrieve those orders.

Key Endpoints

Endpoint	Method	Description
`/orders/:id`	`GET`	Fetch latest order details
Webhook URL	`POST`	Receive `order.complete` and `order.cancelled` notifications