Is Mahjoz compliant with ZATCA Phase 2 e-invoicing?

Yes, Mahjoz is 100% compliant with ZATCA Phase 2. The system connects directly to the Fatoora platform with digital signing and automatic invoice submission within 24 hours.

Can I try Mahjoz before subscribing?

Yes, you can request a free demo and explore all system features before making a subscription decision.

What payment methods are supported?

Mahjoz supports 9 payment methods: Mada, STC Pay, Tabby, Tamara, Apple Pay, Visa, Mastercard, bank transfer, and cash on delivery.

Is there a commission on each booking or sale?

No, Mahjoz does not take any commission on your bookings or sales. The subscription is annual at a fixed price that never changes regardless of your customer or sales volume.

Does Mahjoz have a mobile app for employees?

Yes, the employee app is available on iOS and Android and supports 6 languages: Arabic, English, Urdu, Tagalog, Hindi, and Indonesian.

How long does it take to set up?

You can start using Mahjoz within minutes. Our support team helps you set up your account and configure the system according to your business needs.

Back to Overview

API Reference

Detailed request and response examples for every endpoint.

https://api.mahjoz.io/api/open/v1

Orders

GET/ordersorders:read

List orders with pagination and optional filters.

Field	Type	Required	Description
`page`	integer	No	Page number
`per_page`	integer	No	Items per page (max 100)
`from`	date	No	Filter from date (YYYY-MM-DD)
`to`	date	No	Filter to date (YYYY-MM-DD)
`status`	string	No	Filter by status

Response

{
  "data": [
    {
      "id": "uuid",
      "order_number": "ORD-001",
      "status": "confirmed",
      "source": "api",
      "customer": { "id": "uuid", "first_name": "...", "last_name": "...", "phone": "..." },
      "branch": { "id": "uuid", "name": "Main Branch" },
      "items": [
        {
          "id": "uuid",
          "name": "Haircut",
          "type": "service",
          "price": 100.00,
          "quantity": 1,
          "discount_amount": 0,
          "total": 100.00
        }
      ],
      "currency": "SAR",
      "total": 150.00,
      "created_at": "2026-02-25T10:00:00.000000Z"
    }
  ]
}

GET/orders/{uuid}orders:read

Get order detail with items, transactions, and full customer/branch details. Each item includes staff_id.

Response

