v1
Powered by

# Orders

# Introduction

Using our order management API, you can seamlessly dispatch orders to Armada drivers and access key details, including fees, delivery estimates, tracking links, and more. Our service is available in Kuwait, Bahrain, and Saudi Arabia (KSA).

# Order Schema

Place an order via HTTP POST at:

POST
https://api.armadadelivery.com/v1/deliveries

The body of the request should be in JSON format and include the following parameters:

  • reference: Order reference ID String - Required
  • origin_format: Format type of the origin, can be "branch_format" or "location_format" String - Required

  • origin: Contains information about the origin, depends on origin_format Object - Required

    • branch_id: Branch ID (24-character hexadecimal) String - Required
    • contact_name: Contact name String - Required
    • contact_phone: Contact phone String - Required
    • latitude: Latitude coordinate Number - Required
    • longitude: Longitude coordinate Number - Required
    • first_line: Address first line (good for drivers to locate the destination faster) String - Optional
    • floor: Floor number String - Optional
    • apartment: Apartment number String - Optional
  • destination_format: Format type of the destination, can be "location_format", "kuwait_format", "bahrain_format", "ksa_format", "ksa_short_format" String - Required

  • destination: Contains the customer's destination information, depends on destination_format Object - Required

    • contact_name: Customer name String - Required
    • contact_phone: Customer phone String - Required
    • latitude: Latitude coordinate Number - Required
    • longitude: Longitude coordinate Number - Required
    • first_line: Address first line (good for drivers to locate the destination faster) String - Optional
    • floor: Floor number String - Optional
    • apartment: Apartment number String - Optional
    • instructions: Delivery instructions String - Optional
    • contact_name: Customer name String - Required
    • contact_phone: Customer phone String - Required
    • area: Area name String - Required
    • block: Block number String - Required
    • street: Street name/number String - Required
    • building: Building number String - Required
    • floor: Floor number String - Optional
    • apartment: Apartment number String - Optional
    • instructions: Delivery instructions String - Optional
    • contact_name: Customer name String - Required
    • contact_phone: Customer phone String - Required
    • area: Area name String - Required
    • block: Block number String - Required
    • street: Street name/number String - Required
    • building: Building number String - Required
    • floor: Floor number String - Optional
    • apartment: Apartment number String - Optional
    • instructions: Delivery instructions String - Optional
    • contact_name: Customer name String - Required
    • contact_phone: Customer phone String - Required
    • city: City name String - Required
    • street: Street name String - Required
    • district: District name String - Required
    • building: Building number String - Required
    • floor: Floor number String - Optional
    • apartment: Apartment number String - Optional
    • instructions: Delivery instructions String - Optional
    • contact_name: Customer name String - Required
    • contact_phone: Customer phone String - Required
    • short_address: Short address code String - Required
    • instructions: Delivery instructions String - Optional
  • payment: Payment details Object - Required
    • amount: Total amount for the order Number - Required
    • type: Payment type, can be "paid" or "cash" String - Required
  • scheduled_date: Desired start time for the order ISO Date - Optional
    • The specified time must be later than the current time. If the time is within 30 minutes, the order will be processed immediately.

# Create Order Example

You can now select the appropriate destination format based on your location. Choose location format for universal deliveries or country-specific formats based on your region.

curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "A97UI5R",
  "origin_format": "branch_format",
  "origin": {
    "branch_id": "682473e10313f6003826e5d7"
  },
  "destination_format": "location_format",
  "destination": {
    "contact_name": "Nadeen",
    "contact_phone": "+212680980068",
    "first_line": "Al-Dohah Port, Kuwait",
    "latitude": 29.355,
    "longitude": 47.8046,
    "instructions": "Leave the order by the front door and ring the bell"
  },
  "payment": {
    "amount": 3.00,
    "type": "cash"
  }
}'
 
curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "ORD-654789123",
  "origin_format": "branch_format",
  "origin": {
    "branch_id": "682473e10313f6003826e5d7"
  },
  "destination_format": "kuwait_format",
  "destination": {
    "contact_name": "Fatima Ahmed",
    "contact_phone": "+96512340003",
    "area": "Hawally",
    "block": "5",
    "street": "15",
    "building": "42",
    "floor": "2",
    "apartment": "12A",
    "instructions": "Put it in front of the door and ring the bell"
  },
  "payment": {
    "amount": 3.00,
    "type": "cash"
  }
}'
 
curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "ORD-9876BHR",
  "origin_format": "branch_format",
  "origin": {
    "branch_id": "682473e10313f6003826e5d7"
  },
  "destination_format": "bahrain_format",
  "destination": {
    "contact_name": "Rajae",
    "contact_phone": "+97333985678",
    "area": "Adliya",
    "block": "338",
    "street": "Road 2819",
    "building": "150",
    "floor": "2",
    "apartment": "12A",
    "instructions": "Leave the order by the front door and ring the bell"
  },
  "payment": {
    "amount": 10.00,
    "type": "paid"
  }
}'
 
curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "ORD-1234KSA",
  "origin_format": "branch_format",
  "origin": {
    "branch_id": "682473e10313f6003826e5d7"
  },
  "destination_format": "ksa_format",
  "destination": {
    "contact_name": "Amal",
    "contact_phone": "+966501234567",
    "city": "Al Olaya",
    "street": "King Fahd Road",
    "district": "Al Olaya District",
    "building": "456",
    "floor": "3",
    "apartment": "8B",
    "instructions": "Please leave the package at the reception."
  },
  "payment": {
    "amount": 15.00,
    "type": "cash"
  }
}'
 
curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "ORD-5678KSA",
  "origin_format": "branch_format",
  "origin": {
    "branch_id": "682473e10313f6003826e5d7"
  },
  "destination_format": "ksa_short_format",
  "destination": {
    "contact_name": "Bashir",
    "contact_phone": "+966501234567",
    "short_address": "RFNB4718",
    "instructions": "Leave the package with the security guard."
  },
  "payment": {
    "amount": 20.00,
    "type": "paid"
  }
}'
 
curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reference": "ORD-LOC-9999",
  "origin_format": "location_format",
  "origin": {
    "contact_name": "Ahmed Ali",
    "contact_phone": "+212680985566",
    "latitude": 29.3140728,
    "longitude": 48.021550,
    "floor": "2",
    "apartment": "5"
  },
  "destination_format": "location_format",
  "destination": {
    "contact_name": "Sara Ahmed",
    "contact_phone": "+965555123456",
    "first_line": "456 Market Street",
    "latitude": 29.355069903470575,
    "longitude": 47.80469652165224,
    "floor": "4",
    "apartment": "15A",
    "instructions": "Call upon arrival"
  },
  "payment": {
    "amount": 12.00,
    "type": "cash"
  }
}'

# Response Schema

After successful completion, our API will provide a JSON response containing the following parameters:

  • code: Delivery ID within Armada String
  • status: Status of the order, one of: pending, dispatched, waiting_pack, en_route, completed, canceled, failed String
  • amount: Order amount set by the merchant Number
  • created_at: Date of delivery creation ISO Date
  • currency: Currency used for this delivery String
  • delivery_fee: Cost of the delivery Number
  • customer: Customer information Object
    • name: Customer name String
    • phone: Customer phone number String
    • address: Customer address generated by Armada based on platform data String
    • latitude: Latitude of the customer location Number
    • longitude: Longitude of the customer location Number
  • driver: Driver data (fields can be empty/null depending on driver availability) Object
    • name: Driver name String
    • phone: Driver phone String
    • latitude: Driver latitude coordinate Number/Null
    • longitude: Driver longitude coordinate Number/Null
  • logistics: Logistics information Object
    • estimated_distance: Estimated distance from pickup to customer destination in meters Number
    • estimated_duration: Estimated duration from pickup to customer destination in seconds Number
    • tracking_url: Link to a public page showing live delivery progress (share it with your client ) URL
    • pickup_qr_url: Link to the QR code for the driver to scan if not performed within the merchant dashboard URL

