> ## 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.

# POST /Sales

> Submit a POS sale transaction to NowBookIt. Amounts are in cents.

Submit a POS sale transaction to NowBookIt, optionally linking it to an existing booking. All monetary amounts are in cents (e.g. `2500` = \$25.00).

<ParamField header="X-API-KEY" type="string" required>Your API key</ParamField>
<ParamField header="Content-Type" type="string" required>Must be `application/json`</ParamField>

**Required body fields**

| Field                 | Type    | Description                      |
| --------------------- | ------- | -------------------------------- |
| `origin.saleId`       | string  | POS-generated unique sale ID     |
| `source.type`         | string  | e.g. `POS`, `ONLINE`             |
| `type`                | string  | `SALE`, `REFUND`, or `VOID`      |
| `openedZonedDateTime` | string  | UTC datetime the sale was opened |
| `staff.id`            | string  | Staff member ID                  |
| `table.seats`         | integer | Number of seats                  |

**Optional body fields**

| Field                   | Type   | Description                                                |
| ----------------------- | ------ | ---------------------------------------------------------- |
| `origin.originalSaleId` | string | Parent sale ID for refunds                                 |
| `origin.locationId`     | string | POS location ID                                            |
| `origin.locationName`   | string | POS location name                                          |
| `locationId`            | string | NowBookIt integration location ID (required if configured) |
| `closedZonedDateTime`   | string | UTC datetime the sale was closed                           |
| `bookingId`             | string | NowBookIt booking ID to link this sale to                  |
| `table.number`          | string | Table number or label                                      |
| `customer.id`           | string | Customer ID                                                |
| `customer.name`         | string | Customer name                                              |
| `customer.notes`        | string | Customer notes                                             |
| `register.id`           | string | POS register ID                                            |
| `register.name`         | string | POS register name                                          |
| `section.id`            | string | Section ID                                                 |
| `section.name`          | string | Section name                                               |
| `items`                 | array  | Line items — see below                                     |
| `payments`              | array  | Payment records — see below                                |
| `total`                 | Price  | Total amount                                               |
| `subtotal`              | Price  | Subtotal before tax                                        |
| `tax`                   | Price  | Tax amount                                                 |
| `discounts`             | Price  | Discount amount                                            |
| `surcharges`            | Price  | Surcharge amount                                           |

**Price object:** `{ "amount": integer (cents), "currency": "AUD" }`

**Item fields:** `id`, `name`, `category`, `quantity`, `unitPrice` (Price), `unitPriceTax` (Price), `total` (Price), `tax` (Price)

**Payment fields:** `method`, `goodsAndServicesAmount` (Price), `status`

<CodeGroup>
  ```shell curl theme={null}
  curl --location '[BASE_URL]/Sales' \
  --header 'X-API-KEY: your_api_key_here' \
  --header 'Content-Type: application/json' \
  --data '{ "origin": { "saleId": "pos-sale-9981" }, "source": { "type": "POS" }, "type": "SALE", "openedZonedDateTime": "2024-03-20T19:05:00Z", "staff": { "id": "staff-7" }, "table": { "seats": 4, "number": "5" } }'
  ```
</CodeGroup>

**Full Example Request Body**

```json theme={null}
{
  "origin": { "saleId": "pos-sale-9981", "locationId": "loc-1", "locationName": "Main Venue" },
  "source": { "type": "POS" },
  "type": "SALE",
  "openedZonedDateTime": "2024-03-20T19:05:00Z",
  "closedZonedDateTime": "2024-03-20T20:45:00Z",
  "bookingId": "abc-123",
  "staff": { "id": "staff-7" },
  "table": { "seats": 4, "number": "5" },
  "total": { "amount": 18500, "currency": "AUD" },
  "items": [
    {
      "id": "item-1",
      "name": "Wagyu Steak",
      "category": "food",
      "quantity": 2,
      "unitPrice": { "amount": 6500, "currency": "AUD" },
      "unitPriceTax": { "amount": 591, "currency": "AUD" },
      "total": { "amount": 13000, "currency": "AUD" },
      "tax": { "amount": 1182, "currency": "AUD" }
    }
  ],
  "payments": [
    { "method": "EFTPOS", "goodsAndServicesAmount": { "amount": 18500, "currency": "AUD" }, "status": "APPROVED" }
  ]
}
```

| Status | Description                                                                 |
| ------ | --------------------------------------------------------------------------- |
| `200`  | Sale submitted                                                              |
| `400`  | `Sales Record '{saleId}' previously processed.` — duplicate sale            |
| `400`  | `Invalid Location Id {locationId}`                                          |
| `400`  | `No Venue Subscribed to your App.`                                          |
| `401`  | X-API-KEY missing or invalid                                                |
| `409`  | `TransactionId - {saleId} currently being processed.` — retry after \~1 min |


## OpenAPI

````yaml POST /Sales
openapi: 3.0.4
info:
  title: NowBookIt IPOS Partner API
  description: >-
    REST API for integrating your POS or external system with NowBookIt's
    reservation, sales, and gift card platform.
  version: v1
  contact:
    email: platform.integrations@nowbookit.com
servers:
  - url: https://ipos.dev.nowbookit.com
    description: Development
  - url: https://ipos.nowbookit.com
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /Sales:
    post:
      tags:
        - Sales
      summary: Create Sale
      operationId: createSale
      parameters:
        - name: X-API-KEY
          in: header
          description: API Key authentication header
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sales'
      responses:
        '200':
          description: OK
        '404':
          description: Returns 404 Not Found when trying to find Booking from NBI.
        '500':
          description: Internal Server Error
      security:
        - ApiKeyAuth: []