{
  "data": {
    "id": "uuid",
    "order_number": "ORD-001",
    "status": "confirmed",
    "source": "api",
    "address": "123 Main St, Riyadh",
    "customer": { "id": "uuid", "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "+966500000001" },
    "branch": { "id": "uuid", "name": "Main Branch" },
    "items": [
      { "id": "uuid", "name": "Haircut", "type": "service", "price": 100.00, "quantity": 1, "discount_amount": 0, "total": 100.00 }
    ],
    "transactions": [
      { "id": "uuid", "amount": "100.00", "status": "confirmed", "date": "2026-02-25T10:30:00.000000Z" }
    ],
    "currency": "SAR",
    "total": 150.00,
    "discount_amount": 0,
    "tax_amount": 7.50,
    "pin_code": "4821",
    "created_at": "2026-02-25T10:00:00.000000Z",
    "updated_at": "2026-02-25T10:00:00.000000Z"
  }
}

Field	Type	Required	Description
`pin_code`	string \| null	No	Order PIN code (e.g. 4-digit). Set when the tenant has the "Require PIN code to close order" setting enabled, used by staff to confirm completion. null otherwise.

POST/ordersorders:write

Create a new order. If the order includes service items, the API validates the requested time slot before creating it.

Request

{
  "team_id": "branch-uuid",
  "customer_id": "customer-uuid",
  "start": "2026-02-25T10:00:00",
  "items": [
    {
      "id": "service-uuid",
      "type": "service",
      "staff_id": "staff-uuid",
      "quantity": 1,
      "unit_amount": 100.00,
      "discount_amount": 0,
      "option_id": "option-uuid"
    },
    {
      "id": "product-uuid",
      "type": "product",
      "quantity": 2,
      "unit_amount": 25.00
    }
  ],
  "note": "Optional note",
  "latitude": 24.7136,
  "longitude": 46.6753
}

Field	Type	Required	Description
`team_id`	uuid	Yes	Branch UUID
`customer_id`	uuid	Yes	Customer UUID
`start`	datetime	Yes	Required if items contain a service. ISO 8601.
`items`	array	Yes	At least 1 item
`items.*.id`	uuid	Yes	Service/Product/Package UUID
`items.*.type`	string	Yes	service, product, or package
`items.*.quantity`	integer	Yes	Minimum 1
`items.*.staff_id`	uuid	No	Staff or staff label UUID (validated by assignment type)
`items.*.unit_amount`	number	No	Override unit price
`items.*.discount_amount`	number	No	Discount per item
`items.*.option_id`	uuid	No	Service option UUID
`note`	string	No	Order note
`latitude`	number	No	Order location latitude
`longitude`	number	No	Order location longitude

Staff Assignment: staff_id is validated based on the service assignment type: single_provider expects a staff UUID, team expects a staff label UUID, multiple_providers does not require it.

Response (201)

{
  "data": {
    "id": "uuid",
    "order_number": "ORD-042",
    "status": "confirmed",
    "currency": "SAR",
    "total": 150.00,
    "created_at": "2026-02-25T10:30:00.000000Z"
  }
}

POST/orders/{uuid}/statusorders:write

Change an order's status. Dispatches the order.status_changed webhook. Responds with the full order detail.

Request

{
  "status": "completed",
  "note_for_status": "finished on-site"
}

Field	Type	Required	Description
`status`	string	Yes	One of: confirmed, in-progress, completed, canceled
`note_for_status`	string	No	Free-text reason or note attached to the transition

Rules: If status equals the order's current status, the call is a no-op. 422 order_has_invoice if you try to cancel an order that already has an invoice. 422 invalid_status_transition if you try to cancel an order that has refunded children. Canceling restores item stock automatically.

Availability

POST/availabilityorders:write

Check available time slots for a service.

Request

{
  "service_id": "service-uuid",
  "date": "2026-02-25",
  "staff_id": "staff-uuid",
  "quantity": 1,
  "visible_days": 7,
  "next_availability": false
}

Field	Type	Required	Description
`service_id`	uuid	Yes	Service to check
`date`	date	Yes	Start date (YYYY-MM-DD)
`staff_id`	uuid	No	Specific staff member
`quantity`	integer	No	Default 1
`visible_days`	integer	No	Days to check (1-30, default 7)
`next_availability`	boolean	No	Find next available slot if none on given date

Response

{
  "data": {
    "slots": {
      "2026-02-25": ["09:00", "09:30", "10:00", "10:30"],
      "2026-02-26": ["09:00", "11:00", "14:00"]
    }
  }
}

Customers

GET/customerscustomers:read

List customers with pagination and optional filters.

Field	Type	Required	Description
`page`	integer	No	Page number
`per_page`	integer	No	Items per page (max 100)
`name`	string	No	Filter by name
`phone`	string	No	Filter by phone
`email`	string	No	Filter by email

GET/customers/{uuid}customers:read

Get customer detail with address, note, blocked status, tax_registration_number, and tags.

GET/customers/phonecustomers:read

Find a customer by exact phone number. Returns the customer or null.

Field	Type	Required	Description
`phone`	string	Yes	Exact phone number (URL-encode + as %2B)

POST/customerscustomers:write

Create a new customer.

Request

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+966500000001",
  "phone_country": "SA",
  "type": "individual",
  "city": "Riyadh",
  "address": "123 Main St",
  "note": "VIP customer",
  "tax_registration_number": "300000000000003"
}

