openapi: 3.0.3
info:
  title: User Checkout API
  description: API endpoints for user checkout and order management
  version: 1.0.0
  contact:
    name: Makkok API
    
servers:
  - url: http://localhost:8000/api/user
    description: Local development server
    
security:
  - bearerAuth: []
    
paths:
  /checkout:
    post:
      summary: Checkout cart and create order
      description: Convert user's cart into an order with selected payment method
      tags:
        - Checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - address_id
                - payment_method
              properties:
                address_id:
                  type: integer
                  description: ID of delivery address
                  example: 1
                payment_method:
                  type: string
                  enum: [cash, online]
                  description: Payment method selection
                  example: "cash"
                notes:
                  type: string
                  maxLength: 500
                  description: Optional order notes
                  example: "Please call before delivery"
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Order placed successfully"
                  data:
                    type: object
                    properties:
                      order:
                        $ref: '#/components/schemas/OrderSummary'
        '409':
          description: Store conflict (different store in cart)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '404':
          description: Cart not found or empty
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                
  /orders:
    get:
      summary: Get user's order history
      description: Retrieve list of user's orders with pagination and filtering
      tags:
        - Orders
      parameters:
        - name: status
          in: query
          description: Filter by order status
          schema:
            type: string
            enum: [pending, pending_payment, confirmed, preparing, ready, out_for_delivery, delivered, cancelled]
        - name: page
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Items per page
          schema:
            type: integer
            default: 15
            maximum: 100
      responses:
        '200':
          description: Orders retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Orders retrieved successfully"
                  data:
                    type: object
                    properties:
                      orders:
                        type: array
                        items:
                          $ref: '#/components/schemas/OrderListItem'
                      pagination:
                        $ref: '#/components/schemas/Pagination'
                        
  /orders/{orderId}:
    get:
      summary: Get single order details
      description: Retrieve complete details of a specific order
      tags:
        - Orders
      parameters:
        - name: orderId
          in: path
          required: true
          description: Order ID
          schema:
            type: integer
      responses:
        '200':
          description: Order details retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Order retrieved successfully"
                  data:
                    type: object
                    properties:
                      order:
                        $ref: '#/components/schemas/OrderDetail'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
                
  /orders/{orderId}/cancel:
    post:
      summary: Cancel order
      description: Cancel order if status is pending or pending_payment
      tags:
        - Orders
      parameters:
        - name: orderId
          in: path
          required: true
          description: Order ID
          schema:
            type: integer
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  maxLength: 500
                  description: Cancellation reason
                  example: "Changed my mind"
      responses:
        '200':
          description: Order cancelled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Order cancelled successfully"
        '400':
          description: Cannot cancel order in current status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      
  schemas:
    OrderSummary:
      type: object
      properties:
        id:
          type: integer
          example: 1
        order_number:
          type: string
          example: "ORD-20251030-00001"
        status:
          type: string
          enum: [pending, pending_payment, confirmed, preparing, ready, out_for_delivery, delivered, cancelled]
          example: "pending"
        payment_method:
          type: string
          enum: [cash, online]
          example: "cash"
        payment_status:
          type: string
          enum: [pending, paid, failed, refunded]
          example: "pending"
        payment_reference:
          type: string
          nullable: true
          example: "PAY-PLACEHOLDER-12345"
        payment_url:
          type: string
          nullable: true
          example: "https://payment.example.com/pay/12345"
        subtotal:
          type: string
          example: "150.00"
        delivery_fee:
          type: string
          example: "10.00"
        tax:
          type: string
          example: "0.00"
        total:
          type: string
          example: "160.00"
        items_count:
          type: integer
          example: 3
        created_at:
          type: string
          format: date-time
          example: "2025-10-30T10:30:00Z"
          
    OrderListItem:
      type: object
      properties:
        id:
          type: integer
          example: 1
        order_number:
          type: string
          example: "ORD-20251030-00001"
        store:
          type: object
          properties:
            id:
              type: integer
              example: 1
            name:
              type: string
              example: "Pizza Palace"
            logo_url:
              type: string
              example: "https://example.com/logos/store1.jpg"
        status:
          type: string
          example: "pending"
        status_label:
          type: string
          example: "Pending Confirmation"
        payment_method:
          type: string
          example: "cash"
        total:
          type: string
          example: "160.00"
        items_count:
          type: integer
          example: 3
        created_at:
          type: string
          format: date-time
          example: "2025-10-30T10:30:00Z"
          
    OrderDetail:
      type: object
      properties:
        id:
          type: integer
          example: 1
        order_number:
          type: string
          example: "ORD-20251030-00001"
        store:
          type: object
          properties:
            id:
              type: integer
              example: 1
            name:
              type: string
              example: "Pizza Palace"
            description:
              type: string
              example: "Best pizza in town"
            logo_url:
              type: string
              example: "https://example.com/logos/store1.jpg"
            phone:
              type: string
              example: "+966501234567"
        address:
          type: object
          properties:
            address_type:
              type: string
              example: "apartment"
            building_name:
              type: string
              example: "Tower A"
            apartment_number:
              type: string
              example: "501"
            floor_number:
              type: string
              example: "5"
            street_name:
              type: string
              example: "Main Street"
            landmark:
              type: string
              example: "Near City Mall"
            phone:
              type: string
              example: "+966501234567"
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
                example: 1
              product:
                type: object
                properties:
                  name:
                    type: string
                    example: "Margherita Pizza"
                  description:
                    type: string
                    example: "Classic pizza with tomato and mozzarella"
                  image_url:
                    type: string
                    example: "https://example.com/images/pizza.jpg"
              quantity:
                type: integer
                example: 2
              selected_options:
                type: array
                items:
                  type: object
                  properties:
                    option_group_name:
                      type: string
                      example: "Size"
                    option_value_name:
                      type: string
                      example: "Large"
                    calculated_price:
                      type: string
                      example: "9.00"
              selected_addons:
                type: array
                items:
                  type: object
                  properties:
                    addon_name:
                      type: string
                      example: "Extra Cheese"
                    quantity:
                      type: integer
                      example: 1
                    total_price:
                      type: string
                      example: "5.00"
              unit_price:
                type: string
                example: "59.00"
              total_price:
                type: string
                example: "118.00"
        status:
          type: string
          example: "pending"
        status_label:
          type: string
          example: "Pending Confirmation"
        payment_method:
          type: string
          example: "cash"
        payment_status:
          type: string
          example: "pending"
        payment_reference:
          type: string
          nullable: true
          example: null
        subtotal:
          type: string
          example: "150.00"
        delivery_fee:
          type: string
          example: "10.00"
        tax:
          type: string
          example: "0.00"
        total:
          type: string
          example: "160.00"
        notes:
          type: string
          nullable: true
          example: "Please call before delivery"
        created_at:
          type: string
          format: date-time
          example: "2025-10-30T10:30:00Z"
        updated_at:
          type: string
          format: date-time
          example: "2025-10-30T10:30:00Z"
          
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 15
        total:
          type: integer
          example: 45
        last_page:
          type: integer
          example: 3
        from:
          type: integer
          example: 1
        to:
          type: integer
          example: 15
          
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Error message"
          
    ValidationError:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Validation failed"
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          example:
            address_id: ["The selected address is invalid"]
            payment_method: ["The payment method field is required"]
