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

There are two key types:

Prefix	Mode	Effect
pk_live_	Production	Real orders. Dispatched to drivers, deducts your wallet, fires notifications and webhooks.
pk_test_	Sandbox	Test orders. Isolated data, no real drivers, no wallet deduction, no notifications.

Both keys belong to your merchant account. The only difference is that anything created with a pk_test_ key is treated as sandbox data and never affects production. See Authentication and Sandbox & Testing for details.

Request your keys from the Wasal team, or generate a sandbox key yourself from your merchant dashboard.

Quick start. Download the Wasal Integration Test File — a ready-to-run collection of every API endpoint, compatible with VS Code REST Client and JetBrains HTTP Client. Drop in your pk_test_ key and run each request top-to-bottom.

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_test_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_test_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 keys and sandbox isolation work → Authentication
• Simulate the full delivery lifecycle without a real driver → Sandbox & Testing
• Full endpoint reference → Orders