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

# Create a delivery quote

> Calculates a quote from pickup and drop-off coordinates. This operation
does not create or reserve a delivery and does not require an
`Idempotency-Key`.




## OpenAPI

````yaml /openapi.yaml post /quotes
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:
  /quotes:
    post:
      tags:
        - Quotes
      summary: Create a delivery quote
      description: |
        Calculates a quote from pickup and drop-off coordinates. This operation
        does not create or reserve a delivery and does not require an
        `Idempotency-Key`.
      operationId: createQuote
      parameters:
        - $ref: '#/components/parameters/XRequestID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
            example:
              pickup:
                latitude: 5.6037
                longitude: -0.187
              dropoff:
                latitude: 5.6698
                longitude: -0.1695
              vehicle_type: bike
      responses:
        '200':
          description: Quote calculated.
          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/QuoteSuccessResponse'
              example:
                success: true
                statusCode: 200
                message: Quote calculated
                data:
                  environment: live
                  simulated: false
                  vehicle_type: bike
                  currency: GHS
                  distance_km: 8.4
                  distance_source: road
                  fee: 40
                  requires_custom_quote: false
        '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'
        '503':
          $ref: '#/components/responses/QuoteUnavailable'
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
  schemas:
    QuoteRequest:
      type: object
      additionalProperties: false
      required:
        - pickup
        - dropoff
        - vehicle_type
      properties:
        pickup:
          $ref: '#/components/schemas/Coordinates'
        dropoff:
          $ref: '#/components/schemas/Coordinates'
        vehicle_type:
          $ref: '#/components/schemas/VehicleType'
    QuoteSuccessResponse:
      $ref: '#/components/schemas/SuccessEnvelopeQuote'
    Coordinates:
      type: object
      additionalProperties: false
      required:
        - latitude
        - longitude
      properties:
        latitude:
          type: number
          format: double
          minimum: -90
          maximum: 90
          example: 5.56
        longitude:
          type: number
          format: double
          minimum: -180
          maximum: 180
          example: -0.2057
    VehicleType:
      type: string
      enum:
        - bike
        - minivan
      example: bike
    SuccessEnvelopeQuote:
      type: object
      additionalProperties: false
      required:
        - success
        - statusCode
        - message
        - data
      properties:
        success:
          type: boolean
          const: true
        statusCode:
          type: integer
          enum:
            - 200
        message:
          type: string
        data:
          $ref: '#/components/schemas/Quote'
    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'
    Quote:
      type: object
      additionalProperties: false
      required:
        - environment
        - simulated
        - vehicle_type
        - currency
        - distance_km
        - distance_source
        - requires_custom_quote
      properties:
        environment:
          $ref: '#/components/schemas/Environment'
        simulated:
          type: boolean
          description: Always `true` for sandbox quotes.
        vehicle_type:
          $ref: '#/components/schemas/VehicleType'
        currency:
          type: string
          const: GHS
        distance_km:
          type: number
          format: double
          minimum: 0
        distance_source:
          type: string
          enum:
            - road
            - estimated
            - sandbox_fixture
        fee:
          type:
            - number
            - 'null'
          format: double
          minimum: 0
          description: '`null` when `requires_custom_quote` is true.'
        requires_custom_quote:
          type: boolean
    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.
    Environment:
      type: string
      enum:
        - test
        - live
      example: live
  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
    QuoteUnavailable:
      description: A quote could not be calculated at this time.
      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: 503
            message: A delivery quote is temporarily unavailable
            error:
              code: QUOTE_UNAVAILABLE
  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.

````