> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haulstow.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List deliveries

> Returns only deliveries created by the authenticated application. Results
are ordered by `(created_at, id)` and use opaque cursor pagination.




## OpenAPI

````yaml /openapi.yaml get /deliveries
openapi: 3.1.0
info:
  title: HaulStow Developer Delivery API
  version: 1.0.0
  summary: Create, quote, track, and test HaulStow deliveries.
  description: >
    The HaulStow Developer Delivery API is a server-to-server API for existing

    HaulStow business customers. Authenticate every request with a
    business-bound

    `hsg_live_key_...` API key. Use a test key with the sandbox base URL for

    deterministic, side-effect-free integration testing.


    All JSON responses use the same envelope. Every response includes

    `X-Request-ID` and rate-limit headers. Keep the request ID when contacting

    HaulStow support.
  contact:
    name: HaulStow Developer Support
    email: support@haulstow.co
servers:
  - url: https://developer.haulstow.co/v1
    description: Live
security:
  - DeveloperApiKey: []
tags:
  - name: Quotes
    description: Calculate a delivery quote without creating a delivery.
  - name: Recipients
    description: Manage business-scoped recipients and reusable addresses.
  - name: Deliveries
    description: Create and inspect deliveries created by the authenticated application.
  - name: Sandbox
    description: Test-only helpers that never affect live operations.
  - name: Webhooks
    description: Signed delivery lifecycle callbacks sent by HaulStow.
