> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.nowbookit.com/llms.txt > Use this file to discover all available pages before exploring further. # List Sales > Retrieve a venue's sales within a date range. Retrieves your venue's sales within a date range, oldest first. Results are always scoped to the venue tied to your API key — there's no way to list sales for another venue. > [!NOTE] > > Large ranges are paginated. When a response includes a `nextCursor`, pass it back as the `cursor` parameter to fetch the next page; `nextCursor` is `null` once you've reached the end. > [!NOTE] > > `reconciliationStatus` reflects whether the sale was matched to a booking: `Matched` (found, and enriched with service/table/diner details), `Unmatched` (a match was attempted but nothing found), or `PendingMatch` (matching couldn't be completed and may resolve later). > [!NOTE] > > `recordType` is `Final` (closed/settled), `Incremental` (accumulates onto the stored record on resend), or `Tally` (a running snapshot of a still-open sale — resends are diffed against the stored record and only changed fields are applied). See [Ingest Sale](/platform/sales/ingest-sale) for details on resend behavior per type. ### Example ```shell curl theme={null} curl --location 'https://platform.uat.nowbookit.com/api/sales/transactions?startDate=2026-07-23T00:00:00Z&endDate=2026-07-24T00:00:00Z&limit=50' \ --header 'Authorization: Bearer your_api_key_here' ``` ```json Response — 200 OK theme={null} { "sales": [ { "saleId": "01J...ULID", "partnerSaleId": "pos-sale-9981", "transactionType": "Sale", "recordType": "Final", "reconciliationStatus": "Matched", "bookingId": "abc-123", "openedAt": "2026-07-23T19:05:00.000Z", "closedAt": "2026-07-23T20:45:00.000Z", "tables": [{ "name": "12", "seats": 4 }], "staffId": "staff-7", "items": [ { "id": "item-1", "name": "Wagyu Steak", "quantity": 2, "unitPrice": 6500, "total": 13000 } ], "payments": [{ "id": "pay-1", "type": "EFTPOS", "amount": 18500 }], "total": 18500, "currency": "AUD" } ], "nextCursor": null } ``` ## OpenAPI ````yaml platform/sales/openapi.json GET /api/sales/transactions openapi: 3.0.4 info: title: NowBookIt Sales API description: >- REST API for submitting POS sale transactions to NowBookIt and retrieving a venue's sales history. version: v1 contact: email: platform.integrations@nowbookit.com servers: - url: https://platform.uat.nowbookit.com description: UAT - url: https://platform.nowbookit.com description: Production security: - ApiKeyAuth: [] tags: - name: Sales description: POS sale ingest and venue sales listing. paths: /api/sales/transactions: get: tags: - Sales summary: List a venue's sales description: >- Lists the calling partner's venue's sales within a date range, ascending by `saleId` (a time-ordered ULID). Scope is always the authenticated key's own `orgId`/`venueId` — there is no cross-venue or cross-org listing. operationId: listSales parameters: - name: startDate in: query required: true schema: type: string format: date-time description: Any UTC offset accepted; normalised to UTC. - name: endDate in: query required: true schema: type: string format: date-time description: Must not be before `startDate`. - name: cursor in: query required: false schema: type: string description: Opaque pagination cursor from a previous response's `nextCursor`. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 200 default: 50 description: How many sales to return at once (1–200). Defaults to 50. responses: '200': description: Sales within the requested range. content: application/json: schema: $ref: '#/components/schemas/SalesQueryResponse' '400': description: >- Query parameter validation failure (root-level issues keyed `query`, not `body`). content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' example: code: ValidationError message: Query parameters failed validation requestId: c47a9e21-8b3d-4f6a-9e12-example errors: query: - endDate must not be before startDate '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: UnauthorisedError message: Invalid API key requestId: 8f14e45f-ceea-4c6f-8f89-example '502': description: >- The iPOS API-key resolve endpoint was unavailable or returned an unexpected response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: AppError message: iPOS API-key resolve endpoint returned an unexpected response requestId: 6e2a9c4f-1d3b-4a7e-9c5f-example components: schemas: SalesQueryResponse: type: object properties: sales: type: array description: The list of sales matching your request. items: $ref: '#/components/schemas/Sale' nextCursor: type: string nullable: true description: Opaque pagination cursor. `null` when there are no more results. required: - sales - nextCursor ValidationErrorResponse: allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object properties: errors: type: object description: >- Per-field validation messages, keyed by dotted path (`body` or `query` for root-level cross-field issues). additionalProperties: type: array items: type: string example: total: - Sum of payments amounts (1800) must equal total (1850) closedAt: - closedAt is required when recordType is Final required: - errors ErrorResponse: type: object properties: code: type: string description: >- Error class name, e.g. `UnauthorisedError`, `ValidationError`, `AppError`. example: UnauthorisedError message: type: string description: What went wrong, described in plain language. example: Invalid API key requestId: type: string description: >- A unique reference number for this request — handy if you need to contact support about it. example: 8f14e45f-ceea-4c6f-8f89-example required: - code - message - requestId Sale: type: object description: A stored sale record, as returned by the venue sales listing. properties: venueId: type: string description: ID of the venue the sale belongs to. orgId: type: string description: ID of the organisation the venue belongs to. saleId: type: string description: >- NBI-generated ULID, seeded from `closedAt` (or now, for open Incremental records). partnerSaleId: type: string description: The sale ID you submitted when the sale was sent in. partnerId: type: string description: ID identifying you as the partner who submitted the sale. partnerName: type: string description: Your business name, as known to NowBookIt. source: type: string description: >- Collapsed from the request's `{ type, other }` into `": "` (or just ``). transactionType: type: string description: Whether this is a sale, a refund, or a void. enum: - Sale - Refund - Void recordType: type: string description: >- Whether this is a closed sale (Final), a running snapshot of an open sale (Tally), or a record that adds onto an existing sale (Incremental). enum: - Final - Tally - Incremental posStatus: type: string description: The raw status from your POS system, passed through as-is. posLocationId: type: string description: The venue or location ID as known to your POS system. posLocationName: type: string description: The venue or location name as known to your POS system. reconciliationStatus: type: string description: Whether the sale has been matched to a booking. enum: - Unmatched - PendingMatch - Matched bookingId: type: string description: '`unknown` until reconciliation matches a booking.' originalSaleId: type: string description: The sale ID this record is a refund of, if applicable. originalSaleResolved: type: boolean description: >- Set only for Refunds — whether `originalSaleId` was found via the partner index at ingest. venueName: type: string description: Name of the venue the sale belongs to. timeZoneId: type: string description: IANA timezone, e.g. `Australia/Sydney`. serviceId: type: string description: Enriched from the matched NBI booking on reconciliation. serviceName: type: string description: Name of the service or seating period, e.g. Dinner Service. tables: type: array description: The tables the sale was linked to. items: $ref: '#/components/schemas/SaleTable' covers: type: number description: Number of guests at the table. openedAt: type: string description: When the sale started, e.g. when the table was opened. format: date-time closedAt: type: string description: When the sale was closed out. format: date-time register: type: object description: Details of the till or register the sale was rung up on. additionalProperties: true staffId: type: string description: ID of the staff member who processed the sale. staffName: type: string description: Name of the staff member who processed the sale. dinerId: type: string description: '`unknown` until a diner is resolved/matched.' diner: type: object description: Details about the diner the sale is linked to, if known. additionalProperties: true dinerResolved: type: boolean description: Whether the diner's details have been matched and filled in. items: type: array description: The food, drinks, and other items included in the sale. items: $ref: '#/components/schemas/SaleItem' payments: type: array description: The payments made toward the sale. items: $ref: '#/components/schemas/SalePayment' total: type: integer description: Amount in whole cents (no decimals). subtotal: type: integer description: Amount in whole cents (no decimals). tax: type: integer description: Amount in whole cents (no decimals). discount: type: integer description: Amount in whole cents (no decimals). surcharges: type: integer description: Amount in whole cents (no decimals). tip: type: integer description: Amount in whole cents (no decimals). currency: type: string description: Three-letter currency code, e.g. AUD or USD. createdAt: type: string description: When this sale record was first stored. format: date-time updatedAt: type: string description: When this sale record was last updated. format: date-time required: - venueId - orgId - saleId - partnerSaleId - partnerId - source - transactionType - recordType - reconciliationStatus - bookingId - openedAt - dinerId - dinerResolved - total - currency - createdAt - updatedAt SaleTable: type: object properties: name: type: string description: Table name or number. seats: type: number description: Number of seats at the table. sectionId: type: string description: >- Populated only once reconciliation resolves this table against the NBI booking's floor plan. sectionName: type: string description: >- Name of the section or area the table belongs to, e.g. Patio or Main Dining Room. required: - name SaleItem: type: object properties: id: type: string description: Your own ID for this item. sku: type: string description: The item's SKU or product code, if it has one. name: type: string description: Name of the item, as it appeared on the receipt. category: type: string description: Category the item belongs to, e.g. food, drinks, or merchandise. barcode: type: string description: Barcode for the item, if it was scanned. quantity: type: number description: How many of this item were ordered. unitPrice: type: integer description: Amount in whole cents (no decimals). unitTax: type: integer description: Amount in whole cents (no decimals). discount: type: integer description: Amount in whole cents (no decimals). total: type: integer description: Amount in whole cents (no decimals). required: - id - name - quantity - unitPrice - total SalePayment: type: object properties: id: type: string description: Your own ID for this payment. type: type: string description: How the guest paid, e.g. cash, EFTPOS, or credit card. enum: - CASH - EFTPOS - CREDIT_CARD - GIFT_CARD - VOUCHER - ACCOUNT - DEPOSIT - BANK_TRANSFER - THIRD_PARTY - COMPLIMENTARY - OTHER status: type: string description: Status of the payment, e.g. approved or declined. amount: type: integer description: Amount in whole cents (no decimals). tip: type: integer description: Amount in whole cents (no decimals). surcharge: type: integer description: Amount in whole cents (no decimals). terminalId: type: string description: ID of the card machine or payment terminal used, if any. transactionReference: type: string description: Reference number for the payment transaction, if available. required: - id - type - amount securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- Your API key. See [Authorization](/platform/authorization) to create one. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.