Field	Type	Required	Description
`first_name`	string	Yes	Min 2 chars
`last_name`	string	No	Min 2 chars
`email`	string	No	Valid email
`phone`	string	No	Unique per tenant
`phone_country`	string	No	Required with phone, 2-char code (e.g. SA)
`type`	string	No	individual or company (default: individual)
`city`	string	No	Min 3 chars
`address`	string	No	Min 3 chars
`note`	string	No	Free text
`tax_registration_number`	string	No	15 digits

Response (201)

{
  "data": {
    "id": "uuid",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+966500000001",
    "type": "individual",
    "city": "Riyadh",
    "created_at": "2026-02-25T10:30:00.000000Z"
  }
}

Items (Services & Products)

GET/itemsitems:read

List items (services and products) with pagination. Services include duration; products include cost and stock. Each item includes options array with variants.

Field	Type	Required	Description
`page`	integer	No	Page number
`per_page`	integer	No	Items per page (max 100)
`type`	string	No	service or product
`name`	string	No	Filter by name

Response

{
  "data": [
    {
      "id": "uuid",
      "type": "service",
      "sku": "SRV-001",
      "name": { "ar": "قص شعر", "en": "Haircut" },
      "slug": "haircut",
      "status": true,
      "price": 100.00,
      "offer_price": 80.00,
      "currency": "SAR",
      "duration": 30,
      "options": [
        {
          "id": "uuid",
          "name": "Red Small",
          "price": 120.00,
          "values": [
            { "option_value_id": "uuid", "option_name": "Color", "value": "Red" },
            { "option_value_id": "uuid", "option_name": "Size", "value": "Small" }
          ]
        }
      ],
      "category": { "id": "uuid", "name": { "ar": "الشعر", "en": "Hair" } },
      "branch": { "id": "uuid", "name": "Main Branch" }
    }
  ]
}

GET/items/{uuid}items:read

Get item detail. For services, includes staff array with id, name, price, and duration.

Staff (Providers)

GET/staffstaff:read

List staff members with their assigned services.

Field	Type	Required	Description
`page`	integer	No	Page number
`per_page`	integer	No	Items per page (max 100)
`name`	string	No	Filter by name
`branch_id`	uuid	No	Filter by branch UUID

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "Ahmed Ali",
      "phone": "+966500000001",
      "email": "ahmed@example.com",
      "image": "https://...",
      "branch": { "id": "uuid", "name": "Main Branch" },
      "services": [
        { "id": "uuid", "name": "Haircut", "price": 100.00, "duration": 30 }
      ]
    }
  ]
}

GET/staff/{uuid}staff:read

Get staff member detail with branch and full services list.

GET/staff/{uuid}/working-hourstaff:read

Get the staff member's default working hour with intervals. Falls back to the team (branch) working hour when the staff has no custom one. Returns 404 only when neither has a working hour configured.

Response

{
  "data": {
    "id": "uuid",
    "source": "staff",
    "all_time": false,
    "active": true,
    "intervals": [
      { "id": "uuid", "day": "sun", "from": "09:00", "to": "17:00", "active": true }
    ]
  }
}

Field	Type	Required	Description
`source`	string	No	staff if the staff has a custom working hour, branch if falling back to the branch (team) working hour
`intervals[].day`	string	No	Lowercase three-letter day code (sun, mon, tue, wed, thu, fri, sat)
`intervals[].from`	string	No	Start time in HH:mm (tenant timezone)
`intervals[].to`	string	No	End time in HH:mm (tenant timezone)

Branches

GET/branchesbranches:read

List all active branches for the tenant.

Field	Type	Required	Description
`page`	integer	No	Page number
`per_page`	integer	No	Items per page (max 100)

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "Main Branch",
      "slug": "main-branch",
      "phone": "+966500000001",
      "address": "123 Main St, Riyadh",
      "latitude": 24.7136,
      "longitude": 46.6753,
      "location": "in-store",
      "status": true
    }
  ]
}

Payment Methods

Only payment methods of type cash and other are exposed. Gateway-backed methods (card, wallets, bank transfer) are managed from the Mahjoz dashboard.