paths:
  /deliveries:
    get:
      tags:
        - Deliveries
      summary: List deliveries
      description: >
        Returns only deliveries created by the authenticated application.
        Results

        are ordered by `(created_at, id)` and use opaque cursor pagination.
      operationId: listDeliveries
      parameters:
        - $ref: '#/components/parameters/XRequestID'
        - $ref: '#/components/parameters/Cursor'
        - $ref: '#/components/parameters/Limit'
        - name: status
          in: query
          description: Filter by one public delivery status.
          schema:
            $ref: '#/components/schemas/DeliveryStatus'
        - name: external_id
          in: query
          description: Match one application-defined external ID.
          schema:
            type: string
            maxLength: 128
        - name: created_after
          in: query
          description: Include deliveries created at or after this RFC 3339 timestamp.
          schema:
            type: string
            format: date-time
        - name: created_before
          in: query
          description: Include deliveries created before this RFC 3339 timestamp.
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Delivery page returned.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestID'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliveryListSuccessResponse'
              example:
                success: true
                statusCode: 200
                message: OK
                data:
                  - id: dlv_3f1a821cdb58498cbb52f4706545a089
                    external_id: shop-order-1842
                    reference: H-RS83223
                    environment: live
                    simulated: false
                    status: booked
                    recipient:
                      id: rcp_3f1a821cdb58498cbb52f4706545a089
                      name: Ama Mensah
                      phone_number: '+233245412312'
                    pickup:
                      name: Osu Store
                      contact: '+233200000001'
                      address: Oxford Street, Osu, Accra
                      latitude: 5.556
                      longitude: -0.182
                    dropoff:
                      id: adr_78de60204f574a64be88ba9bd94a049f
                      address: 15 Independence Avenue, Accra
                      latitude: 5.56
                      longitude: -0.2057
                    payment:
                      type: cod
                      goods_value: 185
                    vehicle_type: bike
                    currency: GHS
                    delivery_fee: 20
                    requires_custom_quote: false
                    tracking_url: https://track.haulstow.co/H-RS83223
                    created_at: '2026-08-20T14:20:00Z'
                    updated_at: '2026-08-20T14:20:00Z'
                meta:
                  limit: 25
                  has_more: false
                  next_cursor: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    XRequestID:
      name: X-Request-ID
      in: header
      required: false
      description: >
        Optional caller correlation ID. Use 1–128 ASCII letters, digits, `.`,
        `_`,

        `-`, or `:`. Invalid values are replaced. The accepted/generated value
        is

        returned in the response.
      schema:
        type: string
        minLength: 1
        maxLength: 128
        pattern: ^[A-Za-z0-9._:-]+$
      example: req_shop_1842_create
    Cursor:
      name: cursor
      in: query
      required: false
      description: >-
        Opaque cursor returned as `meta.next_cursor`. Do not construct or modify
        it.
      schema:
        type: string
        maxLength: 512
    Limit:
      name: limit
      in: query
      required: false
      description: Number of resources to return.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  schemas:
    DeliveryStatus:
      type: string
      enum:
        - booked
        - assigned
        - picked_up
        - in_transit
        - delivered
        - failed
        - cancelled
        - outsourced
      example: in_transit
    DeliveryListSuccessResponse:
      $ref: '#/components/schemas/SuccessEnvelopeDeliveryList'
    SuccessEnvelopeDeliveryList:
      type: object
      additionalProperties: false
      required:
        - success
        - statusCode
        - message
        - data
        - meta
      properties:
        success:
          type: boolean
          const: true
        statusCode:
          type: integer
          enum:
            - 200
        message:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/Delivery'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - success
        - statusCode
        - message
        - error
      properties:
        success:
          type: boolean
          const: false
        statusCode:
          type: integer
          minimum: 400
          maximum: 599
        message:
          type: string
        error:
          $ref: '#/components/schemas/ErrorPayload'
    Delivery:
      type: object
      additionalProperties: false
      required:
        - id
        - environment
        - simulated
        - status
        - recipient
        - pickup
        - dropoff
        - payment
        - vehicle_type
        - currency
        - requires_custom_quote
        - created_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/DeliveryID'
        external_id:
          type:
            - string
            - 'null'
          maxLength: 128
        reference:
          type:
            - string
            - 'null'
          description: HaulStow's human-readable delivery reference.
          example: H-RS83223
        environment:
          $ref: '#/components/schemas/Environment'
        simulated:
          type: boolean
        status:
          $ref: '#/components/schemas/DeliveryStatus'
        recipient:
          $ref: '#/components/schemas/DeliveryRecipient'
        pickup:
          $ref: '#/components/schemas/Pickup'
        dropoff:
          $ref: '#/components/schemas/DeliveryDropoff'
        payment:
          $ref: '#/components/schemas/DeliveryPayment'
        vehicle_type:
          $ref: '#/components/schemas/VehicleType'
        delivery_instructions:
          type:
            - string
            - 'null'
        currency:
          type: string
          const: GHS
        delivery_fee:
          type:
            - number
            - 'null'
          format: double
          minimum: 0
          description: '`null` when a manual quote is required.'
        requires_custom_quote:
          type: boolean
        tracking_url:
          type:
            - string
            - 'null'
          format: uri
          description: Always `null` for sandbox deliveries.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    PaginationMeta:
      type: object
      additionalProperties: false
      required:
        - limit
        - has_more
        - next_cursor
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 100
        has_more:
          type: boolean
        next_cursor:
          type:
            - string
            - 'null'
          description: Pass this opaque value as `cursor`; `null` marks the last page.
    ErrorPayload:
      type: object
      additionalProperties: false
      required:
        - code
      properties:
        code:
          type: string
          description: Stable machine-readable error code.
          example: VALIDATION_ERROR
        details:
          type: object
          additionalProperties: true
          description: >-
            Optional structured context. Do not parse `message` for control
            flow.
    DeliveryID:
      type: string
      pattern: ^dlv_[a-f0-9]{32}$
      example: dlv_3f1a821cdb58498cbb52f4706545a089
    Environment:
      type: string
      enum:
        - test
        - live
      example: live
    DeliveryRecipient:
      type: object
      additionalProperties: false
      required:
        - id
        - phone_number
      properties:
        id:
          $ref: '#/components/schemas/RecipientID'
        name:
          type:
            - string
            - 'null'
        phone_number:
          type: string
    Pickup:
      type: object
      additionalProperties: false
      required:
        - name
        - contact
        - address
        - latitude
        - longitude
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        contact:
          type: string
          minLength: 5
          maxLength: 64
        address:
          type: string
          minLength: 2
          maxLength: 500
        latitude:
          type: number
          format: double
          minimum: -90
          maximum: 90
        longitude:
          type: number
          format: double
          minimum: -180
          maximum: 180
    DeliveryDropoff:
      type: object
      additionalProperties: false
      required:
        - id
        - address
        - latitude
        - longitude
      properties:
        id:
          $ref: '#/components/schemas/AddressID'
        label:
          type:
            - string
            - 'null'
        address:
          type: string
        latitude:
          type: number
          format: double
        longitude:
          type: number
          format: double
        municipality:
          type:
            - string
            - 'null'
        delivery_notes:
          type:
            - string
            - 'null'
    DeliveryPayment:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - cod
            - delivery_only
            - client_billed
        goods_value:
          type: number
          format: double
          exclusiveMinimum: 0
          description: Present only for COD.
    VehicleType:
      type: string
      enum:
        - bike
        - minivan
      example: bike
    RecipientID:
      type: string
      pattern: ^rcp_[a-f0-9]{32}$
      example: rcp_3f1a821cdb58498cbb52f4706545a089
    AddressID:
      type: string
      pattern: ^adr_[a-f0-9]{32}$
      example: adr_78de60204f574a64be88ba9bd94a049f
  headers:
    XRequestID:
      description: Correlation ID for the request.
      schema:
        type: string
      example: 01J5T33T75A8S2JCB37Y6Z5Y4N
    RateLimitLimit:
      description: Maximum requests available in the current window.
      schema:
        type: integer
        minimum: 0
      example: 120
    RateLimitRemaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
        minimum: 0
      example: 119
    RateLimitReset:
      description: Unix timestamp in seconds when the current window resets.
      schema:
        type: integer
        format: int64
      example: 1787236260
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 1
      example: 30
  responses:
    Unauthorized:
      description: >-
        API key is missing, malformed, revoked, expired, or belongs to another
        environment.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalid:
              value:
                success: false
                statusCode: 401
                message: API key is invalid
                error:
                  code: INVALID_API_KEY
            revoked:
              value:
                success: false
                statusCode: 401
                message: API key has been revoked
                error:
                  code: API_KEY_REVOKED
            expired:
              value:
                success: false
                statusCode: 401
                message: API key has expired
                error:
                  code: API_KEY_EXPIRED
            environment:
              value:
                success: false
                statusCode: 401
                message: API key does not match this environment
                error:
                  code: ENVIRONMENT_MISMATCH
    Forbidden:
      description: The authenticated key lacks the operation's required scope.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            statusCode: 403
            message: API key lacks the required scope
            error:
              code: INSUFFICIENT_SCOPE
              details:
                required_scope: deliveries:write
    ValidationError:
      description: Request parameters or body are invalid.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            validation:
              value:
                success: false
                statusCode: 422
                message: Delivery request is invalid
                error:
                  code: VALIDATION_ERROR
                  details:
                    fields:
                      - field: pickup.latitude
                        message: Latitude must be between -90 and 90
            codGoodsValue:
              value:
                success: false
                statusCode: 422
                message: Goods value is required for COD deliveries
                error:
                  code: COD_GOODS_VALUE_REQUIRED
    RateLimited:
      description: Rate limit exceeded.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            statusCode: 429
            message: Too many requests; please try again later
            error:
              code: RATE_LIMIT_EXCEEDED
    InternalError:
      description: Unexpected server error. Quote `X-Request-ID` when contacting support.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestID'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            statusCode: 500
            message: Internal server error
            error:
              code: INTERNAL_SERVER_ERROR
  securitySchemes:
    DeveloperApiKey:
      type: http
      scheme: bearer
      bearerFormat: hsg_live_key_... or hsg_test_key_...
      description: >
        A business-bound HaulStow API key. Send

        `Authorization: Bearer hsg_live_key_...` to the live server or a

        `hsg_test_key_...` key to the sandbox server. Never expose this key in a
        browser.

````