components:
  schemas:
    Sales:
      required:
        - openedZonedDateTime
        - origin
        - source
        - staff
        - table
        - type
      type: object
      properties:
        locationId:
          type: string
          nullable: true
        origin:
          $ref: '#/components/schemas/SaleOrigin'
        source:
          $ref: '#/components/schemas/SaleSource'
        type:
          minLength: 1
          type: string
          description: The Type of Sale. E.g. SALE, REFUND, VOID
        status:
          type: string
          nullable: true
        openedZonedDateTime:
          type: string
          description: The time (in UTC) the sale was opened on the POS.
          format: date-time
        closedZonedDateTime:
          type: string
          format: date-time
          nullable: true
        staff:
          $ref: '#/components/schemas/Staff'
        customer:
          $ref: '#/components/schemas/PosCustomer'
        register:
          $ref: '#/components/schemas/Register'
        section:
          $ref: '#/components/schemas/Section'
        bookingId:
          type: string
          description: The Now Book It Booking Id to associate this sale transaction with.
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
          nullable: true
        payments:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
          nullable: true
        tax:
          $ref: '#/components/schemas/Price'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Price'
          nullable: true
        surcharges:
          type: array
          items:
            $ref: '#/components/schemas/Price'
          nullable: true
        total:
          $ref: '#/components/schemas/Price'
        table:
          $ref: '#/components/schemas/Table'
        subtotal:
          $ref: '#/components/schemas/Price'
      additionalProperties: false
    SaleOrigin:
      required:
        - saleId
      type: object
      properties:
        saleId:
          minLength: 1
          type: string
          description: POS system generated Id of the Sale.
        originalSaleId:
          type: string
          description: POS system generated Id of the Parent Sale record in case of Refund.
          nullable: true
        recordType:
          $ref: '#/components/schemas/SalesRecordType'
        locationId:
          type: string
          nullable: true
        locationName:
          type: string
          nullable: true
      additionalProperties: false
    SaleSource:
      required:
        - type
      type: object
      properties:
        type:
          minLength: 1
          type: string
          description: The source type of the Sale.
        other:
          type: string
          nullable: true
      additionalProperties: false
    Staff:
      required:
        - id
      type: object
      properties:
        id:
          minLength: 1
          type: string
          description: The Id of the staff member.
      additionalProperties: false
    PosCustomer:
      type: object
      properties:
        id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
      additionalProperties: false
    Register:
      type: object
      properties:
        id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
      additionalProperties: false
    Section:
      type: object
      properties:
        id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
      additionalProperties: false
    Item:
      required:
        - id
        - name
        - quantity
        - tax
        - total
        - unitPrice
        - unitPriceTax
      type: object
      properties:
        id:
          minLength: 1
          type: string
          description: A unique item Id in Sale.
        name:
          minLength: 1
          type: string
        category:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        sku:
          type: string
          nullable: true
        barcode:
          type: string
          nullable: true
        modifiers:
          type: array
          items:
            $ref: '#/components/schemas/ItemModifier'
          nullable: true
        unitPrice:
          $ref: '#/components/schemas/Price'
        unitPriceTax:
          $ref: '#/components/schemas/Price'
        quantity:
          type: number
          format: double
        total:
          $ref: '#/components/schemas/Price'
        tax:
          $ref: '#/components/schemas/Price'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Price'
          nullable: true
        surcharges:
          type: array
          items:
            $ref: '#/components/schemas/Price'
          nullable: true
      additionalProperties: false
      description: The Item purchased in this Sale Transaction.
    Payment:
      required:
        - goodsAndServicesAmount
        - method
      type: object
      properties:
        acquirer:
          $ref: '#/components/schemas/PaymentAcquirer'
        method:
          minLength: 1
          type: string
          description: The method of Payment. E.g. EFTPOS, CASH, GIFT_CARD
        goodsAndServicesAmount:
          $ref: '#/components/schemas/Price'
        tipAmount:
          $ref: '#/components/schemas/Price'
        surchargeAmount:
          $ref: '#/components/schemas/Price'
        status:
          type: string
          nullable: true
      additionalProperties: false
    Price:
      type: object
      properties:
        amount:
          type: integer
          description: The amount in cents.
          format: int32
        currency:
          type: string
          description: The currency (currently only AUD is supported).
          nullable: true
        description:
          type: string
          nullable: true
      additionalProperties: false
    Table:
      required:
        - seats
      type: object
      properties:
        seats:
          type: integer
          format: int32
        number:
          type: string
          nullable: true
      additionalProperties: false
    SalesRecordType:
      enum:
        - Incremental
        - Tally
        - Final
      type: string
    ItemModifier:
      required:
        - id
        - name
        - quantity
        - tax
        - total
        - unitPrice
        - unitPriceTax
      type: object
      properties:
        id:
          minLength: 1
          type: string
        name:
          minLength: 1
          type: string
        category:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        sku:
          type: string
          nullable: true
        barcode:
          type: string
          nullable: true
        unitPrice:
          $ref: '#/components/schemas/Price'
        unitPriceTax:
          $ref: '#/components/schemas/Price'
        quantity:
          type: number
          format: double
        total:
          $ref: '#/components/schemas/Price'
        tax:
          $ref: '#/components/schemas/Price'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Price'
          nullable: true
        surcharges:
          type: array
          items:
            $ref: '#/components/schemas/Price'
          nullable: true
      additionalProperties: false
    PaymentAcquirer:
      type: object
      properties:
        name:
          type: string
          nullable: true
        transactionReference:
          type: string
          nullable: true
        terminalId:
          type: string
          nullable: true
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````