Getting Started

The Wasal Merchant Integration API is a REST API that lets you create and manage delivery orders programmatically. This guide walks you through your first order end-to-end.

Base URL

All requests are made over HTTPS to the Wasal API host:

https://www.wasal.org/api/v1

Every integration endpoint is prefixed with /integration/merchant/. For example, creating an order is:

POST https://www.wasal.org/api/v1/integration/merchant/order

Authentication

Every authenticated request carries your API key in the Authorization header:

Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Each merchant has one pk_live_ integration key. Requests perform normal production operations, including wallet charges, notifications, driver dispatch, and webhooks. See Authentication for storage and rotation guidance.

Request your key from the Wasal team or have an administrator generate it from your merchant record.

Quick start. Download the Wasal Integration Test File, compatible with VS Code REST Client and JetBrains HTTP Client. Use only an approved demo merchant key for closed testing and coordinate order lifecycle tests with the demo delivery partner and driver.

Content type

All request and response bodies are JSON. Send:

Content-Type: application/json

Response envelope

Every response follows the same shape.

Success:

{
  "success": true,
  "data": { /* endpoint-specific payload */ }
}

Error:

{
  "success": false,
  "message": "Human-readable description",
  "code": "MACHINE_READABLE_CODE",
  "errors": { "fieldName": "Field-level message" }
}

The errors object is only present for validation failures (HTTP 400). See the Error Reference for the full list of codes.

Rate limiting

The API allows 600 requests per 15-minute window per key. Every response includes RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. Exceeding the limit returns 429 Too Many Requests — wait for the reset before retrying. See Error Reference.

Your first order in 4 steps

The minimum flow to get a package moving:

1. Look up areas

Customer addresses use Wasal governorate and neighborhood IDs. Fetch governorates, then the neighborhoods within one, and cache them:

curl "https://www.wasal.org/api/v1/integration/merchant/governorate-area?featureType=Governorate"

See Areas & Pricing.

2. Create a customer

curl -X POST https://www.wasal.org/api/v1/integration/merchant/customer \
  -H "Authorization: Bearer pk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sara Ahmad",
    "phoneNumber": "+96550001234",
    "addresses": [{
      "label": "Home",
      "governorateId": "<governorate-id>",
      "neighborhoodId": "<neighborhood-id>",
      "blockId": "4",
      "streetId": "12",
      "houseNumber": "8"
    }]
  }'

The response returns the created customer, including its _id and the generated addresses[] (each with its own _id). See Customers.

Required for pricing: every customer address must include governorateId and neighborhoodId — Wasal resolves the delivery fee from these. Include blockId too whenever possible; it improves routing accuracy.

3. Create an order

curl -X POST https://www.wasal.org/api/v1/integration/merchant/order \
  -H "Authorization: Bearer pk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "<customer-id>",
    "customerAddressId": "<address-id>",
    "branchCode": "MAIN",
    "specialHandlingTags": ["none"],
    "paymentMethod": "cod",
    "amountToCollect": 12.500,
    "pricing": { "total": 12.500 }
  }'

The response returns { order: { _id, orderNumber, status } }. See Orders.

4. Track the order

curl https://www.wasal.org/api/v1/integration/merchant/order/track/<orderNumber>

This public endpoint returns the live status and, once a driver is en route, their live location. See Order Tracking.

Next steps

• Learn how to secure and rotate your key → Authentication
• Coordinate closed lifecycle testing with the Wasal demo merchant, delivery partner, and driver accounts
• Full endpoint reference → Orders