Custom Third Party Delivery Documentation

This guide helps you integrate your third party delivery provider with our system using our Custom Third Party Delivery setup. We support:

🔐 Step 1: Setup & Authentication

To integrate with our system, you need to provide:

Key	Description
url	Base URL of your third party delivery
auth_token	Token used for authentication

You’ll set these values in the Admin Panel while configuring your third party delivery.

📌 Note:

The auth_token is used as a Bearer Token in:

The Authorization header during delivery creation.

🧾 Step 2: Creating a Delivery

We’ll call your url with the following request:

▶️ Sample Request

We will send this payload to your system:

{
    "order_id": "116305",
    "merchant_id": "62b1c315f54672795f038de2",
    "order_comment": null,
    "delivery_instructions": null,
    "items": [
        {
            "name": "Chair AR",
            "quantity": 1
        }
    ],
    "pickup": {
        "pickup_timestamp": "2025-07-22 16:41:54",
        "name": "Buck's cafe",
        "contact": "+19056364601",
        "location": {
            "type": "Point",
            "coordinates": [
                -79.5370341,
                43.8287327
            ]
        },
        "address": {
            "full_address": "3175 Rutherford Rd",
            "country_code": "CA"
        },
        "payment": {
            "amount": 377,
            "currency_code": "USD"
        }
    },
    "drop": {
        "drop_timestamp": "2025-07-22 17:26:54",
        "name": "Farhan",
        "contact": "+919651861130",
        "location": {
            "type": "Point",
            "coordinates": [
                80.9796823,
                26.8828811
            ]
        },
        "address": {
            "full_address": "12, Indira Nagar Main Rd, Sector 23, Liberty Colony Park, Sarvodaya Nagar, Indira Nagar, Lucknow, Uttar Pradesh 226022, India",
            "building": "58",
            "area": null,
            "landmark": null,
            "city": "Lucknow",
            "country_code": "IN"
        },
        "payment": {
            "amount": 377,
            "currency_code": "USD"
        }
    },
    "agent_tip_earning": null,
    "is_pickup_proof_required": false,
    "is_delivery_proof_required": false,
    "scheduled_at": null
}

🔐 Headers

Authorization: Bearer your_auth_token
Content-Type: application/json

Your system should return the following expected response

✅ Expected Response

{
  "delivery_id": "xyz",
  "delivery_status": "pending",
  "tracking_url": "https://yourthirdpartydelivery.com/track/xyz"
}

🔔 Step 3: Sending Webhooks (Required)

Once the delivery status updated (picked, completed, cancelled), your system must notify us via webhook.

📬 Webhook URL

Your unique webhook URL is auto-generated and visible in the Admin Panel. It looks like:

https://delivery.apps.hyperzod.dev/api/v1/1003/webhook/order/customdelivery

📦 Webhook Payload

Send a POST request to the webhook URL with the following structure:

{
  "delivery_id": "xyz",
  "delivery_status": "completed",       // completed / cancelled / picked
}

📘 delivery_status Values

Value	Description
completed	Delivery has been completed
cancelled	Delivery has been cancelled
picked	Delivery has been picked

✅ Make sure your webhook server handles retries in case of temporary failure.