GET/payment-methodspayment_methods:read

List the tenant's manual payment methods (cash and other types only).

Field	Type	Required	Description
`page`	integer	No	Page number
`per_page`	integer	No	Items per page (max 100)

Response

{
  "data": [
    {
      "id": "uuid",
      "name": { "ar": "نقدي", "en": "Cash" },
      "slug": "on_arrival",
      "status": true,
      "type": { "id": 1, "slug": "cash", "name": "Cash" },
      "created_at": "2026-04-10T09:00:00.000000Z",
      "updated_at": "2026-04-10T09:00:00.000000Z"
    }
  ]
}

GET/payment-methods/{uuid}payment_methods:read

Get a single payment method by UUID. Returns 404 if the method's type is not cash or other.

POST/payment-methodspayment_methods:write

Create a manual payment method restricted to cash or other types.

Request

{
  "name": "Bank Transfer - Al Rajhi",
  "type": "other",
  "status": true
}

Field	Type	Required	Description
`name`	string	Yes	Display name (max 255 chars)
`type`	string	Yes	cash or other
`status`	boolean	No	Enabled (default true)

Response (201)

{
  "data": {
    "id": "uuid",
    "name": { "en": "Bank Transfer - Al Rajhi" },
    "slug": null,
    "status": true,
    "type": { "id": 4, "slug": "other", "name": "Other" },
    "created_at": "2026-04-15T18:00:00.000000Z",
    "updated_at": "2026-04-15T18:00:00.000000Z"
  }
}

Transactions

GET/transactionstransactions:read

List transactions for the tenant with optional filters.

Field	Type	Required	Description
`page`	integer	No	Page number
`per_page`	integer	No	Items per page (max 100)
`status`	string	No	Filter by transaction status (e.g. confirmed, pending)
`order_id`	uuid	No	Filter by order UUID
`booking_id`	uuid	No	Filter by booking UUID
`from`	date	No	Filter from date (YYYY-MM-DD)
`to`	date	No	Filter to date (YYYY-MM-DD)

Response

{
  "data": [
    {
      "id": "uuid",
      "transaction_no": "TRX-0042",
      "amount": "100.00",
      "currency": "SAR",
      "status": "confirmed",
      "is_deposit": false,
      "note": "Paid in full",
      "date": "2026-04-15T18:00:00.000000Z",
      "payment_method": { "id": "uuid", "name": "Cash", "slug": "on_arrival" },
      "order": { "id": "uuid", "order_number": "ORD-001" },
      "booking": null,
      "created_at": "2026-04-15T18:00:00.000000Z",
      "updated_at": "2026-04-15T18:00:00.000000Z"
    }
  ]
}

GET/transactions/{uuid}transactions:read

Get a single transaction by UUID with its payment method, order, and booking relations.

POST/orders/{order}/paymentstransactions:write

Record a payment against an order. The amount cannot exceed the order's remaining unpaid balance, and the order must not be in draft status.

Request

{
  "amount": 100.00,
  "payment_method_id": "payment-method-uuid",
  "note": "Paid in cash on delivery",
  "reference_number": "REF-12345",
  "date": "2026-04-15T18:00:00"
}

Field	Type	Required	Description
`amount`	number	Yes	Payment amount (0.01 to remaining unpaid)
`payment_method_id`	uuid	Yes	UUID of a payment method enabled for this tenant
`note`	string	No	Free-text note
`reference_number`	string	No	External reference (e.g. bank transfer id)
`date`	datetime	No	Payment date (defaults to now)

Response (201)

{
  "data": {
    "id": "uuid",
    "transaction_no": "TRX-0043",
    "amount": "100.00",
    "currency": "SAR",
    "status": "confirmed",
    "is_deposit": false,
    "note": "Paid in cash on delivery",
    "date": "2026-04-15T18:00:00.000000Z",
    "payment_method": { "id": "uuid", "name": "Cash", "slug": "on_arrival" },
    "order": { "id": "uuid", "order_number": "ORD-001" },
    "created_at": "2026-04-15T18:00:00.000000Z",
    "updated_at": "2026-04-15T18:00:00.000000Z"
  }
}

