openapi: 3.0.1
info:
  title: Shipday API
  description: >-
    The Shipday REST API lets you programmatically manage delivery and pickup
    orders, drivers (carriers), order assignment to your own fleet, and an
    on-demand delivery network (Uber, DoorDash) for last-mile fulfillment.
    The API is served over HTTPS and secured with HTTP Basic authentication
    using your API key.
  termsOfService: https://www.shipday.com/terms
  contact:
    name: Shipday Support
    url: https://www.shipday.com
  version: '1.0'
servers:
  - url: https://api.shipday.com
security:
  - basicAuth: []
paths:
  /orders:
    get:
      operationId: retrieveActiveOrders
      tags:
        - Orders
      summary: Retrieve active orders
      description: Returns an array of active order objects for the account.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Order'
    post:
      operationId: insertOrder
      tags:
        - Orders
      summary: Insert a delivery order
      description: Creates a new delivery order.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsertOrderRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsertOrderResponse'
  /order/edit/{orderId}:
    put:
      operationId: editOrder
      tags:
        - Orders
      summary: Edit an order
      description: Edits an existing order identified by its orderId.
      parameters:
        - name: orderId
          in: path
          required: true
          description: Unique identifier of the order returned when it was placed.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditOrderRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleResponse'
  /orders/{orderId}:
    delete:
      operationId: deleteOrder
      tags:
        - Orders
      summary: Delete an order
      description: Deletes an order identified by its orderId.
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleResponse'
  /carriers:
    get:
      operationId: retrieveCarriers
      tags:
        - Drivers
      summary: Retrieve carriers
      description: Returns the list of carriers (drivers) on the account.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Carrier'
    post:
      operationId: addCarrier
      tags:
        - Drivers
      summary: Add a carrier
      description: >-
        Adds a new carrier (driver) to the account and returns an
        auto-generated password for the driver app login.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCarrierRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddCarrierResponse'
  /carriers/{carrierId}:
    delete:
      operationId: deleteCarrier
      tags:
        - Drivers
      summary: Delete a carrier
      description: Removes a carrier (driver) from the account.
      parameters:
        - name: carrierId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleResponse'
  /orders/assign/{orderId}/{carrierId}:
    put:
      operationId: assignOrderToCarrier
      tags:
        - Assignment
      summary: Assign an order to a carrier
      description: >-
        Assigns an order to a specific carrier (driver) in your own fleet by
        order ID and carrier ID.
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
        - name: carrierId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '204':
          description: Assignment successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleResponse'
  /orders/assign/{orderId}:
    delete:
      operationId: unassignOrder
      tags:
        - Assignment
      summary: Unassign an order from a driver
      description: Removes the current carrier assignment from an order.
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleResponse'
  /on-demand/availability:
    post:
      operationId: checkOnDemandAvailability
      tags:
        - On-Demand Delivery
      summary: Check on-demand delivery availability
      description: >-
        Returns available third-party delivery providers (e.g. DoorDash, Uber)
        with fees and timing estimates for a given pickup/delivery pair.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvailabilityRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AvailabilityOption'
  /on-demand/assign:
    post:
      operationId: assignOnDemand
      tags:
        - On-Demand Delivery
      summary: Assign an order to an on-demand provider
      description: >-
        Assigns an order to a specific third-party delivery service provider
        (e.g. Uber, DoorDash) for last-mile fulfillment.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OnDemandAssignRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnDemandDeliveryDetails'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication. Send your API key as the credential in the
        Authorization header, e.g. `Authorization: Basic {API_KEY}`.
  schemas:
    InsertOrderRequest:
      type: object
      required:
        - orderNumber
        - customerName
        - customerAddress
        - restaurantName
        - restaurantAddress
      properties:
        orderNumber:
          type: string
        customerName:
          type: string
        customerAddress:
          type: string
        customerEmail:
          type: string
        customerPhoneNumber:
          type: string
        restaurantName:
          type: string
        restaurantAddress:
          type: string
        restaurantPhoneNumber:
          type: string
        expectedDeliveryDate:
          type: string
          description: Date in yyyy-mm-dd format.
        expectedPickupTime:
          type: string
          description: Time in hh:mm:ss format.
        expectedDeliveryTime:
          type: string
          description: Time in hh:mm:ss format.
        pickupLatitude:
          type: number
          format: double
        pickupLongitude:
          type: number
          format: double
        deliveryLatitude:
          type: number
          format: double
        deliveryLongitude:
          type: number
          format: double
        orderItem:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        tips:
          type: number
          format: double
        tax:
          type: number
          format: double
        discountAmount:
          type: number
          format: double
        deliveryFee:
          type: number
          format: double
        totalOrderCost:
          type: number
          format: double
        deliveryInstruction:
          type: string
        pickupInstruction:
          type: string
        orderSource:
          type: string
        additionalId:
          type: string
        clientRestaurantId:
          type: integer
        paymentMethod:
          type: string
          enum:
            - cash
            - credit_card
        creditCardType:
          type: string
          enum:
            - VISA
            - MASTER_CARD
            - AMEX
            - OTHER
        creditCardId:
          type: integer
        isCatering:
          type: boolean
    EditOrderRequest:
      type: object
      required:
        - orderNo
        - customerName
        - customerAddress
        - customerEmail
        - customerPhoneNumber
        - restaurantName
        - restaurantAddress
      properties:
        orderNo:
          type: string
        customerName:
          type: string
        customerAddress:
          type: string
        customerEmail:
          type: string
        customerPhoneNumber:
          type: string
        restaurantName:
          type: string
        restaurantAddress:
          type: string
        restaurantPhoneNumber:
          type: string
        expectedDeliveryDate:
          type: string
        expectedPickupTime:
          type: string
        expectedDeliveryTime:
          type: string
        tips:
          type: number
          format: double
        tax:
          type: number
          format: double
        discountAmount:
          type: number
          format: double
        deliveryFee:
          type: number
          format: double
        totalOrderCost:
          type: number
          format: double
        deliveryInstruction:
          type: string
        paymentMethod:
          type: string
          enum:
            - cash
            - credit_card
    InsertOrderResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Indicates the success of the order insert.
        response:
          type: string
          description: Message on successful creation of the order.
        orderId:
          type: integer
          description: Unique identifier for the created order.
    SimpleResponse:
      type: object
      properties:
        success:
          type: boolean
        response:
          type: string
    OrderItem:
      type: object
      properties:
        name:
          type: string
        unitPrice:
          type: number
          format: double
        quantity:
          type: integer
        addOns:
          type: array
          items:
            type: string
        detail:
          type: string
    Order:
      type: object
      properties:
        orderId:
          type: integer
        orderNumber:
          type: string
        companyId:
          type: integer
        areaId:
          type: integer
        customerName:
          type: string
        customerAddress:
          type: string
        customerPhoneNumber:
          type: string
        customerEmail:
          type: string
        deliveryLatitude:
          type: number
          format: double
        deliveryLongitude:
          type: number
          format: double
        restaurantName:
          type: string
        restaurantAddress:
          type: string
        restaurantPhoneNumber:
          type: string
        pickupLatitude:
          type: number
          format: double
        pickupLongitude:
          type: number
          format: double
        assignedCarrier:
          $ref: '#/components/schemas/Carrier'
        distance:
          type: number
          format: double
        placementTime:
          type: string
        expectedPickupTime:
          type: string
        expectedDeliveryDate:
          type: string
        expectedDeliveryTime:
          type: string
        deliveryTime:
          type: string
        totalCost:
          type: number
          format: double
        deliveryFee:
          type: number
          format: double
        tip:
          type: number
          format: double
        tax:
          type: number
          format: double
        discountAmount:
          type: number
          format: double
        paymentMethod:
          type: string
        orderItems:
          type: array
          items:
            $ref: '#/components/schemas/OrderItem'
        orderState:
          type: string
        trackingLink:
          type: string
        deliveryInstruction:
          type: string
    AddCarrierRequest:
      type: object
      required:
        - name
        - email
        - phoneNumber
      properties:
        name:
          type: string
          description: Full name of the carrier (driver).
        email:
          type: string
          description: Valid email address of the carrier.
        phoneNumber:
          type: string
          description: Phone number, optionally including country code.
    AddCarrierResponse:
      type: object
      properties:
        carrierId:
          type: integer
        email:
          type: string
        password:
          type: string
          description: Auto-generated password the carrier should update.
        message:
          type: string
    Carrier:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        phoneNumber:
          type: string
        email:
          type: string
        carrierPhoto:
          type: string
        isOnShift:
          type: boolean
        isActive:
          type: boolean
    AvailabilityRequest:
      type: object
      required:
        - pickupAddress
        - deliveryAddress
      properties:
        pickupAddress:
          type: string
          description: Pickup address of the order.
        deliveryAddress:
          type: string
          description: Delivery address of the order.
        deliveryTime:
          type: string
          description: Expected delivery time in ISO 8601 UTC format.
        pickUpTime:
          type: string
          description: Expected pickup time in ISO 8601 UTC format.
    AvailabilityOption:
      type: object
      properties:
        name:
          type: string
          description: Provider name (e.g. DoorDash, Uber, MotoClick).
        fee:
          type: number
          format: double
        pickupTime:
          type: string
        deliveryTime:
          type: string
        pickupDuration:
          type: integer
        deliveryDuration:
          type: integer
        error:
          type: boolean
        errorMessage:
          type: string
        errorDescription:
          type: string
    OnDemandAssignRequest:
      type: object
      required:
        - name
        - orderId
      properties:
        name:
          type: string
          description: Third-party service provider name (e.g. Uber, DoorDash).
        orderId:
          type: integer
        tip:
          type: number
          format: double
        estimateReference:
          type: string
          description: Reference ID from a prior availability estimate.
        contactlessDelivery:
          type: boolean
          default: false
        podType:
          type: string
          enum:
            - PHOTO
            - SIGNATURE
            - PIN
            - NONE
        podTypes:
          type: array
          items:
            type: string
            enum:
              - PHOTO
              - SIGNATURE
              - PIN
              - NONE
    OnDemandDeliveryDetails:
      type: object
      properties:
        orderId:
          type: integer
        provider:
          type: string
        trackingUrl:
          type: string
        fee:
          type: number
          format: double
        status:
          type: string
        driverName:
          type: string
        driverPhoneNumber:
          type: string