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

> Creates one delivery using either existing recipient/address IDs or one
inline recipient. The two recipient shapes are mutually exclusive.

This public contract is content-opaque: it accepts no line items,
product contents, declared value, rider, vehicle, fee override,
`business_id`, or operational status.




## OpenAPI

````yaml /openapi.yaml post /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:
    post:
      tags:
        - Deliveries
      summary: Create a delivery
      description: |
        Creates one delivery using either existing recipient/address IDs or one
        inline recipient. The two recipient shapes are mutually exclusive.

        This public contract is content-opaque: it accepts no line items,
        product contents, declared value, rider, vehicle, fee override,
        `business_id`, or operational status.
      operationId: createDelivery
      parameters:
        - $ref: '#/components/parameters/XRequestID'
        - $ref: '#/components/parameters/RequiredIdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeliveryRequest'
            examples:
              inlineRecipient:
                summary: Create with an inline recipient
                value:
                  external_id: shop-order-1842
                  recipient:
                    name: Ama Mensah
                    phone_number: '+233245412312'
                    address:
                      label: Home
                      address: 15 Independence Avenue, Accra
                      latitude: 5.56
                      longitude: -0.2057
                      municipality: Accra Metropolitan
                      delivery_notes: Call when you arrive
                  pickup:
                    name: Osu Store
                    contact: '+233200000001'
                    address: Oxford Street, Osu, Accra
                    latitude: 5.556
                    longitude: -0.182
                  payment:
                    type: cod
                    goods_value: 185
                  vehicle_type: bike
                  delivery_instructions: Leave with the front desk if authorized
              existingRecipient:
                summary: Reuse recipient and address IDs
                value:
                  recipient_id: rcp_3f1a821cdb58498cbb52f4706545a089
                  recipient_address_id: adr_78de60204f574a64be88ba9bd94a049f
                  pickup:
                    name: Osu Store
                    contact: '+233200000001'
                    address: Oxford Street, Osu, Accra
                    latitude: 5.556
                    longitude: -0.182
                  payment:
                    type: delivery_only
                  vehicle_type: bike
      responses:
        '201':
          description: Delivery created.
          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'
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeliverySuccessResponse'
              example:
                success: true
                statusCode: 201
                message: Delivery created
                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
                    label: Home
                    address: 15 Independence Avenue, Accra
                    latitude: 5.56
                    longitude: -0.2057
                    municipality: Accra Metropolitan
                    delivery_notes: Call when you arrive
                  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'
        '400':
          $ref: '#/components/responses/IdempotencyKeyRequired'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/DeliveryDependencyNotFound'
        '409':
          $ref: '#/components/responses/DeliveryConflict'
        '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
    RequiredIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: A unique key for this logical mutation. Retained for 24 hours.
      schema:
        type: string
        minLength: 8
        maxLength: 255
      example: shop-order-1842-create-v1
  schemas:
    CreateDeliveryRequest:
      type: object
      additionalProperties: false
      required:
        - pickup
        - payment
        - vehicle_type
      properties:
        external_id:
          type: string
          minLength: 1
          maxLength: 128
          description: Unique within the authenticated application when supplied.
        recipient_id:
          $ref: '#/components/schemas/RecipientID'
        recipient_address_id:
          $ref: '#/components/schemas/AddressID'
        recipient:
          $ref: '#/components/schemas/InlineRecipientRequest'
        pickup:
          $ref: '#/components/schemas/Pickup'
        payment:
          $ref: '#/components/schemas/DeliveryPaymentRequest'
        vehicle_type:
          $ref: '#/components/schemas/VehicleType'
        delivery_instructions:
          type: string
          maxLength: 500
      oneOf:
        - title: Existing recipient and address
          required:
            - recipient_id
            - recipient_address_id
          not:
            required:
              - recipient
        - title: Inline recipient and address
          required:
            - recipient
          allOf:
            - not:
                required:
                  - recipient_id
            - not:
                required:
                  - recipient_address_id
    DeliverySuccessResponse:
      $ref: '#/components/schemas/SuccessEnvelopeDelivery'
    RecipientID:
      type: string
      pattern: ^rcp_[a-f0-9]{32}$
      example: rcp_3f1a821cdb58498cbb52f4706545a089
    AddressID:
      type: string
      pattern: ^adr_[a-f0-9]{32}$
      example: adr_78de60204f574a64be88ba9bd94a049f
    InlineRecipientRequest:
      type: object
      additionalProperties: false
      required:
        - phone_number
        - address
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        phone_number:
          type: string
          pattern: ^\+[1-9][0-9]{7,14}$
        address:
          $ref: '#/components/schemas/CreateAddressRequest'
    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
    DeliveryPaymentRequest:
      oneOf:
        - $ref: '#/components/schemas/CODPaymentRequest'
        - $ref: '#/components/schemas/NonCODPaymentRequest'
      discriminator:
        propertyName: type
    VehicleType:
      type: string
      enum:
        - bike
        - minivan
      example: bike
    SuccessEnvelopeDelivery:
      type: object
      additionalProperties: false
      required:
        - success
        - statusCode
        - message
        - data
      properties:
        success:
          type: boolean
          const: true
        statusCode:
          type: integer
          enum:
            - 200
            - 201
        message:
          type: string
        data:
          $ref: '#/components/schemas/Delivery'
    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'
    CreateAddressRequest:
      type: object
      additionalProperties: false
      required:
        - address
        - latitude
        - longitude
      properties:
        label:
          type: string
          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
        municipality:
          type: string
          maxLength: 128
        delivery_notes:
          type: string
          maxLength: 500
    CODPaymentRequest:
      type: object
      additionalProperties: false
      required:
        - type
        - goods_value
      properties:
        type:
          type: string
          const: cod
        goods_value:
          type: number
          format: double
          exclusiveMinimum: 0
    NonCODPaymentRequest:
      type: object
      additionalProperties: false
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - delivery_only
            - client_billed
    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
    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
    DeliveryStatus:
      type: string
      enum:
        - booked
        - assigned
        - picked_up
        - in_transit
        - delivered
        - failed
        - cancelled
        - outsourced
      example: in_transit
    DeliveryRecipient:
      type: object
      additionalProperties: false
      required:
        - id
        - phone_number
      properties:
        id:
          $ref: '#/components/schemas/RecipientID'
        name:
          type:
            - string
            - 'null'
        phone_number:
          type: string
    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.
  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
    IdempotentReplayed:
      description: >-
        Present and `true` when the response was replayed from an earlier
        completed request.
      schema:
        type: boolean
      example: true
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        minimum: 1
      example: 30
  responses:
    IdempotencyKeyRequired:
      description: A required `Idempotency-Key` header was not supplied.
      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: 400
            message: Idempotency-Key is required
            error:
              code: IDEMPOTENCY_KEY_REQUIRED
    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
    DeliveryDependencyNotFound:
      description: Referenced recipient or address was not found.
      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: 404
            message: Recipient address not found
            error:
              code: RECIPIENT_ADDRESS_NOT_FOUND
    DeliveryConflict:
      description: External ID, idempotency, or recipient-shape conflict.
      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'
          examples:
            externalID:
              value:
                success: false
                statusCode: 409
                message: External ID is already in use
                error:
                  code: EXTERNAL_ID_CONFLICT
            recipientShape:
              value:
                success: false
                statusCode: 409
                message: Choose either recipient IDs or an inline recipient
                error:
                  code: RECIPIENT_SHAPE_CONFLICT
            idempotency:
              value:
                success: false
                statusCode: 409
                message: Idempotency key was already used with another request
                error:
                  code: IDEMPOTENCY_CONFLICT
    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.

````