# Order Management

# Introduction

With our order management API, you can easily send orders to Armada drivers and receive details such as fees, estimates, tracking URLs, and more. Our service currently covers Kuwait, Bahrain, and Saudi Arabia (KSA).

# Note

To test your work on the sandbox or staging API, please refer to the Environments section for detailed instructions.

# Order Creation

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

https://staging.api.armadadelivery.com/v0/deliveries

https://api.armadadelivery.com/v0/deliveries

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

platformName: Refer to the delivery platform String - Required
platformData: Contains the data required to create the delivery Object - Required
- orderId: Order ID in your platform String - Required
- name: Customer name String - Required
- phone: Customer phone String - Required
- location: Customer geo location address Object - Required if full address missing
  - latitude: Float
  - longitude: Float
- area: Critical address component, must match our area spellings String - Required for Kuwait & Bahrain if location missing
- block: One of the address components String - Required for Kuwait & Bahrain if location missing
- street: One of the address components String - Required for Kuwait & Bahrain if location missing
- buildingNumber: One of the address components String - Required for Kuwait & Bahrain if location missing
- floor: One of the address components String - Optional
- apartment: One of the address components String - Optional
- instructions: Extra instructions for the driver String - Optional
- shortAddress: Short address version of the national address by SPL String - Required for KSA if location missing
- firstLine: Full normal address String - Required for KSA if location or shortAddress missing
- amount: Order amount Number - Required if the paymentType is cash
- scheduledAt: Specify the desired start time for the order. This date must be later than the current time. If it's within 30 minutes from the current time, the order will be processed immediately ISODATE - Optional
- paymentType: Payment type, Enum: should be paid or cash String - Required

For the security, we recommend including a security key in the headers of your order:

order-webhook-key: Webhook key must be between 12-32 characters String - Recommend

When you receive an order update via your webhook, the order-webhook-key will be included in the headers as an Authorization key for security purposes. see webhooks

# Addressing

The addressing varies from one country to another. However, you can deliver your order using a unified method such as location (latitude, longitude). If you prefer to provide a full address, please follow the format for each country.

# Kuwait 🇰🇼 Bahrain 🇧🇭

For Kuwait and Bahrain, We provide two ways in this order: location or area block street buildingNumber.

curl --location --request POST 'https://api.armadadelivery.com/v0/deliveries' \
--header 'Authorization: Key [YOUR API KEY]' \
--header 'order-webhook-key: vE6gH8Rt2L1sK9w' \
--header 'Content-Type: application/json' \
--data-raw '{
    "platformName": "pos",
    "platformData": {
        "orderId": "4AJ9P5",
        "name": "mohamed",
        "phone": "+96551234567",
        "location": {
            "latitude": 29.22536,
            "longitude": 48.07328
        },
        "amount": "5.000",
        "paymentType": "paid"
    }
}'

curl --location --request POST 'https://api.armadadelivery.com/v0/deliveries' \
--header 'Authorization: Key [YOUR API KEY]' \
--header 'order-webhook-key: vE6gH8Rt2L1sK9w' \
--header 'Content-Type: application/json' \
--data-raw '{
    "platformName": "pos",
    "platformData": {
        "orderId": "4AJ9P5",
        "name": "mohamed",
        "phone": "+96551234567",
        "area": "Abdullah Mubarak Al-Sabah",
        "block": "5",
        "street": "St 503",
        "buildingNumber": "123",
        "amount": "5.000",
        "paymentType": "paid"
    }
}'

curl --location --request POST 'https://api.armadadelivery.com/v0/deliveries' \
--header 'Authorization: Key [YOUR API KEY]' \
--header 'order-webhook-key: vE6gH8Rt2L1sK9w' \
--header 'Content-Type: application/json' \
--data-raw '{
    "platformName": "strongCoffee",
    "platformData": {
        "orderId": "7HJ3B2",
        "name": "hajar",
        "phone": "+97333337777",
        "area": "Juffair",
        "block": "342",
        "street": "Al Shabab Avenue",
        "buildingNumber": "123",
        "amount": "12.000",
        "paymentType": "cash"
    }
}'

# Saudi Arabia (KSA) 🇸🇦

For Saudi Arabia, We provide three ways in this order: location or shortAddress or firstLine.

curl --location --request POST 'https://api.armadadelivery.com/v0/deliveries' \
--header 'Authorization: Key [YOUR API KEY]' \
--header 'order-webhook-key: R4nD0mK3y' \
--header 'Content-Type: application/json' \
--data-raw '{
    "platformName": "tryMe",
    "platformData": {
        "orderId": "4dOke36Vdv",
        "name": "Zakaria",
        "phone": "+96656781234",
        "location": {
            "latitude": 24.70923,
            "longitude": 46.68901
        },
        "amount": "17.000",
        "paymentType": "paid"
    }
}'

curl --location --request POST 'https://api.armadadelivery.com/v0/deliveries' \
--header 'Authorization: Key [YOUR API KEY]' \
--header 'order-webhook-key: R4nD0mK3y' \
--header 'Content-Type: application/json' \
--data-raw '{
    "platformName": "tryMe",
    "platformData": {
        "orderId": "4dOke36Vdv",
        "name": "Zakaria",
        "phone": "+96656781234",
        "shortAddress": "RRAA2062",
        "amount": "17.000",
        "paymentType": "paid"
    }
}'

