openapi: 3.0.3
info:
  title: Palm Open API
  version: "1.0"
  description: |
    Public API for third-party integrations with Palm POS.

servers:
  - url: https://lite-dev.palmnet.co
    description: Production

security:
  - ApiKeyHeader: []

paths:
  /v1/orgs/{orgId}/orders:
    get:
      operationId: listOrgOrders
      summary: List orders
      description: |
        Retrieve orders across all stores in the organization,
        sorted by creation time (newest first). Supports filtering
        and cursor-based pagination.
      tags:
        - Orders
      security:
        - ApiKeyHeader: []
      parameters:
        - name: orgId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Organization ID

        - name: store_id
          in: query
          schema:
            type: string
            format: uuid
          description: Filter by a specific store

        - name: view
          in: query
          schema:
            type: string
            enum: [all, active, history]
            default: all
          description: >
            `all` — no filter;
            `active` — excludes completed/cancelled;
            `history` — only completed/cancelled

        - name: payment_status
          in: query
          schema:
            type: string
          description: Comma-separated payment statuses (e.g. `paid,unpaid`)

        - name: fulfillment_status
          in: query
          schema:
            type: string
          description: Comma-separated fulfillment statuses (e.g. `completed,cancelled`)

        - name: source
          in: query
          schema:
            type: string
          description: Comma-separated order sources (e.g. `pos,kiosk`)

        - name: from
          in: query
          schema:
            type: string
          description: Start date/time (RFC 3339 or `YYYY-MM-DD`)

        - name: to
          in: query
          schema:
            type: string
          description: End date/time (RFC 3339 or `YYYY-MM-DD`; date-only = end of day)

        - name: amount_min
          in: query
          schema:
            type: integer
          description: Minimum totalCents (inclusive)

        - name: amount_max
          in: query
          schema:
            type: integer
          description: Maximum totalCents (inclusive)

        - name: page_size
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 200
          description: >
            Number of orders per page (1–200).
            Capped to 50 when `expand` includes `items`.

        - name: before
          in: query
          schema:
            type: string
            format: date-time
          description: >
            Pagination cursor — pass the `createdAt` of the last order
            from the previous page (RFC 3339 Nano)

        - name: expand
          in: query
          schema:
            type: string
          description: >
            Comma-separated list of sub-resources to inline in each order object.
            Allowed values: `items`, `payments`, `refunds`, `tax_breakdown`.
            When specified, the server batch-loads the requested sub-resources
            for all orders in the current page and includes them in the response.
          example: "items,payments"

      responses:
        "200":
          description: Orders retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required: [orders, hasMore]
                properties:
                  orders:
                    type: array
                    items:
                      $ref: "#/components/schemas/Order"
                  hasMore:
                    type: boolean
                    description: Whether more orders exist beyond this page
              example:
                orders:
                  - id: "550e8400-e29b-41d4-a716-446655440000"
                    storeId: "660e8400-e29b-41d4-a716-446655440001"
                    orderVersion: 3
                    serviceType: dine_in
                    paymentStatus: paid
                    fulfillmentStatus: completed
                    subtotalCents: 2500
                    discountCents: 0
                    manualDiscountCents: 0
                    taxCents: 250
                    totalCents: 2750
                    note: ""
                    source: pos
                    tzOffsetMinutes: 60
                    createdAt: "2024-06-15T14:30:00Z"
                hasMore: false
        "400":
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Insufficient scope or org mismatch
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v1/orgs/{orgId}/orders/{orderId}:
    get:
      operationId: getOrgOrder
      summary: Get order details
      description: |
        Retrieve full details of a single order including line items,
        refunds, and tax breakdown.
      tags:
        - Orders
      security:
        - ApiKeyHeader: []
      parameters:
        - name: orgId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Organization ID

        - name: orderId
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Order ID

      responses:
        "200":
          description: Order retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required: [order]
                properties:
                  order:
                    $ref: "#/components/schemas/OrderDetail"
        "401":
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Insufficient scope or org mismatch
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Order not found or does not belong to the organization
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key passed in the `X-Api-Key` header

  schemas:
    Order:
      type: object
      required:
        - id
        - storeId
        - orderVersion
        - serviceType
        - paymentStatus
        - fulfillmentStatus
        - subtotalCents
        - discountCents
        - manualDiscountCents
        - taxCents
        - totalCents
        - note
        - source
        - tzOffsetMinutes
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        storeId:
          type: string
          format: uuid
        orderVersion:
          type: integer
        serviceType:
          type: string
          description: "`dine_in`, `takeaway`, `delivery`, etc."
        paymentStatus:
          type: string
          enum: [unpaid, partial, paid, refunded]
        fulfillmentStatus:
          type: string
          enum: [pending, pending_acceptance, accepted, preparing, ready, completed, cancelled]
        subtotalCents:
          type: integer
          description: Subtotal before discounts and tax (cents)
        discountCents:
          type: integer
          description: Promotion/coupon discount (cents)
        manualDiscountCents:
          type: integer
          description: Manual discount by staff (cents)
        taxCents:
          type: integer
          description: Tax amount (cents)
        totalCents:
          type: integer
          description: Final total (cents)
        couponCode:
          type: string
          nullable: true
        sequenceNumber:
          type: integer
          nullable: true
          description: Daily sequence number
        ticketNumber:
          type: string
          nullable: true
        note:
          type: string
        source:
          type: string
          description: "Order origin: `pos`, `kiosk`, `online`, etc."
        tzOffsetMinutes:
          type: integer
          description: Store timezone offset from UTC in minutes
        paidAt:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when payment was completed (null if unpaid)
        createdAt:
          type: string
          format: date-time
        tableId:
          type: string
          format: uuid
          nullable: true
        tableName:
          type: string
          nullable: true
        memberId:
          type: string
          format: uuid
          nullable: true
        memberName:
          type: string
          nullable: true
        memberPhone:
          type: string
          nullable: true
        shippingAddressId:
          type: string
          format: uuid
          nullable: true
          description: Shipping address ID (for delivery orders)
        parentOrderId:
          type: string
          format: uuid
          nullable: true
          description: Parent order ID (for split orders)
        pickupName:
          type: string
          nullable: true
        pickupPhone:
          type: string
          nullable: true
        pickupAt:
          type: string
          format: date-time
          nullable: true
        items:
          type: array
          items:
            $ref: "#/components/schemas/OrderItem"
          description: >
            Line items. Present in detail endpoint; in list endpoint only
            when `expand=items` is requested.
        payments:
          type: array
          items:
            $ref: "#/components/schemas/OrderPayment"
          description: >
            Payment records. Present in detail endpoint; in list endpoint
            only when `expand=payments` is requested.
        refunds:
          type: array
          items:
            $ref: "#/components/schemas/OrderRefund"
          description: >
            Refund records. Present in detail endpoint; in list endpoint
            only when `expand=refunds` is requested.
        taxBreakdown:
          type: array
          items:
            $ref: "#/components/schemas/TaxBreakdownEntry"
          description: >
            Per-rate tax breakdown. Present in detail endpoint; in list
            endpoint only when `expand=tax_breakdown` is requested.

    OrderPayment:
      type: object
      required:
        - id
        - orderId
        - paymentMethodId
        - amountCents
        - note
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        orderId:
          type: string
          format: uuid
        paymentMethodId:
          type: string
          format: uuid
        paymentMethodName:
          type: object
          additionalProperties:
            type: string
          description: "Localized name, e.g. `{\"_base\": \"Cash\", \"en\": \"Cash\"}`"
        paymentMethodCode:
          type: string
          description: "Machine-readable code, e.g. `cash`, `card`"
        amountCents:
          type: integer
          description: Amount paid (cents)
        tenderCents:
          type: integer
          nullable: true
          description: Amount tendered if different (cash overpayment)
        note:
          type: string
        createdAt:
          type: string
          format: date-time

    OrderDetail:
      description: >
        Full order object returned by the detail endpoint.
        Always includes items, payments, refunds, taxBreakdown,
        and appliedPromotions.
      allOf:
        - $ref: "#/components/schemas/Order"
        - type: object
          properties:
            appliedPromotions:
              type: array
              nullable: true
              items:
                $ref: "#/components/schemas/AppliedPromotion"

    OrderItem:
      type: object
      required:
        - id
        - orderId
        - productId
        - qty
        - unitPriceCents
        - amountCents
        - discountCents
        - manualDiscountCents
        - taxCents
        - refundedAmountCents
        - refundedQty
        - itemRole
      properties:
        id:
          type: string
          format: uuid
        orderId:
          type: string
          format: uuid
        productId:
          type: string
          format: uuid
        productName:
          type: object
          additionalProperties:
            type: string
          description: "Localized product name, e.g. `{\"_base\": \"Latte\", \"en\": \"Latte\"}`"
        variantId:
          type: string
          format: uuid
          nullable: true
        variantName:
          type: object
          additionalProperties:
            type: string
          nullable: true
        qty:
          type: number
        unitPriceCents:
          type: integer
        amountCents:
          type: integer
          description: Line total before discount (cents)
        discountCents:
          type: integer
        manualDiscountCents:
          type: integer
        isPriceOverride:
          type: boolean
        modifiers:
          type: array
          items:
            $ref: "#/components/schemas/OrderItemModifier"
        taxRateId:
          type: string
          nullable: true
        taxCents:
          type: integer
        refundedAmountCents:
          type: integer
        refundedQty:
          type: number
        submitRound:
          type: integer
          description: Submit round number (increments on each kitchen send)
        deltaQty:
          type: number
          description: Quantity change in the current submit round
        itemRole:
          type: string
          enum: [normal, combo_parent, combo_child]
        parentItemId:
          type: string
          format: uuid
          nullable: true
        comboGroupId:
          type: string
          description: Combo group ID within the combo product
        comboItemId:
          type: string
          description: Combo item ID within the group
        comboExtraCents:
          type: integer
          description: Extra charge for this combo selection (cents)

    AppliedPromotion:
      type: object
      required:
        - promotionId
        - triggerType
        - name
        - discountCents
      properties:
        promotionId:
          type: string
          format: uuid
        triggerType:
          type: string
          enum: [automatic, coupon]
          description: How the promotion was triggered
        memberCouponId:
          type: string
          format: uuid
          nullable: true
          description: Member coupon instance ID (when triggered by coupon)
        name:
          type: object
          additionalProperties:
            type: string
          description: "Localized promotion name, e.g. `{\"_base\": \"10% Off\", \"en\": \"10% Off\"}`"
        discountCents:
          type: integer
          description: Total discount from this promotion (cents)
        lineAllocations:
          type: array
          items:
            $ref: "#/components/schemas/DiscountAllocation"

    DiscountAllocation:
      type: object
      required:
        - lineIndex
        - discountCents
        - promotionId
      properties:
        lineIndex:
          type: integer
          description: Index into the items array
        discountCents:
          type: integer
          description: Discount allocated to this item (cents)
        promotionId:
          type: string
          format: uuid

    OrderItemModifier:
      type: object
      required:
        - id
        - name
        - priceDeltaCents
      properties:
        id:
          type: string
          description: Modifier option ID
        name:
          type: object
          additionalProperties:
            type: string
          description: "Localized modifier name, e.g. `{\"_base\": \"Extra cheese\", \"en\": \"Extra cheese\"}`"
        priceDeltaCents:
          type: integer
          description: Price adjustment (cents, can be negative)

    OrderRefund:
      type: object
      required:
        - id
        - orderId
        - amountCents
        - reason
        - createdAt
      properties:
        id:
          type: string
          format: uuid
        orderId:
          type: string
          format: uuid
        amountCents:
          type: integer
        reason:
          type: string
        createdAt:
          type: string
          format: date-time
        items:
          type: array
          items:
            $ref: "#/components/schemas/OrderRefundItem"
        payments:
          type: array
          items:
            $ref: "#/components/schemas/OrderRefundPayment"

    OrderRefundItem:
      type: object
      required:
        - id
        - refundId
        - orderItemId
        - qty
        - amountCents
        - taxCents
      properties:
        id:
          type: string
          format: uuid
        refundId:
          type: string
          format: uuid
        orderItemId:
          type: string
          format: uuid
        qty:
          type: number
        amountCents:
          type: integer
        taxCents:
          type: integer

    OrderRefundPayment:
      type: object
      required:
        - id
        - refundId
        - paymentMethodId
        - amountCents
      properties:
        id:
          type: string
          format: uuid
        refundId:
          type: string
          format: uuid
        paymentMethodId:
          type: string
          format: uuid
        paymentMethodName:
          type: object
          additionalProperties:
            type: string
        paymentMethodCode:
          type: string
        amountCents:
          type: integer

    TaxBreakdownEntry:
      type: object
      required:
        - taxRateId
        - taxRatePercent
        - taxCents
      properties:
        taxRateId:
          type: string
          description: Tax rate ID (empty string if unset)
        taxRatePercent:
          type: number
        taxCents:
          type: integer

    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Human-readable error message
        request_id:
          type: string
          description: Unique request ID for debugging