All notable changes to the Papaya Open API will be documented in this file.

[2.227.0] – 2026-03-17

Added

• List Orders by Date Range Endpoint — Added GET /api/v1/orders endpoint for retrieving orders within a specified date range. Supports filtering by status (complete, cancelled), cursor-based pagination (25 orders per status per page), and returns the full order payload including items and payments, matching the GET /api/v1/orders/:id response shape. Maximum date range is 31 days.

Changed

None

Fixed

None

Removed

None

[2.206.0] – 2026-02-06

Added

• Historical Order Import Endpoint

  • Added POST /orders/import endpoint for importing historical orders from external POS systems (e.g., Revel, Square).

  • Accepts caller-provided orderDate, paidAt, number, and receiptNumber to preserve original order data.

  • Orders are created directly as complete with timestamps reflecting the original order date, skipping real-time validations and side effects (printing, webhooks, inventory checks).

  • Requires externalOrderSource to identify the originating POS system.

  • Supports idempotency keys for safe retries during bulk migration.

Changed

None

Fixed

None

Removed

None

[2.196.0] – 2026-01-19

Added

• Discount Support for Create Order

  • Added appliedDiscounts field to create order endpoint for order-level fixed discounts.

  • Supports optional custom discount name (defaults to "Open Discount").

  • Validates discount total does not exceed bill total before creating order.

Changed

None

Fixed

None

Removed

None

[2.189.0] – 2026-01-05

Added

• Inventory Management Use Case

  • Added new Inventory Management use case to send webhooks for menu updates and all complete or cancelled orders.

  • Uses thin event payload (orderId, event, updatedAt) for partners to fetch full details via /orders/:id.

Changed

None

Fixed

None

Removed

None

[2.177.0] – 2025-12-02

Added

• Rate Limiting

  • Implemented global rate limiting for all OpenAPI endpoints (5 requests per second per API key)

  • Added HTTP 429 response with retryAfter field when rate limit is exceeded

  • Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) included in all responses

  • Rate limiting is scoped per API key to prevent abuse while allowing reasonable burst traffic

Changed

None

Fixed

None

Removed

None

[2.160.0] – 2025-10-22

Added

• Order Data Use Case

  • Added new Order Data use case to send webhooks for all complete or cancelled orders (POS, API, partner-created).

  • Uses thin event payload (orderId, event, updatedAt) for partners to fetch full details via /orders/:id.

Changed

None

Fixed

None

Removed

None

[2.124.1] – 2025-07-17

Added

• Idempotent Request Support

  • All POST endpoints now support idempotency via the idempotency-key header

  • Prevents duplicate operations by caching request hashes for 24 hours

  • Safe retries return the original response

  • Mismatched payloads with the same key return 409 Conflict

  • Header x-idempotent-replay: true included in replayed responses

Changed

None

Fixed

None

Removed

None

[2.91.0] – 2025-06-13

Added

• Authentication

  • Token-based (Bearer JWT) auth

• Core Endpoints

  • Channel, Menu, Order and Outlet

• Request & Response Formats

  • JSON only, camelCase fields, ISO 8601 timestamps

  • Standard HTTP status codes (200, 201, 400, 401, 404, 500)

• Error Handling

  • Uniform error body: { code, message[, errors] }

• Webhooks

  • Order status callbacks to your configured webhookUrl

Changed

None

Fixed

None

Removed

None