Errors: 422 invalid_order_status if the order is in draft; 422 order_fully_paid if the remaining unpaid amount is already 0.

Webhooks

Webhooks allow your application to receive real-time notifications when order events occur.

Maximum 3 webhooks per tenant. All payloads are signed with HMAC-SHA256.

Available events:

order.createdorder.updatedorder.deletedorder.status_changedorder.invoice_createdorder.payment_accepted

POST/webhookswebhooks:write

Field	Type	Required	Description
`url`	string	Yes	HTTPS endpoint to receive payloads
`events`	string[]	Yes	Event names to subscribe to

Response

{
  "data": {
    "id": "uuid",
    "url": "https://your-app.com/webhooks/mahjoz",
    "events": ["order.created", "order.status_changed"],
    "is_active": true,
    "secret": "a1b2c3...64_char_secret",
    "last_triggered_at": null,
    "created_at": "2026-04-13T19:00:00.000000Z",
    "updated_at": "2026-04-13T19:00:00.000000Z"
  }
}

GET/webhookswebhooks:read

List all webhooks registered by the authenticated client.

Response

{
  "data": [
    {
      "id": "uuid",
      "url": "https://your-app.com/webhooks/mahjoz",
      "events": ["order.created", "order.status_changed"],
      "is_active": true,
      "last_triggered_at": "2026-04-13T20:30:00.000000Z",
      "created_at": "2026-04-13T19:00:00.000000Z",
      "updated_at": "2026-04-13T19:00:00.000000Z"
    }
  ]
}

GET/webhooks/{webhook_id}webhooks:read

Get a specific webhook by ID.

Response

{
  "data": {
    "id": "uuid",
    "url": "https://your-app.com/webhooks/mahjoz",
    "events": ["order.created", "order.status_changed"],
    "is_active": true,
    "last_triggered_at": "2026-04-13T20:30:00.000000Z",
    "created_at": "2026-04-13T19:00:00.000000Z",
    "updated_at": "2026-04-13T19:00:00.000000Z"
  }
}

PUT/webhooks/{webhook_id}webhooks:write

Update a webhook's URL, events, or active status.

Field	Type	Required	Description
`url`	string	No	New HTTPS endpoint
`events`	string[]	No	New event subscriptions
`is_active`	boolean	No	Enable or disable the webhook

Response

{
  "data": {
    "id": "uuid",
    "url": "https://your-app.com/webhooks/mahjoz",
    "events": ["order.created", "order.updated"],
    "is_active": false,
    "last_triggered_at": "2026-04-13T20:30:00.000000Z",
    "created_at": "2026-04-13T19:00:00.000000Z",
    "updated_at": "2026-04-13T19:15:00.000000Z"
  }
}

DELETE/webhooks/{webhook_id}webhooks:write

Delete a webhook. Returns 204 No Content.

Response

204 No Content

Payload Format

All webhook deliveries include a Signature header (HMAC-SHA256 of the body using your secret) and an X-Mahjoz-Event header with the event name.

Response

{
  "event": "order.created",
  "webhook_id": "uuid",
  "timestamp": "2026-04-13T19:30:00+03:00",
  "data": {
    "id": "order-uuid",
    "order_number": "ORD-001",
    "status": "confirmed",
    "customer": { "id": "uuid", "first_name": "...", "last_name": "..." },
    "branch": { "id": "uuid", "name": "Main Branch" },
    "items": [ ... ],
    "transactions": [ ... ],
    "currency": "SAR",
    "total": 50.00,
    "discount_amount": 0,
    "tax_amount": 7.50
  }
}

API Reference

Orders

Availability

Customers

Items (Services & Products)

Staff (Providers)

Branches

Categories

Payment Methods

Transactions

Webhooks

Payload Format