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

# Create a delivery order

> Creates a delivery or pickup order for products in the vendor's UrbnBox catalogue and reserves their stock. When `external_reference` matches an existing order, that order is returned instead of a new one (still `201`).



## OpenAPI

````yaml /openapi.json post /api/vendor/v1/orders
openapi: 3.1.0
info:
  title: UrbnBox integration API
  version: 1.0.0
  description: >-
    Create and track delivery orders, send parcels between pickup points, and
    connect Shopify.
servers:
  - url: https://portal.urbnbox.io
    description: UrbnBox production and test-key server
security: []
tags:
  - name: Shipments
    description: Quote, create, and retrieve pickup-point shipments.
  - name: Checkout sessions
    description: Hold lockers for partner checkout sessions.
  - name: Public bookings
    description: Create browser-based locker bookings.
  - name: Store discovery
    description: Find active UrbnBox stores.
  - name: Shopify
    description: Callbacks called by Shopify.
  - name: Vendor API
    description: >-
      Vendor-authenticated endpoints for delivery orders, pickup-point shipments
      and webhooks. All require an X-API-Key header with a vendor key.
paths:
  /api/vendor/v1/orders:
    post:
      tags:
        - Vendor API
      summary: Create a delivery order
      description: >-
        Creates a delivery or pickup order for products in the vendor's UrbnBox
        catalogue and reserves their stock. When `external_reference` matches an
        existing order, that order is returned instead of a new one (still
        `201`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderInput'
      responses:
        '201':
          description: >-
            Order created, or the existing order with the same
            external_reference
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VendorOrder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CreateOrderInput:
      type: object
      required:
        - client_name
        - client_phone
        - items
      properties:
        external_reference:
          type: string
          description: Your order ID. A repeat value returns the existing order
        client_name:
          type: string
          description: Customer's full name
        client_phone:
          type: string
          description: Customer's WhatsApp number
        fulfillment_type:
          type: string
          enum:
            - delivery
            - scheduled_delivery
            - self_pickup
            - scheduled_pickup
          default: delivery
        address:
          type: string
          description: Delivery address. Required for delivery and scheduled_delivery
        client_lat:
          type: number
          description: Delivery latitude. When omitted, the address is geocoded
        client_lng:
          type: number
          description: Delivery longitude
        scheduled_at:
          type: string
          format: date-time
          description: Required for scheduled_delivery and scheduled_pickup
        pickup_name:
          type: string
          description: >-
            Who collects the order. Required for self_pickup and
            scheduled_pickup
        pickup_phone:
          type: string
          description: Collector's phone. Required for self_pickup and scheduled_pickup
        items:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - product_id
              - quantity
            properties:
              product_id:
                type: string
                description: An active product in your UrbnBox catalogue
              quantity:
                type: integer
                minimum: 1
      example:
        external_reference: SHOP-ORDER-1001
        client_name: Jane Mwangi
        client_phone: '+254712345678'
        fulfillment_type: delivery
        address: Kenyatta Avenue, Nairobi
        items:
          - product_id: PRODUCT_ID
            quantity: 2
    VendorOrder:
      type: object
      description: Order fields are returned with capitalised names.
      properties:
        ID:
          type: string
        Status:
          type: string
          enum:
            - draft
            - confirmed
            - assigned
            - packing
            - dispatched
            - delivered
            - cancelled
        FulfillmentType:
          type: string
        ClientName:
          type:
            - string
            - 'null'
        ClientPhone:
          type:
            - string
            - 'null'
        Address:
          type:
            - string
            - 'null'
        ClientLat:
          type:
            - number
            - 'null'
        ClientLng:
          type:
            - number
            - 'null'
        ScheduledAt:
          type:
            - string
            - 'null'
          format: date-time
        TotalKES:
          type: integer
          description: Items plus delivery fee, in whole KES
        DeliveryFeeKES:
          type: integer
          description: Whole KES
        PublicToken:
          type: string
        IsCOD:
          type: boolean
        CODAmountKES:
          type:
            - integer
            - 'null'
        CreatedAt:
          type: string
          format: date-time
        UpdatedAt:
          type: string
          format: date-time
  responses:
    BadRequest:
      description: The request body, date, field, or query parameter is invalid.
      content:
        text/plain:
          schema:
            type: string
    Unauthorized:
      description: The credential is missing, invalid, or inactive.
      content:
        text/plain:
          schema:
            type: string
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Vendor API key. Keys begin with the ubx_ prefix and identify vendor
        accounts.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.