GET sales

Endpoint

GET /public-api/v1/sales

Purpose

Returns sale summaries for the key organization, scoped by date range and optional filters.

Authentication

Required.

Parameters

• limit: optional page size, default 25, maximum 100.
• cursor: optional UUID from pagination.nextCursor.
• storeIds: optional branch filter.
• from: optional ISO timestamp.
• to: optional ISO timestamp.
• status: optional comma-separated or repeated values: PENDING, PAID, CANCELLED, REVERTED, REFUNDED.
• paymentMethods: optional comma-separated or repeated values: CASH, CARD, VISA, MASTERCARD, TRANSFER, PROMPT_PAY, ALIPAY, WECHAT_PAY, CRYPTO.
• staffId: optional staff UUID. Returns sales assigned to that staff member (the cashier recorded on the sale).
• tabCreatorId: optional staff UUID. Returns sales whose tab was opened by that staff member.
• search: optional invoice ID search. Numeric values match invoiceId.

Response fields

Each sale includes id, timestamps, invoiceId, status, type, subTotal, total, discountType, discountValue, pointsUsed, rounding, store, staff, tabCreator, payments, and compact lineItems.

staff is the staff member assigned to the sale (the recorded cashier). tabCreator is the staff member who originally opened the tab, or null when the sale did not originate from a tab. Both objects contain only id and name.

Each payment includes paymentMethod, amount, sequence, and createdAt.

Each line item includes id, productId, productName, productUnit, quantity, and actualQuantity. quantity is the quantity sold. actualQuantity reflects the inventory quantity applied by the sale, which can differ for products with unit conversion.

Example request

curl "https://api.klupos.com/public-api/v1/sales?limit=10&status=PAID&from=2026-06-01T00:00:00.000Z&to=2026-06-24T23:59:59.999Z" \
  -H "Authorization: Bearer klu_live_replace_me"

Example response

{
  "data": [
    {
      "id": "sale-id",
      "createdAt": "2026-06-24T10:00:00.000Z",
      "updatedAt": "2026-06-24T10:01:00.000Z",
      "invoiceId": 1024,
      "status": "PAID",
      "type": "RETAIL",
      "subTotal": 900,
      "total": 900,
      "discountType": null,
      "discountValue": 0,
      "pointsUsed": 0,
      "rounding": 0,
      "store": { "id": "store-id", "name": "Main Branch", "branchNo": "001" },
      "staff": { "id": "staff-id", "name": "Nok" },
      "tabCreator": { "id": "tab-creator-id", "name": "Mali" },
      "payments": [
        {
          "paymentMethod": "CASH",
          "amount": 900,
          "sequence": 1,
          "createdAt": "2026-06-24T10:01:00.000Z"
        }
      ],
      "lineItems": [
        {
          "id": "sale-product-id",
          "productId": "product-id",
          "productName": "House Blend",
          "productUnit": "PIECE",
          "quantity": 2,
          "actualQuantity": 2
        }
      ]
    }
  ],
  "meta": {
    "dateRange": {
      "from": "2026-06-01T00:00:00.000Z",
      "to": "2026-06-24T23:59:59.999Z"
    }
  }
}

Common errors

• 400: invalid status, payment method, date range, limit, cursor, staff ID, tab creator ID, or UUID.
• 401: invalid key.
• 403: requested storeIds are outside the organization.
• 429: rate limit exceeded.

AI-agent notes

Use analytics endpoints for totals. Use this endpoint for product-level sales velocity and drill-down into individual sale summaries. Follow nextCursor until it is null when building a complete export.