Guide

Changelog

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

[2.324.0] – 2026-07-15

Added

  • Inventory Good Receipts Endpoint

    • Added GET /api/v1/inventory/goods-receipts — lists the outlet's goods receipts (purchase records) within a date range, oldest first, cursor-paginated. Requires RFC 3339 from/to bounds (maximum range 31 days) filtering on created, and supports a comma-separated status filter (draft, completed, cancelled, partiallyReceived; defaults to completed) and an optional supplierId. Each receipt includes header amounts (totalPrice, tax, shippingFee, total, isTaxInclusive), the supplier snapshot, and full line items with quantity, purchase unit, unit cost, line total, and the tax rate snapshot applied at receipt time. Use deliveryDate as the supplier bill date in accounting systems, and treat the line totalPrice as authoritative. Pages return up to 25 receipts; a page may return fewer but still carry a next cursor — always follow the cursor until it is null.

    • Authenticate with the same outlet API key used for the /orders endpoints (merchant/outlet scope comes from the key); MCP access tokens are also accepted.

Changed

None

Fixed

None

Removed

None

[2.315.0] – 2026-07-01

Added

  • Order Action Log Endpoints

    • Added GET /api/v1/orders/{id}/action-log — returns the full action log for a single order, newest first. Each entry has a structured action type, a projected actor (type, id, name, role), action-specific metadata, and created. Mirrors the access rules of GET /api/v1/orders/{id}: returns 404 for missing or partner-aggregated orders.

    • Added GET /api/v1/orders/action-logs — lists the outlet's action log entries within a date range, newest first, cursor-paginated. Requires RFC 3339 from/to bounds (maximum range 31 days) and supports filtering by action, actorId, actorType, channelId, and free-text search. A page may return fewer entries than requested but still carry a next cursor — always follow the cursor until it is null.

Changed

None

Fixed

None

Removed

None

[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

Previous
Webhooks

© 2025 Papaya