WalaaPass Merchant API v1

https://walaapass.com/api/v1

Authorization: Bearer wlp_your_api_key_here

// Missing or malformed header → 401
{ "error": "Missing or invalid Authorization header. Use: Bearer wlp_..." }

// Invalid key format → 401
{ "error": "Invalid API key format" }

// Key not found or revoked → 401
{ "error": "Invalid API key" }

// Key expired → 401
{ "error": "API key has expired" }

// Plan downgraded → 403
{ "error": "API access requires the Special plan" }

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 60

{ "error": "Rate limit exceeded. Maximum 60 requests per minute." }

Retry-After: 60

{
  "data": {
    "customer_number": 100042,
    "name": "Ahmed Ali",
    "..."
  }
}

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 342,
    "total_pages": 18
  }
}

{
  "error": "Human-readable error message"
}

GET /customers

curl "https://walaapass.com/api/v1/customers?page=1&page_size=10&search=ahmed" \
  -H "Authorization: Bearer wlp_your_api_key_here"

curl "https://walaapass.com/api/v1/customers?mobile=%2B966501234567" \
  -H "Authorization: Bearer wlp_your_api_key_here"

{
  "data": [
    {
      "customer_number": 100042,
      "name": "Ahmed Ali",
      "mobile": "+966501234567",
      "email": "ahmed@example.com",
      "gender": "male",
      "date_of_birth": "1990-05-15",
      "current_stamps": 5,
      "lifetime_stamps": 47,
      "rewards_available": 2,
      "rewards_redeemed": 5,
      "current_balance": 0,
      "lifetime_balance": 0,
      "membership_started_at": null,
      "membership_expires_at": null,
      "pass_status": "pass_installed",
      "card_id": "card-uuid-here",
      "branch_id": "branch-uuid-here",
      "created_at": "2024-01-15T10:30:00.000Z",
      "updated_at": "2024-03-01T14:20:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 10,
    "total": 342,
    "total_pages": 35
  }
}

GET /customers/:customer_id

curl "https://walaapass.com/api/v1/customers/100042" \
  -H "Authorization: Bearer wlp_your_api_key_here"

{
  "data": {
    "customer_number": 100042,
    "name": "Ahmed Ali",
    "mobile": "+966501234567",
    "email": "ahmed@example.com",
    "current_stamps": 5,
    "rewards_available": 2,
    "card_id": "card-uuid",
    "branch_id": "branch-uuid",
    "cards": {
      "id": "card-uuid",
      "name": "Gold Loyalty",
      "display_name": "Gold Card",
      "type": "stamp"
    },
    "branches": {
      "id": "branch-uuid",
      "name": "Downtown Branch"
    },
    "..."
  }
}

PATCH /customers/:customer_id

curl -X PATCH "https://walaapass.com/api/v1/customers/100042" \
  -H "Authorization: Bearer wlp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ahmed Mohammed Ali",
    "email": "ahmed.new@example.com"
  }'

POST /customers/:customer_id/stamps

curl -X POST "https://walaapass.com/api/v1/customers/100042/stamps" \
  -H "Authorization: Bearer wlp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"count": 1}'

{
  "data": {
    "customer_number": 100042,
    "current_stamps": 6,
    "lifetime_stamps": 48,
    "rewards_available": 2,
    "..."
  },
  "reward_earned": false
}

{
  "data": {
    "customer_number": 100042,
    "current_stamps": 0,
    "lifetime_stamps": 50,
    "rewards_available": 3,
    "..."
  },
  "reward_earned": true
}

{ "error": "Stamp cooldown: please wait 12 minutes" }

DELETE /customers/:customer_id/stamps

curl -X DELETE "https://walaapass.com/api/v1/customers/100042/stamps" \
  -H "Authorization: Bearer wlp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"count": 1}'

POST /customers/:customer_id/rewards/redeem

