---
title: Custom Third Party Delivery Documentation
slug: custom-third-party-delivery-documentation
docTags: 
createdAt: 2026-08-26T12:11:56.709Z
---

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:
  1. 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: 

```json
{
    "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

```php
Authorization: Bearer your_auth_token
Content-Type: application/json
```

Your system should return the following expected response

### ✅ Expected Response

```json
{
  "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:

```php
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: 

```json
{
  "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.