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

> Creates a locker-to-locker shipment. This endpoint requires a secret partner key. The deposit PIN is returned only in this response.



## OpenAPI

````yaml /openapi.json post /api/partner/v1/shipments
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/partner/v1/shipments:
    post:
      tags:
        - Shipments
      summary: Create a shipment
      description: >-
        Creates a locker-to-locker shipment. This endpoint requires a secret
        partner key. The deposit PIN is returned only in this response.
      operationId: createShipment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateShipmentRequest'
            example:
              external_reference: ORDER-1001
              recipient_name: Jane Mwangi
              recipient_phone: '+254712345678'
              origin_city: Nairobi
              destination_city: Mombasa
              weight_tier: light
              starts_at: '2026-07-05'
              ends_at: '2026-07-08'
      responses:
        '201':
          description: Shipment created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedShipment'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: No lockers are available for the requested route and dates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JSONError'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - partnerKey: []
components:
  schemas:
    CreateShipmentRequest:
      type: object
      properties:
        external_reference:
          type: string
          description: Your order or fulfillment ID.
        recipient_name:
          type: string
        recipient_phone:
          type: string
          example: '+254712345678'
        origin_city:
          type: string
          example: Nairobi
        destination_city:
          type: string
          example: Mombasa
        weight_tier:
          type: string
          enum:
            - light
            - medium
            - heavy
        starts_at:
          type: string
          format: date
        ends_at:
          type: string
          format: date
      required:
        - external_reference
        - recipient_name
        - recipient_phone
        - origin_city
        - destination_city
        - weight_tier
        - starts_at
        - ends_at
    CreatedShipment:
      allOf:
        - $ref: '#/components/schemas/Shipment'
        - type: object
          properties:
            deposit_pin:
              type: string
              pattern: ^[0-9]{6}$
              description: One-time deposit PIN. Store it when creating the shipment.
            deposit_whatsapp_link:
              type: string
              format: uri
            collection_whatsapp_link:
              type: string
              format: uri
          required:
            - deposit_pin
            - deposit_whatsapp_link
            - collection_whatsapp_link
    JSONError:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
      required:
        - error
        - message
    Shipment:
      type: object
      properties:
        id:
          type: string
        tracking_token:
          type: string
        tracking_url:
          type: string
          format: uri
        status:
          type: string
        origin_locker:
          $ref: '#/components/schemas/Locker'
        destination_locker:
          $ref: '#/components/schemas/Locker'
        fee_breakdown:
          $ref: '#/components/schemas/FeeBreakdown'
      required:
        - id
        - tracking_token
        - tracking_url
        - status
        - origin_locker
        - destination_locker
        - fee_breakdown
    Locker:
      type: object
      properties:
        name:
          type: string
        city:
          type: string
        address:
          type: string
      required:
        - name
        - city
        - address
    FeeBreakdown:
      type: object
      properties:
        origin_locker_fee_kes:
          type: integer
          format: int64
        destination_locker_fee_kes:
          type: integer
          format: int64
        transit_rider_fee_kes:
          type: integer
          format: int64
        platform_fee_kes:
          type: integer
          format: int64
        total_kes:
          type: integer
          format: int64
      required:
        - origin_locker_fee_kes
        - destination_locker_fee_kes
        - transit_rider_fee_kes
        - platform_fee_kes
  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
    Forbidden:
      description: The credential is not authorized for this operation.
      content:
        text/plain:
          schema:
            type: string
    ServerError:
      description: UrbnBox could not complete the request.
      content:
        text/plain:
          schema:
            type: string
  securitySchemes:
    partnerKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Partner key. Shipment creation requires a secret key.

````

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