curl -X POST "https://walaapass.com/api/v1/customers/100042/rewards/redeem" \
  -H "Authorization: Bearer wlp_your_api_key_here"

{
  "data": {
    "customer_number": 100042,
    "rewards_available": 1,
    "rewards_redeemed": 6,
    "..."
  }
}

{ "error": "No rewards available" }

POST /customers/:customer_id/discount

curl -X POST "https://walaapass.com/api/v1/customers/100042/discount" \
  -H "Authorization: Bearer wlp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"amount": 200.00}'

{
  "data": {
    "discount": 30.00,
    "final_total": 170.00,
    "rate": 15
  }
}

{ "error": "Invalid amount" }              // amount <= 0 or not a number
{ "error": "Card is not a discount type" }  // customer's card isn't a discount card
{ "error": "Invalid JSON body" }            // malformed request body

POST /customers/:customer_id/membership

curl -X POST "https://walaapass.com/api/v1/customers/100042/membership" \
  -H "Authorization: Bearer wlp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"action": "activate"}'

{
  "data": {
    "started_at": "2024-03-01T10:00:00.000Z",
    "expires_at": "2024-03-31T10:00:00.000Z",
    "days_remaining": 30
  }
}

{ "error": "Invalid action. Use 'activate' or 'renew'." }
{ "error": "Card is not a subscription type" }

GET /branches

curl "https://walaapass.com/api/v1/branches" \
  -H "Authorization: Bearer wlp_your_api_key_here"

{
  "data": [
    {
      "id": "branch-uuid",
      "name": "Downtown Branch",
      "mobile": "+966501234567",
      "description": "Main branch in city center",
      "google_map_link": "https://maps.google.com/...",
      "latitude": 24.7136,
      "longitude": 46.6753,
      "is_active": true,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-02-15T12:00:00.000Z"
    }
  ]
}

GET /cards

curl "https://walaapass.com/api/v1/cards" \
  -H "Authorization: Bearer wlp_your_api_key_here"

{
  "data": [
    {
      "id": "card-uuid",
      "name": "Gold Loyalty",
      "display_name": "Gold Card",
      "display_name_ar": "البطاقة الذهبية",
      "type": "stamp",
      "type_value": 10,
      "max_discount": null,
      "card_color": "#1a1a2e",
      "text_color": "#ffffff",
      "is_active": true,
      "branch_id": null,
      "stamp_cooldown_minutes": 30,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-02-15T12:00:00.000Z",
      "card_rewards": [
        {
          "id": "reward-uuid",
          "name": "Free Coffee",
          "name_ar": "قهوة مجانية",
          "stamps_required": 10,
          "is_active": true
        }
      ]
    }
  ]
}

GET /transactions

curl "https://walaapass.com/api/v1/transactions?customer_number=100042&type=STAMP_ADDED&page_size=50" \
  -H "Authorization: Bearer wlp_your_api_key_here"

{
  "data": [
    {
      "id": "txn-uuid",
      "type": "STAMP_ADDED",
      "details": "1 stamp added via API",
      "metadata": {
        "count": 1,
        "previousStamps": 4,
        "newStamps": 5,
        "source": "api"
      },
      "card_id": "card-uuid",
      "branch_id": "branch-uuid",
      "created_at": "2024-03-01T14:30:00.000Z",
      "customers": { "customer_number": 100042, "name": "Ahmed", "mobile": "+966501234567" },
      "cards": { "id": "card-uuid", "name": "Gold Card" },
      "branches": { "id": "branch-uuid", "name": "Downtown" }
    }
  ],
  "pagination": { "page": 1, "page_size": 50, "total": 230, "total_pages": 5 }
}

# List customers with search
curl "https://walaapass.com/api/v1/customers?search=ahmed&page_size=10" \
  -H "Authorization: Bearer wlp_your_api_key_here"

# Look up customer by phone number
curl "https://walaapass.com/api/v1/customers?mobile=%2B966501234567" \
  -H "Authorization: Bearer wlp_your_api_key_here"