# Response Example

JSON
{
  "code": "89CC2FE26D",
  "status": "pending",
  "amount": 3,
  "created_at": "2026-01-05T15:40:44.458Z",
  "currency": "KWD",
  "delivery_fee": 14.75,
  "customer": {
    "name": "Jean",
    "phone": "212680980068",
    "address": "Mina Doha, Block 1, Doha Road",
    "latitude": 29.355,
    "longitude": 47.8046
  },
  "driver": {
    "name": "",
    "phone": "",
    "latitude": null,
    "longitude": null
  },
  "logistics": {
    "estimated_distance": 96523,
    "estimated_duration": 5615.614600000001,
    "tracking_url": "https://sandbox.tracking.armadadelivery.com/244ed75c-621f-4963-ae5c-76d5d9ca2c2e",
    "pickup_qr_url": "https://armada-sand.s3.eu-central-1.amazonaws.com/qrCodes/2545be5db4269c9c0cc4160b4fb46b60.svg"
  }
}

# Get Order

Get order details via HTTP GET at:

GET
https://api.armadadelivery.com/v1/deliveries/:code
  • code: Code returned by order creation String - Required

# Request Example

(e.g code = 89CC2FE26D)

cURL
curl --location --request GET 'https://api.armadadelivery.com/v1/deliveries/89CC2FE26D' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]'

# Response Example

For more details see Response Schema of the previous section.

JSON
{
  "code": "89CC2FE26D",
  "status": "pending",
  "amount": 3,
  "created_at": "2026-01-05T15:40:44.458Z",
  "currency": "KWD",
  "delivery_fee": 14.75,
  "customer": {
    "name": "Jean",
    "phone": "212680980068",
    "address": "Mina Doha, Block 1, Doha Road",
    "latitude": 29.355,
    "longitude": 47.8046
  },
  "driver": {
    "name": "",
    "phone": "",
    "latitude": null,
    "longitude": null
  },
  "logistics": {
    "estimated_distance": 96523,
    "estimated_duration": 5615.614600000001,
    "tracking_url": "https://sandbox.tracking.armadadelivery.com/244ed75c-621f-4963-ae5c-76d5d9ca2c2e",
    "pickup_qr_url": "https://armada-sand.s3.eu-central-1.amazonaws.com/qrCodes/2545be5db4269c9c0cc4160b4fb46b60.svg"
  }
}

# Cancel Order

To cancel an order, you will need to make an HTTP POST request to the following endpoint:

POST
https://api.armadadelivery.com/v1/deliveries/:code/cancel
  • code: Code returned by order creation String - Required

# Request Example

(e.g code = 89CC2FE26D)

cURL
curl --location --request POST 'https://api.armadadelivery.com/v1/deliveries/89CC2FE26D/cancel' \
--header 'Armada-Access-Token: [YOUR ACCESS TOKEN]' \
--data ''

# Response Example

For more details see Response Schema of the previous section.

JSON
{
  "code": "89CC2FE26D",
  "status": "canceled",
  "amount": 3,
  "created_at": "2026-01-05T15:40:44.458Z",
  "currency": "KWD",
  "delivery_fee": 14.75,
  "customer": {
    "name": "Jean",
    "phone": "212680980068",
    "address": "Mina Doha, Block 1, Doha Road",
    "latitude": 29.355,
    "longitude": 47.8046
  },
  "driver": {
    "name": "",
    "phone": "",
    "latitude": null,
    "longitude": null
  },
  "logistics": {
    "estimated_distance": 96523,
    "estimated_duration": 5615.614600000001,
    "tracking_url": "https://sandbox.tracking.armadadelivery.com/244ed75c-621f-4963-ae5c-76d5d9ca2c2e",
    "pickup_qr_url": "https://armada-sand.s3.eu-central-1.amazonaws.com/qrCodes/2545be5db4269c9c0cc4160b4fb46b60.svg"
  }
}

© Copyright 2016 - 2026. All rights reserved.