Pos

@narisolutions/medusa-plugin-pos

Medusa v2 plugin that adds the product endpoints a POS (Point of Sale) app needs. Built by Nari Solutions specifically for Medusa POS — it is the backend half of that app.

Without these custom endpoints, a POS talking to Medusa's generic API has two problems: stock isn't checked automatically when adding items to a cart, and prices come back raw — not context-calculated. This plugin's /pos/* endpoints return live inventory quantities per variant and context-calculated prices (?currency_code=), plus a ?custom_fields= option to choose exactly which product fields you fetch.

Built for Medusa POS

This plugin exists to serve narisolutions/medusa-pos. Its endpoints, response shapes, and options are designed around what that app consumes — install it on the Medusa backend that Medusa POS points at.

It has no dependency on the POS app itself, so the /pos/* endpoints work for any client that wants stock-aware, price-calculated product data. Just be aware that the API is shaped by Medusa POS's needs and follows its requirements.

Requirements

• Medusa v2 ≥ 2.15.0 (@medusajs/framework and @medusajs/medusa are peer dependencies)
• Node.js ≥ 20

Installation

Setup

Add the plugin to your medusa-config.ts:

API Documentation

• docs/endpoints.md — endpoint reference with rationale and retirement criteria
• openapi.yaml — OpenAPI 3.1 spec (parameters, schemas, status codes)

Endpoints

All endpoints require an admin bearer token (Authorization: Bearer <token>).

GET /pos/products/:sales_channel_id

Returns all published products for a sales channel, with inventory quantities per variant.

The default field list covers core product/variant fields. Fields like translations.* are not included by default — opt in via ?custom_fields=translations.*.

Response: array of product objects.

---

GET /pos/product-by-barcode/:sales_channel_id/:ean

Looks up a single product by barcode value, with inventory quantities.

The :ean path parameter is matched first against the variant barcode field, then falls back to the ean field. This means physical barcodes stored in barcode work out of the box — ean is the fallback for stores that populate that field instead.

Response: single product object. Returns 404 if no variant matches either field.

---

GET /pos/health

Returns { "status": "ok" }. Requires auth. Use for backend health checks from your POS.

Authentication

Obtain a bearer token from the Medusa admin auth endpoint:

Use the returned token as Authorization: Bearer <token> on all /pos/* requests.

Frontend usage (example)

Plugin options

License

Apache-2.0