# Look up customer by Customer ID
curl "https://walaapass.com/api/v1/customers?customer_number=100042" \
  -H "Authorization: Bearer wlp_your_api_key_here"

# Get a single customer
curl "https://walaapass.com/api/v1/customers/100042" \
  -H "Authorization: Bearer wlp_your_api_key_here"

# Add 2 stamps
curl -X POST "https://walaapass.com/api/v1/customers/100042/stamps" \
  -H "Authorization: Bearer wlp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"count": 2}'

# Redeem a reward
curl -X POST "https://walaapass.com/api/v1/customers/100042/rewards/redeem" \
  -H "Authorization: Bearer wlp_your_api_key_here"

# Apply discount on 150 SAR purchase
curl -X POST "https://walaapass.com/api/v1/customers/100042/discount" \
  -H "Authorization: Bearer wlp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"amount": 150}'

# Activate membership
curl -X POST "https://walaapass.com/api/v1/customers/100042/membership" \
  -H "Authorization: Bearer wlp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"action": "activate"}'

# Update customer info
curl -X PATCH "https://walaapass.com/api/v1/customers/100042" \
  -H "Authorization: Bearer wlp_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ahmed Ali", "email": "ahmed@company.com"}'

# List transactions for a customer
curl "https://walaapass.com/api/v1/transactions?customer_number=100042&page_size=50" \
  -H "Authorization: Bearer wlp_your_api_key_here"

const API_KEY = process.env.WALAAPASS_API_KEY;
const BASE_URL = 'https://walaapass.com/api/v1';

async function walaaApi(path, options = {}) {
  const res = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  // Log rate limit status
  const remaining = res.headers.get('X-RateLimit-Remaining');
  if (remaining && parseInt(remaining) < 10) {
    console.warn(`API rate limit warning: ${remaining} requests remaining`);
  }

  const json = await res.json();
  if (!res.ok) throw new Error(json.error || `HTTP ${res.status}`);
  return json;
}

// List all customers (paginated)
const { data: customers, pagination } = await walaaApi('/customers?page=1&page_size=50');
console.log(`Found ${pagination.total} customers`);

// Look up customer by phone number
const { data: results } = await walaaApi('/customers?mobile=%2B966501234567');
const customer = results[0];

// Or look up by Customer ID
const { data: singleCustomer } = await walaaApi('/customers/100042');

// Add a stamp after purchase
const { data: updated, reward_earned } = await walaaApi(`/customers/${customer.customer_number}/stamps`, {
  method: 'POST',
  body: JSON.stringify({ count: 1 }),
});

if (reward_earned) {
  console.log('Customer earned a reward!');
}

// Apply discount at checkout
const { data: discount } = await walaaApi(`/customers/${customer.customer_number}/discount`, {
  method: 'POST',
  body: JSON.stringify({ amount: 200.00 }),
});
console.log(`Discount: ${discount.discount} SAR, Final: ${discount.final_total} SAR`);

// Redeem reward
await walaaApi(`/customers/${customer.customer_number}/rewards/redeem`, { method: 'POST' });

// Activate subscription
const { data: membership } = await walaaApi(`/customers/${customer.customer_number}/membership`, {
  method: 'POST',
  body: JSON.stringify({ action: 'activate' }),
});
console.log(`Membership valid for ${membership.days_remaining} days`);

// Get all cards and branches
const { data: cards } = await walaaApi('/cards');
const { data: branches } = await walaaApi('/branches');

import requests
import os

API_KEY = os.environ["WALAAPASS_API_KEY"]
BASE_URL = "https://walaapass.com/api/v1"

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {API_KEY}"})

# List customers
resp = session.get(f"{BASE_URL}/customers", params={"page_size": 50})
data = resp.json()
print(f"Total customers: {data['pagination']['total']}")
print(f"Rate limit remaining: {resp.headers.get('X-RateLimit-Remaining')}")

