{
  "info": {
    "_postman_id": "d6f0a1c2-3b4d-4e5f-8a9b-dropoff-v1-0000",
    "name": "DropOff Couriers Integration API v1",
    "description": "Create and track shipments. Set the collection variables `base_url` and `api_key` (use a dk_test_ key to start — test shipments are isolated and never bill or SMS). Auth is a collection-level Bearer token; every request inherits it.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_key}}", "type": "string" } ] },
  "variable": [
    { "key": "base_url", "value": "https://app.dropoffcouriers.com/api/v1/business", "type": "string" },
    { "key": "api_key", "value": "dk_test_REPLACE_WITH_YOUR_TEST_KEY", "type": "string" },
    { "key": "shipment_id", "value": "", "type": "string" }
  ],
  "item": [
    {
      "name": "Shipments",
      "item": [
        {
          "name": "Create shipment",
          "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [
            "var b = pm.response.json();",
            "if (b && b.data && b.data.id) { pm.collectionVariables.set('shipment_id', b.data.id); }",
            "pm.test('status is 200 or 201', function () { pm.expect([200,201]).to.include(pm.response.code); });"
          ] } } ],
          "request": {
            "method": "POST",
            "header": [
              { "key": "Accept", "value": "application/json" },
              { "key": "Content-Type", "value": "application/json" },
              { "key": "Idempotency-Key", "value": "{{$guid}}", "description": "Optional: safe retries." }
            ],
            "body": { "mode": "raw", "raw": "{\n  \"receiver_name\": \"Jane Receiver\",\n  \"receiver_phone_number\": \"0772123456\",\n  \"receiver_address\": \"Plot 5, Ntinda, Kampala\",\n  \"service_type\": \"standard\",\n  \"payment_type\": \"sender_pays\",\n  \"item_name\": \"Phone case\",\n  \"external_reference\": \"ORD-{{$timestamp}}\"\n}" },
            "url": { "raw": "{{base_url}}/shipments", "host": ["{{base_url}}"], "path": ["shipments"] },
            "description": "Create a parcel. Needs shipments:write. A test key persists a TEST parcel (meta.test:true) with no invoice/SMS."
          }
        },
        {
          "name": "List shipments",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": { "raw": "{{base_url}}/shipments?status=created&page=1", "host": ["{{base_url}}"], "path": ["shipments"], "query": [ { "key": "status", "value": "created" }, { "key": "service_type", "value": "standard", "disabled": true }, { "key": "external_reference", "value": "ORD-5001", "disabled": true }, { "key": "page", "value": "1" } ] }
          }
        },
        {
          "name": "Look up shipment",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": { "raw": "{{base_url}}/shipments/lookup?external_reference=ORD-5001", "host": ["{{base_url}}"], "path": ["shipments", "lookup"], "query": [ { "key": "external_reference", "value": "ORD-5001" }, { "key": "tracking_number", "value": "#DOC-0002807921284", "disabled": true } ] }
          }
        },
        {
          "name": "Get shipment",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": { "raw": "{{base_url}}/shipments/{{shipment_id}}", "host": ["{{base_url}}"], "path": ["shipments", "{{shipment_id}}"] }
          }
        },
        {
          "name": "Tracking timeline",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": { "raw": "{{base_url}}/shipments/{{shipment_id}}/tracking", "host": ["{{base_url}}"], "path": ["shipments", "{{shipment_id}}", "tracking"] },
            "description": "Needs tracking:read. Event times are UTC ISO-8601."
          }
        },
        {
          "name": "Cancel shipment",
          "request": {
            "method": "POST",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": { "raw": "{{base_url}}/shipments/{{shipment_id}}/cancel", "host": ["{{base_url}}"], "path": ["shipments", "{{shipment_id}}", "cancel"] },
            "description": "Only while status is 'created'; otherwise 409 cannot_cancel."
          }
        },
        {
          "name": "Waybill (PDF)",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/pdf" } ],
            "url": { "raw": "{{base_url}}/shipments/{{shipment_id}}/waybill", "host": ["{{base_url}}"], "path": ["shipments", "{{shipment_id}}", "waybill"] }
          }
        }
      ]
    },
    {
      "name": "Pricing & Zones",
      "item": [
        {
          "name": "Quote a fee",
          "request": {
            "method": "POST",
            "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ],
            "body": { "mode": "raw", "raw": "{\n  \"service_type\": \"express\"\n}" },
            "url": { "raw": "{{base_url}}/shipments/quote", "host": ["{{base_url}}"], "path": ["shipments", "quote"] }
          }
        },
        {
          "name": "List zones",
          "request": {
            "method": "GET",
            "header": [ { "key": "Accept", "value": "application/json" } ],
            "url": { "raw": "{{base_url}}/zones", "host": ["{{base_url}}"], "path": ["zones"] }
          }
        }
      ]
    },
    {
      "name": "Money",
      "item": [
        { "name": "COD ledger", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/cod-ledger", "host": ["{{base_url}}"], "path": ["cod-ledger"] } } },
        { "name": "Settlements", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/settlements", "host": ["{{base_url}}"], "path": ["settlements"] }, "description": "statement_available is a boolean; the PDF downloads from the dashboard, not the API." } }
      ]
    },
    {
      "name": "Returns",
      "item": [
        { "name": "List returns", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/returns", "host": ["{{base_url}}"], "path": ["returns"] } } },
        { "name": "Get return", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{base_url}}/returns/1", "host": ["{{base_url}}"], "path": ["returns", "1"] } } }
      ]
    },
    {
      "name": "Test mode",
      "item": [
        {
          "name": "Advance a test shipment",
          "request": {
            "method": "POST",
            "header": [ { "key": "Accept", "value": "application/json" }, { "key": "Content-Type", "value": "application/json" } ],
            "body": { "mode": "raw", "raw": "{}" },
            "url": { "raw": "{{base_url}}/shipments/{{shipment_id}}/test/advance", "host": ["{{base_url}}"], "path": ["shipments", "{{shipment_id}}", "test", "advance"] },
            "description": "TEST KEY ONLY. Advances the test shipment one step (or send {\"to\":\"delivered\"}) to drive webhooks. A live key gets 403 test_only."
          }
        }
      ]
    }
  ]
}