curl --location --request POST 'https://api.armadadelivery.com/v0/deliveries' \
--header 'Authorization: Key [YOUR API KEY]' \
--header 'order-webhook-key: R4nD0mK3y' \
--header 'Content-Type: application/json' \
--data-raw '{
    "platformName": "tryMe",
    "platformData": {
        "orderId": "4dOke36Vdv",
        "name": "Zakaria",
        "phone": "+96656781234",
        "firstLine": "Prince Mamduh Bin Abdulaziz St, As Sulimaniyah, Riyadh 12245, Saudi Arabia",
        "amount": "17.000",
        "paymentType": "paid"
    }
}'

# Response Schema

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

code: Delivery ID within Armada String
deliveryFee: Cost of the delivery Number
amount: Order amount set by the merchant Number
customerAddress: Customer address generated by Armada based on platform data String
customerLocation: Object
- latitude: Latitude of the customer location Float
- longitude: Longitude of the customer location Float
customerName: Customer name String
customerPhone: Customer phone number String
orderStatus: Status of the order. (see webhooks status for more details) String
estimatedDistance: Estimated distance from pickup to customer destination in meters Number
estimatedDuration: Estimated duration from pickup to customer destination in seconds Number
driver: Driver data Object
- name: Driver name String
- phoneNumber: Driver phone String
trackingLink: Link to a public page showing live delivery progress (give it to your client) URL
qrCodeLink: Link to the QR code for the driver to scan if not performed within the merchant dashboard URL
orderCreatedAt: Date of delivery creation ISO DATE
currency: Currency used for this delivery String

# Response Example

{
  "code": "E8E5653A05",
  "deliveryFee": 194.25,
  "amount": 17.5,
  "customerAddress": "Abdullah Mubarak Al-Sabah, Block 5, St 503",
  "customerLocation": {
    "latitude": 29.242885,
    "longitude": 47.894161
  },
  "customerName": "mohamed",
  "customerPhone": "+96551234567",
  "orderStatus": "pending",
  "estimatedDistance": 24857,
  "estimatedDuration": 1772.55,
  "driver": {
    "name": "Yazid",
    "phoneNumber": "+9650000000"
  }
  "trackingLink": "https://tracking.armadadelivery.com/4c04d9b8-c358-4b0e-b81c-846fd840beea",
  "qrCodeLink": "https://armada-prod.s3.eu-central-1.amazonaws.com/qrCodes/a6c8b061036f988334937de367b6e2ae.svg",
  "orderCreatedAt": "2024-02-21T17:18:04.214Z",
  "currency": "KWD"
}

# Get Orders

To fetch an order, you will need to make an HTTP GET request to the following endpoint:

https://staging.api.armadadelivery.com/v0/deliveries/:code

https://api.armadadelivery.com/v0/deliveries/:code

code: Code returned by order creation.

# Request Example

(e.g code = E8E5653A05)

curl --location --request GET 'https://api.armadadelivery.com/v0/deliveries/E8E5653A05' \
--header 'Authorization: Key [YOUR API KEY]'

fetch('https://api.armadadelivery.com/v0/deliveries/E8E5653A05', {
    method: 'GET',
    headers: {
        'Authorization': `Key [YOUR API KEY]`,
    }
})
.then(response => response.json())
.then((data) => console.log(data))
.catch((error) => console.error('Error:', error));

func main() {
    req, err := http.NewRequest("GET", "https://api.armadadelivery.com/v0/deliveries/E8E5653A05", nil)
    if err != nil {
        fmt.Println(err)
    }
    req.Header.Set("Authorization", "Key [YOUR API KEY]")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(body))
}

# Response Schema

For more details see Response Schema and Example of the previous section.

{
  code: String,
  deliveryFee: Number,
  amount: Number,
  customerAddress: String,
  customerLocation: {
    latitude: Number,
    longitude: Number,
  },
  customerName: String,
  customerPhone: String,
  orderStatus: String,
  estimatedDistance: Number,
  estimatedDuration: Number,
  driver: {
    name: String,
    phoneNumber: String,
  },
  trackingLink: String,
  qrCodeLink: String,
  orderCreatedAt: Date,
  currency: String,
}

# Cancel Order

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

https://staging.api.armadadelivery.com/v0/deliveries/:code/cancel

https://api.armadadelivery.com/v0/deliveries/:code/cancel

code: Code returned by order creation.

# Request Example

(e.g code = E8E5653A05)

curl --location --request POST 'https://api.armadadelivery.com/v0/deliveries/E8E5653A05/cancel' \
--header 'Authorization: Key [YOUR API KEY]' \
--data ''

fetch('https://api.armadadelivery.com/v0/deliveries/E8E5653A05/cancel', {
  method: 'POST',
  headers: {
    'Authorization': `Key [YOUR API KEY]`
  },
})
.then(response => response.ok ? console.log('Delivery successfully cancelled') : console.error('Failed to cancel delivery'))
.catch(error => console.error('Error cancelling delivery:', error));

func main() {
	url := "https://api.armadadelivery.com/v0/deliveries/E8E5653A05/cancel"
	apiKey := "[YOUR API KEY]"
    
	req, err := http.NewRequest("POST", url, nil)
	if err != nil {
		fmt.Println("Error creating request:", err)
		return
	}

	req.Header.Set("Authorization", "Key " + apiKey)

	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Error sending request:", err)
		return
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		fmt.Println("Failed to cancel delivery")
		return
	}

	fmt.Println("Delivery successfully cancelled")
}

# Response

Upon successful cancellation, you will receive a 200 status code.
For failures, you will receive a 400 status code with the following body:

{
    "message": "Unable to cancel order: Order already canceled or failed"
}

Alternatively, you may receive a 404 status code for other failures.