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

# Download shipments CSV template

> Returns `urbnbox-shipments-template.csv` — a pre-formatted CSV with correct headers and two example rows. No authentication required. Fill it in, then POST to `/api/vendor/v1/shipments/import-csv`.

**Column order (do not change):**

| # | Column | Required | Notes |
|---|--------|----------|-------|
| 1 | `external_reference` | Yes | Your shipment ID — used for idempotency |
| 2 | `recipient_name` | Yes | Full name of recipient |
| 3 | `recipient_phone` | Yes | Kenyan number (`07xx` or `+254xx`) |
| 4 | `origin_city` | Yes | e.g. `Nairobi` |
| 5 | `destination_city` | Yes | e.g. `Mombasa` |
| 6 | `weight_tier` | Yes | `small`, `medium`, or `large` |

**Weight tiers:** `small` = up to 5 kg · `medium` = 5–15 kg · `large` = 15–30 kg

**Example file contents:**

```csv
external_reference,recipient_name,recipient_phone,origin_city,destination_city,weight_tier
SHIP-001,Alice Mwangi,0712345678,Nairobi,Mombasa,small
SHIP-002,Bob Otieno,0798765432,Kisumu,Nairobi,medium
```



## OpenAPI

````yaml /openapi.json get /api/vendor/v1/shipments/csv-template
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/shipments/csv-template:
    get:
      tags:
        - Vendor API
      summary: Download shipments CSV template
      description: >-
        Returns `urbnbox-shipments-template.csv` — a pre-formatted CSV with
        correct headers and two example rows. No authentication required. Fill
        it in, then POST to `/api/vendor/v1/shipments/import-csv`.


        **Column order (do not change):**


        | # | Column | Required | Notes |

        |---|--------|----------|-------|

        | 1 | `external_reference` | Yes | Your shipment ID — used for
        idempotency |

        | 2 | `recipient_name` | Yes | Full name of recipient |

        | 3 | `recipient_phone` | Yes | Kenyan number (`07xx` or `+254xx`) |

        | 4 | `origin_city` | Yes | e.g. `Nairobi` |

        | 5 | `destination_city` | Yes | e.g. `Mombasa` |

        | 6 | `weight_tier` | Yes | `small`, `medium`, or `large` |


        **Weight tiers:** `small` = up to 5 kg · `medium` = 5–15 kg · `large` =
        15–30 kg


        **Example file contents:**


        ```csv

        external_reference,recipient_name,recipient_phone,origin_city,destination_city,weight_tier

        SHIP-001,Alice Mwangi,0712345678,Nairobi,Mombasa,small

        SHIP-002,Bob Otieno,0798765432,Kisumu,Nairobi,medium

        ```
      responses:
        '200':
          description: CSV template file — save and open in Excel or Google Sheets
          content:
            text/csv:
              schema:
                type: string
              example: >-
                external_reference,recipient_name,recipient_phone,origin_city,destination_city,weight_tier

                SHIP-001,Alice Mwangi,0712345678,Nairobi,Mombasa,small

                SHIP-002,Bob Otieno,0798765432,Kisumu,Nairobi,medium
          headers:
            Content-Disposition:
              schema:
                type: string
              example: attachment; filename="urbnbox-shipments-template.csv"
      x-codeSamples:
        - lang: Shell
          label: curl
          source: >-
            curl -O -J
            https://api.urbnbox.com/api/vendor/v1/shipments/csv-template
        - lang: Python
          label: Python
          source: >-
            import requests


            resp =
            requests.get('https://api.urbnbox.com/api/vendor/v1/shipments/csv-template')

            with open('urbnbox-shipments-template.csv', 'wb') as f:
                f.write(resp.content)
            print('Template saved.')
        - lang: JavaScript
          label: Node.js
          source: >-
            const fs = require('fs');

            const https = require('https');


            https.get('https://api.urbnbox.com/api/vendor/v1/shipments/csv-template',
            (res) => {
              res.pipe(fs.createWriteStream('urbnbox-shipments-template.csv'));
              res.on('end', () => console.log('Template saved.'));
            });

````

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