lma39ol

Merchant API Reference

Everything a store needs to integrate lma39ol: collecting verified reviews, displaying a trust badge, and reading your merchant billing status. Machine-readable spec: /openapi.json (OpenAPI 3.0, importable into Postman/Insomnia).

Authentication

Two credential types exist. Your storefront's backend should use an API key; the merchant dashboard uses a JWT session.

Credential	Header	Used for
API key	`x-api-key: lma_...`	Server-to-server calls from your own store (ratings, review invitations, billing status).
JWT session	`Authorization: bearer <token>`	Dashboard actions: issuing/revoking API keys, checkout, updating your account.

Generate an API key from an authenticated dashboard session:

curl -X POST http://localhost:3001/merchants/api-keys \
  -H "Authorization: bearer <jwt>" -H "Content-Type: application/json" \
  -d '{"label":"Storefront backend","scopes":["ratings:read","ratings:write"]}'

The full key is only ever returned once, in this response — store it securely.

Ratings

Every score field is optional and rated 0-5; submit whichever your integration collects. Authenticated merchant submissions are always private buyer-risk ratings, never public self-reviews — see review invitations for collecting public reviews.

POST/ratingsAPI key: ratings:write

Record a private rating about a buyer for your own risk screening.

curl -X POST http://localhost:3001/ratings \
  -H "x-api-key: lma_..." -H "Content-Type: application/json" \
  -d '{"orderReference":"ORD-1042","productQuality":5,"deliveryTime":4,"comment":"Smooth transaction"}'

GET/ratings?page=1&limit=20API key: ratings:read

Paginated list, filterable by from/to date range.

GET/ratings/buyer-riskAPI key: ratings:read

Cancellation/return rate and a low/medium/high risk band for a buyer.

PATCH/ratings/:ratingId/replyJWT, merchant-owned only

Publicly reply to a review left about your store.

Review invitations & QR codes

The only way to collect a public, order-linked review: issue a one-time invitation per delivered order, print its QR code on the receipt, and let the buyer scan it later at their own pace.

POST/review-invitationsAPI key: ratings:write

curl -X POST http://localhost:3001/review-invitations \
  -H "x-api-key: lma_..." -H "Content-Type: application/json" \
  -d '{"orderReference":"ORD-1042","buyer":{"firstName":"Amina","lastName":"K.","email":"amina@example.com"},"expiresInDays":14}'

Response includes reviewUrl and a printable qrCodeDataUrl (base64 PNG). One invitation per order — reissuing for the same orderReference returns 409.

GET/review-invitations?page=1&limit=20API key: ratings:read

GET/public/review-invitations/:tokennone — buyer-facing

POST/public/review-invitations/:token/reviewnone — buyer-facing

Your storefront never calls these directly — the QR code points buyers straight at the hosted page /review/:token, which calls them for you.

Trust badge

GET/trust/merchants/:merchantIdnone — public, embeddable

Fetchable directly from your storefront's frontend (your customers' browsers) — no API key needed. Returns the aggregated overall score, per-dimension breakdown, and a confidence band (limited / growing / established) based on review volume.

GET/merchants/me/trustJWT

The same data, for your own dashboard.

Billing

GET/public/payments/plansnone

Public pricing catalog.

GET/payments/subscriptionAPI key or JWT

Returns { planId, status, isActive, currentPeriodEnd, cancelAtPeriodEnd } — useful for gating features in your own integration on plan status.

POST/payments/checkout-sessionsJWT

POST/payments/portal-sessionsJWT

Redirect your dashboard user to the returned URL to subscribe or manage billing via Stripe's hosted pages.

Errors & rate limits

Every response is JSON with a success boolean. Failures include errorCode, a human-readable message, and sometimes a per-field errors object.

{ "success": false, "errorCode": "A0013", "message": "unauthorized !" }

API-key authenticated ratings endpoints are limited to 100 requests/hour per key; exceeding it returns 429.