1Base URL & format
Every request and response uses JSON. Send files (like product images) as multipart/form-data.
https://melaapps.com/api/v1Two headers, every authenticated call. Besides the bearer token you must always send vendorType. Without it every endpoint answers 403 Vendor type required.
Authorization: Bearer <your-token>
vendorType: owner # or "employee"
2Authentication
A merchant authenticates once with their Melaapps credentials and gets a bearer token. There are no API keys.
/auth/vendor/login| Field | Type | Notes |
|---|---|---|
email | string | required |
password | string | required |
vendor_type | string | required — owner or employee |
Response: { "token": "…", "module_type": "…" }.
Tokens do not expire, but each login replaces the previous one. Log in once, cache the token, and authenticate again only after a 401. For an unattended integration, ask the store owner to create a staff account limited to Items and Orders and log in with vendor_type: "employee" — that way nobody's personal login can invalidate your token.
curl -X POST https://melaapps.com/api/v1/auth/vendor/login \
-H "Content-Type: application/json" \
-d '{
"email": "vendor@example.com",
"password": "your-password",
"vendor_type": "employee"
}'
$ch = curl_init('https://melaapps.com/api/v1/auth/vendor/login');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'email' => 'vendor@example.com',
'password' => 'your-password',
'vendor_type' => 'employee',
]),
CURLOPT_RETURNTRANSFER => true,
]);
$token = json_decode(curl_exec($ch), true)['token'];
import requests
resp = requests.post(
"https://melaapps.com/api/v1/auth/vendor/login",
json={
"email": "vendor@example.com",
"password": "your-password",
"vendor_type": "employee",
},
)
token = resp.json()["token"]
# Reuse these headers on every following call
headers = {"Authorization": f"Bearer {token}", "vendorType": "employee"}
using var client = new HttpClient();
var payload = new {
email = "vendor@example.com",
password = "your-password",
vendor_type = "employee"
};
var response = await client.PostAsJsonAsync(
"https://melaapps.com/api/v1/auth/vendor/login", payload);
var json = await response.Content.ReadFromJsonAsync<JsonElement>();
string token = json.GetProperty("token").GetString();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", token);
client.DefaultRequestHeaders.Add("vendorType", "employee");
3Products
Push your catalogue into Melaapps. Create with item/store, then keep it up to date with the cheaper calls below.
/vendor/item/store — create a product (multipart/form-data)/vendor/item/update — update one (send id plus the changed fields)| Field | Type | Notes |
|---|---|---|
category_id | int | required — root category id |
sub_category_id | int | optional |
price | number | required — VAT-inclusive |
translations | JSON string | required — array of {locale, key, value}; locales en, mt, es; keys name and description |
image | file | required on create — main image |
item_images[] | file[] | optional — additional images, several allowed |
current_stock | int | optional — one quantity per product |
brand_id | int | optional — see Reference data |
unit | int | optional — unit id |
maximum_cart_quantity | int | optional — cap per order |
discount / discount_type | number / string | optional — amount or percent. No start or end date — send discount=0 to end a promotion. |
tags | string | optional — comma-separated, searchable |
There is no SKU or barcode field. Keep your own mapping of our id (returned by item/store) to your product. If you want your reference searchable, put it in tags and find it later with POST /vendor/item/search.
/vendor/item/stock-update — stock only: product_id, current_stock/vendor/item/status — show/hide: id, status (0 or 1)/vendor/item/delete — remove a product: id/vendor/get-items-list — your catalogue as Melaapps holds itFor a periodic inventory sync use stock-update, not item/update — it is a small JSON call and avoids re-uploading images. Setting stock to 0 does not hide a product; it shows as out of stock. Use item/status to hide it.
curl -X POST https://melaapps.com/api/v1/vendor/item/store \
-H "Authorization: Bearer $TOKEN" \
-H "vendorType: employee" \
-F "category_id=28" \
-F "sub_category_id=255" \
-F "price=329.00" \
-F "current_stock=10" \
-F "brand_id=317" \
-F "maximum_cart_quantity=2" \
-F "tags=SKU-12345" \
-F 'translations=[{"locale":"en","key":"name","value":"Washing machine 7 kg"},{"locale":"en","key":"description","value":"A+++ , 1400 rpm"}]' \
-F "image=@main.jpg" \
-F "item_images[]=@side.jpg"
import json, requests
translations = json.dumps([
{"locale": "en", "key": "name", "value": "Washing machine 7 kg"},
{"locale": "en", "key": "description", "value": "A+++, 1400 rpm"},
])
with open("main.jpg", "rb") as main, open("side.jpg", "rb") as side:
r = requests.post(
"https://melaapps.com/api/v1/vendor/item/store",
headers=headers, # Bearer + vendorType
data={
"category_id": 28, "sub_category_id": 255,
"price": 329.00, "current_stock": 10,
"brand_id": 317, "translations": translations,
},
files=[("image", main), ("item_images[]", side)],
)
melaapps_id = r.json()["id"] # store this against your own product
4Orders from the marketplace
Orders placed by customers arrive here. There are no webhooks — poll current-orders every few minutes.
| Endpoint | Notes |
|---|---|
GET/vendor/current-orders | Every open order, newest first, not paginated. |
GET/vendor/order-details?order_id= | Full order: customer, address, lines. |
GET/vendor/all-orders | History. Also /completed-orders and /canceled-orders. |
PUT/vendor/update-order-status | Move the order forward — see below. |
PUT/vendor/update-order-amount | Reduce the total (order_id, order_amount) — the difference is refunded. |
Useful fields on an order: id, order_status, order_type (delivery or take_away), payment_status, order_amount, delivery_charge, schedule_at, otp, customer (name, phone, email), delivery_address (address, latitude, longitude, contact name and phone) and details[] (item_id, quantity, price).
Check payment_status before you confirm. An order can appear while the customer is still at the payment step, with payment_status: "unpaid". It turns paid within minutes, or the order fails and disappears from current-orders. Stock is reserved the moment the order is placed, and released if the customer cancels.
Status flow
/vendor/update-order-status — order_id, status, reason, otp| Status | Who sends it |
|---|---|
confirmed → processing → handover | You, as the store. |
delivered | The Melaapps driver, on a delivery order. You send it yourself only for collection orders, or if your store delivers its own orders — and it then requires the customer's otp, which is in order-details. |
canceled | You, with a mandatory reason, before handover. |
There is no automatic cancellation: an unconfirmed order stays pending until you act on it or the customer cancels.
5Point-of-sale orders
Have your own POS software? These endpoints push a sale straight into Melaapps as an order, and look up existing customers.
/vendor/pos/place-order| Field | Type | Notes |
|---|---|---|
store_id | int | required |
payment_method | string | required |
paid_amount | number | required |
cart | JSON string | required — array of line items |
/vendor/pos/orders — list your POS orders/vendor/pos/customers?search= — find a customer by name or phone6Reference data
Read these before your first upload to resolve the ids you need. Categories and brands require two extra headers telling Melaapps which storefront and area you are asking about — we give you your values when you are approved.
moduleId: <your module id>
zoneId: [<your zone id>]
| Endpoint | Notes |
|---|---|
GET/categories | Root categories. Children: /categories/childes/{id}. Map your own departments to these ids. |
GET/brand | Brands and their ids. Missing one? Ask us and we add it. |
GET/vendor/categories | The category tree as it applies to your own store. |
GET/vendor/unit | Units of measure. |
GET/vendor/profile | Your store: id, delivery settings, opening hours. |
7Limits & conventions
| Rate limit | No hard limit is enforced today. Pace your integration sensibly — a delta sync every few minutes is well within what we expect. If we introduce a limit we will announce it at least 30 days beforehand. |
| Bulk | No bulk endpoint — one request per product. Send only what changed. |
| Images | 2 MB per file, 8 MB per request (about three images per call). JPG, PNG or WebP. |
| Languages | English (en), Maltese (mt) and Spanish (es). Send at least English. |
| VAT | Prices are VAT-inclusive. There is no per-product rate field. |
| Currency | Euro (€). |
8Errors
Errors come back as HTTP 401, 403 or 422 with a JSON body shaped like this — read errors[].message.
{
"errors": [
{ "code": "category_id", "message": "The category id field is required." }
]
}
| Code | Notes |
|---|---|
401 | Token missing, or replaced by a newer login. Authenticate again. |
403 Vendor type required | The vendorType header is missing. |
422 | A field failed validation — the message names it. |
DEVELOPERS