Public API — Beta

Connect your own system, in any language

This is a plain REST API over HTTP/JSON — it doesn't matter if your POS, ERP or custom software is written in PHP, Python, .NET, Java or anything else. If it can make an HTTP request, it can talk to Melaapps.

Direct integration requires approval

The endpoints below are documented so you can see exactly what you'd be building against, but connecting your own system requires our sign-off first. Tell us about your integration and we'll get back to you.

1Base URL & format

Every request and response uses JSON. Send files (like product images) as multipart/form-data.

https://melaapps.com/api/v1

Two 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.

POST/auth/vendor/login
FieldTypeNotes
emailstringrequired
passwordstringrequired
vendor_typestringrequired — 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.

POST/vendor/item/store — create a product (multipart/form-data)
PUT/vendor/item/update — update one (send id plus the changed fields)
FieldTypeNotes
category_idintrequired — root category id
sub_category_idintoptional
pricenumberrequired — VAT-inclusive
translationsJSON stringrequired — array of {locale, key, value}; locales en, mt, es; keys name and description
imagefilerequired on create — main image
item_images[]file[]optional — additional images, several allowed
current_stockintoptional — one quantity per product
brand_idintoptional — see Reference data
unitintoptional — unit id
maximum_cart_quantityintoptional — cap per order
discount / discount_typenumber / stringoptional — amount or percent. No start or end date — send discount=0 to end a promotion.
tagsstringoptional — 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.

PUT/vendor/item/stock-update — stock only: product_id, current_stock
GET/vendor/item/status — show/hide: id, status (0 or 1)
DELETE/vendor/item/delete — remove a product: id
GET/vendor/get-items-list — your catalogue as Melaapps holds it

For 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.

EndpointNotes
GET/vendor/current-ordersEvery open order, newest first, not paginated.
GET/vendor/order-details?order_id=Full order: customer, address, lines.
GET/vendor/all-ordersHistory. Also /completed-orders and /canceled-orders.
PUT/vendor/update-order-statusMove the order forward — see below.
PUT/vendor/update-order-amountReduce 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

PUT/vendor/update-order-status — order_id, status, reason, otp
StatusWho sends it
confirmed → processing → handoverYou, as the store.
deliveredThe 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.
canceledYou, 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.

POST/vendor/pos/place-order
FieldTypeNotes
store_idintrequired
payment_methodstringrequired
paid_amountnumberrequired
cartJSON stringrequired — array of line items
GET/vendor/pos/orders — list your POS orders
GET/vendor/pos/customers?search= — find a customer by name or phone

6Reference 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>]
EndpointNotes
GET/categoriesRoot categories. Children: /categories/childes/{id}. Map your own departments to these ids.
GET/brandBrands and their ids. Missing one? Ask us and we add it.
GET/vendor/categoriesThe category tree as it applies to your own store.
GET/vendor/unitUnits of measure.
GET/vendor/profileYour store: id, delivery settings, opening hours.

7Limits & conventions

Rate limitNo 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.
BulkNo bulk endpoint — one request per product. Send only what changed.
Images2 MB per file, 8 MB per request (about three images per call). JPG, PNG or WebP.
LanguagesEnglish (en), Maltese (mt) and Spanish (es). Send at least English.
VATPrices are VAT-inclusive. There is no per-product rate field.
CurrencyEuro (€).

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." }
  ]
}
CodeNotes
401Token missing, or replaced by a newer login. Authenticate again.
403 Vendor type requiredThe vendorType header is missing.
422A field failed validation — the message names it.

Building an integration?

Tell us what you're connecting — POS, ERP, or your own platform — and we'll help you get a vendor token to test against.

Get in touch