Webhook Status Codes

Introduction

Whenever a shipment status changes, AyMakan sends a webhook containing the shipment status and, when applicable, a reason_code.

• status identifies the shipment's current lifecycle stage.
• reason_code provides additional information for statuses such as Not Delivered, Pending, On Hold, Reverse Pickup Incomplete, etc.

Example:

{
    "event": "status_update",
    "reason": "",
    "status": "AY-0004",
    "carrier": "aymakan",
    "tracking": "AY12345678901",
    "reference": "ORD-100254",
    "date_time": "2026-07-23T10:15:32.000000Z",
    "description": "Out for Delivery",
    "reason_description": "",
    "shipping": {
        "tracking_number": "AY12345678901",
        "reference": "ORD-100254",
        "status": "AY-0004",
        "status_label": "Out for Delivery",
        "reason_code": null,
        "reason_en": null,
        "weight": "2.35",
        "pieces": 1,
        "length": null,
        "width": null,
        "height": null,
        "cod_amount": "0.00",
        "payment_method": "Prepaid",
        "pickup_date": "2026-07-22T09:30:00.000000Z",
        "received_at": "2026-07-22T14:10:15.000000Z",
        "delivery_date": null,
        "requested_delivery_date": null,
        "id_customer": 125,
        "customer_name": "Demo Store",
        "is_reverse_pickup": 0,

        "collection_name": "Demo Store Warehouse",
        "collection_email": "[email protected]",
        "collection_city": "Riyadh",
        "collection_address": "King Fahd Road, Riyadh",
        "collection_neighbourhood": "Al Olaya",

        "delivery_name": "John Smith",
        "delivery_email": "[email protected]",
        "delivery_phone": "966500000000",
        "delivery_city": "Riyadh",
        "delivery_country": "SA",
        "delivery_address": "King Abdullah Road, Riyadh",
        "delivery_postcode": "12345",
        "delivery_neighbourhood": "Al Malqa",
        "delivery_description": "Wireless Keyboard x1, Wireless Mouse x1",

        "tracking_info": [
            {
                "status_code": "AY-0004",
                "description": "Shipment is out for its final destination.",
                "description_ar": "الشحنة خارجة للتوصيل للوجهة النهائية",
                "reason_code": null,
                "reason_en": null,
                "reason_ar": null,
                "created_at": "2026-07-23 13:15:32"
            },
            {
                "status_code": "AY-0026",
                "description": "Received at Riyadh Warehouse",
                "description_ar": "تم استلام الشحنة في مستودع الرياض",
                "reason_code": null,
                "reason_en": null,
                "reason_ar": null,
                "created_at": "2026-07-22 17:10:15"
            },
            {
                "status_code": "AY-0003",
                "description": "Shipment is received at hub",
                "description_ar": "تم استلام الشحنة في مركز التوزيع",
                "reason_code": null,
                "reason_en": null,
                "reason_ar": null,
                "created_at": "2026-07-22 17:10:15"
            },
            {
                "status_code": "AY-0002",
                "description": "Shipment was collected from collection point",
                "description_ar": "تم استلام الشحنة من نقطة التجميع",
                "reason_code": null,
                "reason_en": null,
                "reason_ar": null,
                "created_at": "2026-07-22 12:30:00"
            },
            {
                "status_code": "AY-0001",
                "description": "Shipment is created at collection point",
                "description_ar": "تم إنشاء بوليصة الشحنة",
                "reason_code": null,
                "reason_en": null,
                "reason_ar": null,
                "created_at": "2026-07-22 10:45:20"
            }
        ]
    }
}

Shipment Status Codes

Reason Codes

Reason codes are included only when additional context is required.

Not Delivered (AY-0006)

Pending (AY-0032)

Reverse Pickup Incomplete (AY-0038)

Reverse Pickup Complete (AY-0042)

Reverse Pickup Partially Complete (AY-0046)

On Hold (AY-0050)