# Search by phone
resp = session.get(f"{BASE_URL}/customers", params={"mobile": "+966501234567"})
customer = resp.json()["data"][0]

# Add stamp (use Customer ID)
resp = session.post(
    f"{BASE_URL}/customers/{customer['customer_number']}/stamps",
    json={"count": 1}
)
result = resp.json()
if result.get("reward_earned"):
    print("Reward earned!")

# Apply discount
resp = session.post(
    f"{BASE_URL}/customers/{customer['customer_number']}/discount",
    json={"amount": 150.00}
)
discount = resp.json()["data"]
print(f"Discount: {discount['discount']} SAR | Final: {discount['final_total']} SAR")

# Redeem reward
session.post(f"{BASE_URL}/customers/{customer['customer_number']}/rewards/redeem")

# Activate membership
resp = session.post(
    f"{BASE_URL}/customers/{customer['customer_number']}/membership",
    json={"action": "activate"}
)
membership = resp.json()["data"]
print(f"Membership: {membership['days_remaining']} days remaining")

# Export all transactions
all_txns = []
page = 1
while True:
    resp = session.get(f"{BASE_URL}/transactions", params={"page": page, "page_size": 100})
    data = resp.json()
    all_txns.extend(data["data"])
    if page >= data["pagination"]["total_pages"]:
        break
    page += 1

print(f"Exported {len(all_txns)} transactions")

<?php
$apiKey = getenv('WALAAPASS_API_KEY');
$baseUrl = 'https://walaapass.com/api/v1';

function walaaApi($path, $method = 'GET', $body = null) {
    global $apiKey, $baseUrl;

    $ch = curl_init($baseUrl . $path);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Authorization: Bearer $apiKey",
        "Content-Type: application/json",
    ]);

    if ($method !== 'GET') {
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
        if ($body) curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
    }

    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Search customer by phone
$result = walaaApi('/customers?mobile=' . urlencode('+966501234567'));
$customer = $result['data'][0];

// Add stamp (use Customer ID)
$stampResult = walaaApi("/customers/{$customer['customer_number']}/stamps", 'POST', ['count' => 1]);
if ($stampResult['reward_earned']) {
    echo "Reward earned!\n";
}

// Apply discount
$discount = walaaApi("/customers/{$customer['customer_number']}/discount", 'POST', ['amount' => 100]);
echo "Final total: {$discount['data']['final_total']} SAR\n";

// After every purchase, give bonus stamps based on amount
const purchaseAmount = 150; // SAR
const bonusStamps = Math.floor(purchaseAmount / 50); // 1 stamp per 50 SAR

if (bonusStamps > 0) {
  await walaaApi(`/customers/${customer.customer_number}/stamps`, {
    method: 'POST',
    body: JSON.stringify({ count: Math.min(bonusStamps, 10) }),
  });
}

async function safeApiCall(path, options = {}, retries = 3) {
  for (let attempt = 1; attempt <= retries; attempt++) {
    try {
      const res = await fetch(`${BASE_URL}${path}`, {
        ...options,
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json',
          ...options.headers
        },
      });

      // Rate limited — wait and retry
      if (res.status === 429) {
        const wait = parseInt(res.headers.get('Retry-After') || '60');
        console.log(`Rate limited. Waiting ${wait}s (attempt ${attempt})`);
        await new Promise(r => setTimeout(r, wait * 1000));
        continue;
      }

      // Concurrent conflict — retry immediately
      if (res.status === 409 && attempt < retries) {
        console.log(`Conflict, retrying (attempt ${attempt})`);
        continue;
      }

      const json = await res.json();
      if (!res.ok) {
        console.error(`API Error ${res.status}: ${json.error}`);
        return null;
      }

      return json;
    } catch (err) {
      if (attempt === retries) {
        console.error('Network error:', err.message);
        return null;
      }
      await new Promise(r => setTimeout(r, 1000 * attempt));
    }
  }
  return null;
}