Outlets and Acting User

Two headers tell Mekari POS where a request works and who does it.

X-Outlet-ID

Most endpoints work on one outlet of the merchant. Send the outlet id from GET /outlets in the X-Outlet-ID header.

Needs X-Outlet-ID	Works for the whole company (no X-Outlet-ID)
GET /shifts, products, raw materials, recipes, inventory, GET /payment-methods, orders, returns, refunds, exchanges, approvals	GET /outlets, GET /users, customers, promotions, vouchers, categories, collections, GET /order-source, PUT /order-source, webhook endpoints

If the outlet is missing, is not an active outlet of the merchant, or the acting user has no access to it, the response is 403 with the code OUTLET_FORBIDDEN.

X-User-ID

Every write (POST, PUT, PATCH, DELETE) runs as one staff user of the merchant, also a write that needs no X-Outlet-ID (for example POST /categories). The exceptions are POST /orders, where X-User-ID is optional (see Creating Orders); POST /returns/quote, POST /returns and POST /refunds on your own partner order refunded to your partner rail with no approval (see below); and PUT /order-source and the webhook endpoint calls, which change your own application's settings. Send that user's id from GET /users in the X-User-ID header. Most reads ignore it. The exception is GET /approvals/eligible-approvers: it needs X-User-ID and the approval permission, but no open shift (see Approvals).

Mekari POS checks the user with the same roles and permissions as in Mekari POS. Approvals, returns, refunds and exchanges use the permissions of the cashier app; except for the list of eligible approvers, the user also needs an open shift at the outlet (409 SHIFT_NOT_OPEN).

Returns and Refunds of Your Own Partner Orders

POST /returns/quote, POST /returns and POST /refunds may be sent without X-User-ID, and then need no open shift, only when all three hold:

1. The order was created by your application's order source with POST /orders.
2. Every refund tender names your source's partner rail (never cash, never another payment method). A quote without refund tenders counts only when every tender of the order is on that rail.
3. No approval is needed for the operation at the outlet, and no approval_token is sent.

The call then runs as your order source (system:integration-<source_code>), as POST /orders does without a user. Anything else without X-User-ID answers 400 USER_ID_REQUIRED, and when you send X-User-ID the user is checked and needs an open shift as usual. Exchanges always need X-User-ID and an open shift. See Returns, Refunds and Exchanges.

Checks on X-User-ID

Check	Error
The header is missing or sent more than once	400 USER_ID_REQUIRED
The value is not an active user of the merchant	422 INVALID_USER
The user's role does not allow the action	403 PERMISSION_DENIED
On an outlet endpoint, the user has no access to X-Outlet-ID	403 OUTLET_FORBIDDEN

The user is recorded on what the request creates or changes (for example stock movements and loyalty point changes), exactly as if that user had done it in Mekari POS.

tip

Create a dedicated staff user for your integration with only the role it needs, so its actions are easy to find and to limit.

X-User-ID is a Mekari POS user id. It is not the same as any Mekari SSO user identifier.