API Documentation

Overview

The Ritapos REST API v1 exposes store, franchise, product, and order data as JSON.

All requests use HTTPS. Base URL: https://app.ritapos.com

Authentication

Store and product endpoints are public; no Authorization header is required.
Franchise and order endpoints require an API key created in the Ritapos app: Authorization: Bearer YOUR_API_KEY
Do not send the API key in query parameters or the request body; only the Authorization header is accepted.
Keys are scoped to the store they were created for. On franchise endpoints the key must belong to a store in that franchise. The read-only role is sufficient for these read endpoints.

Response envelopes

Store and product endpoints: { "status": true|false, "data": ... }. Business failures often still return HTTP 200; check the status field.
Franchise endpoints use the store envelope on success: { "status": true|false, "data": ... }. Auth and rate-limit failures use the order envelope: { "status": "error", "message" } with HTTP 401, 403 or 429.
Order endpoints: { "status": "ok"|"error", "data" | "message" }. Errors use real HTTP status codes (400, 401, 403, 404, 429, 500).

Order and franchise read requests are limited to 60 requests per minute per API key + IP. Exceeding the limit returns HTTP 429 with Retry-After.

Endpoints

Get store

GET /api/v1/stores/:storeId

No authentication required

Returns the store for the given storeId. The path parameter may be the store _id or guid.

Parameters

Name	In	Required	Description
`storeId`	path	required	Store _id or guid

Notes

The response includes only these fields: _id, guid, name, alias, logoUrl, description, city, country, photos.

Example request

curl -sS 'https://app.ritapos.com/api/v1/stores/Ey29a22Wa5cxxq1r4o'

Success response

{
  "status": true,
  "data": {
    "_id": "Ey29a22Wa5cxxq1r4o",
    "guid": "...",
    "name": "Example Cafe",
    "alias": "example-cafe",
    "logoUrl": "https://...",
    "description": "...",
    "city": "Istanbul",
    "country": "TR",
    "photos": [
      {
        "imageId": "...",
        "imageUrl": "https://..."
      }
    ]
  }
}

Error response

{
  "status": false,
  "data": "Store with storeId Ey29a22Wa5cxxq1r4o not found."
}

Get franchise

GET /api/v1/franchises/:franchiseId

Authentication required

Returns the franchise for the headquarters store _id. The path is not a guid; it is the franchiseId field (the HQ store Mongo _id).

Parameters

Name	In	Required	Description
`franchiseId`	path	required	Headquarters store Mongo _id (franchiseId field)

Notes

The response includes only these fields: _id, guid, name, alias, logoUrl, description, city, country, photos.
The API key must belong to a store in this franchise. Otherwise the response is HTTP 403.

Example request

curl -sS 'https://app.ritapos.com/api/v1/franchises/x7Km9Pq2nR4wT6yLz' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Success response

{
  "status": true,
  "data": {
    "_id": "x7Km9Pq2nR4wT6yLz",
    "guid": "...",
    "name": "Example Franchise",
    "alias": "example-franchise",
    "logoUrl": "https://...",
    "description": "...",
    "city": "Istanbul",
    "country": "TR",
    "photos": [
      {
        "imageId": "...",
        "imageUrl": "https://..."
      }
    ]
  }
}

Error response

{
  "status": "error",
  "message": "Unauthorized"
}

List franchise stores

GET /api/v1/franchises/:franchiseId/stores

Authentication required

Lists member stores of the franchise. The path may be the headquarters _id or a store guid. Results are sorted by name descending.

Parameters

Name	In	Required	Description
`franchiseId`	path	required	Headquarters store _id or a store guid
`isActive`	query	optional	true or false. If omitted, no active filter is applied
`isShownInRewarita`	query	optional	true or false. If omitted, no Rewarita visibility filter is applied

Notes

Returned fields: _id, isActive, name, description, street, city, country, location, phone, link, franchiseOrder, photos. guid is not included.
The API key must belong to a store in this franchise. Otherwise the response is HTTP 403.

Example request

curl -sS 'https://app.ritapos.com/api/v1/franchises/x7Km9Pq2nR4wT6yLz/stores?isActive=true&isShownInRewarita=true' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Success response

{
  "status": true,
  "data": [
    {
      "_id": "x7Km9Pq2nR4wT6yLz",
      "isActive": true,
      "name": "Example Branch",
      "description": "...",
      "street": "...",
      "city": "Istanbul",
      "country": "TR",
      "location": "41.0082,28.9784",
      "phone": "+90...",
      "link": {
        "instagram": "https://...",
        "website": "https://..."
      },
      "franchiseOrder": 1,
      "photos": [
        {
          "imageId": "...",
          "imageUrl": "https://..."
        }
      ]
    }
  ]
}

Error response

{
  "status": "error",
  "message": "Unauthorized"
}

List store products

GET /api/v1/products/:storeId

No authentication required

Lists all products for the given store. The path parameter is a store id (storeId), not a product id.

Parameters

Name	In	Required	Description
`storeId`	path	required	Store id

Notes

The response is an array of product documents for that store.

Example request

curl -sS 'https://app.ritapos.com/api/v1/products/Ey29a22Wa5cxxq1r4o'

Success response

{
  "status": true,
  "data": [
    {
      "_id": "...",
      "storeId": "Ey29a22Wa5cxxq1r4o",
      "title": "Latte",
      "priceOut": 120,
      "tax": 0.1,
      "isVisible": true,
      "isVisibleInQrMenu": true
    }
  ]
}

Error response

{
  "status": false,
  "data": "storeId is missing."
}

List QR menu products

GET /api/v1/products/:storeId/qr-menu

No authentication required

Returns products visible in the QR menu (isVisibleInQrMenu: true), sorted by order then title.

Parameters

Name	In	Required	Description
`storeId`	path	required	Store id
`filter`	query	optional	If set to image, only products with imageId or imageUrl are returned

Notes

Example: /api/v1/products/Ey29a22Wa5cxxq1r4o/qr-menu?filter=image

Example request

curl -sS 'https://app.ritapos.com/api/v1/products/Ey29a22Wa5cxxq1r4o/qr-menu'

Success response

{
  "status": true,
  "data": [
    {
      "_id": "...",
      "storeId": "Ey29a22Wa5cxxq1r4o",
      "title": "Espresso",
      "isVisibleInQrMenu": true,
      "imageUrl": "https://..."
    }
  ]
}

Error response

{
  "status": false,
  "data": "storeId is missing."
}

List store orders

GET /api/v1/orders/store/:storeId

Authentication required

Lists orders for the given store within a date range. The API key must match the store.

Parameters

Name	In	Required	Description
`storeId`	path	required	Store id (must match the API key store)
`startDate`	query	optional	ISO-8601 start date. If both dates are omitted, the last 7 days are used
`finishDate`	query	optional	ISO-8601 end date. If only one is set, the other is ±7 days
`limit`	query	optional	Default 100, maximum 10000

Notes

The date range may not exceed 90 days.
startDate must not be after finishDate.

Example request

curl -sS 'https://app.ritapos.com/api/v1/orders/store/4Bo8zuMSkWSwvtrwi?startDate=2026-04-01&finishDate=2026-05-01&limit=100' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Success response

{
  "status": "ok",
  "data": [
    {
      "_id": "jatmsKpEXq5gepTK3",
      "storeId": "4Bo8zuMSkWSwvtrwi",
      "number": 42,
      "type": 1,
      "paymentType": "cash",
      "paymentTypeLabel": {
        "en": "Cash",
        "tr": "Nakit",
        "es": "Efectivo",
        "de": "Bar"
      },
      "priceOutTotal": 250,
      "grossTotalWithTax": 250,
      "createdAt": "2026-04-15T12:00:00.000Z"
    }
  ]
}

Error response

{
  "status": "error",
  "message": "Unauthorized"
}

Get a single order

GET /api/v1/orders/:orderId

Authentication required

Returns one order by its _id. The response includes storeName. The API key must belong to the order's store.

Parameters

Name	In	Required	Description
`orderId`	path	required	Order _id

Example request

curl -sS 'https://app.ritapos.com/api/v1/orders/jatmsKpEXq5gepTK3' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Success response

{
  "status": "ok",
  "data": {
    "_id": "jatmsKpEXq5gepTK3",
    "storeId": "4Bo8zuMSkWSwvtrwi",
    "storeName": "Example Cafe",
    "number": 42,
    "type": 1,
    "paymentType": "cash",
    "paymentTypeLabel": {
      "en": "Cash",
      "tr": "Nakit",
      "es": "Efectivo",
      "de": "Bar"
    },
    "grossTotalWithTax": 250,
    "createdAt": "2026-04-15T12:00:00.000Z"
  }
}

Error response

{
  "status": "error",
  "message": "Not found"
}

Order fields

Main fields returned in order responses:

_id
storeId
storeName (single-order endpoint only)
number
type
paymentType
paymentTypeLabel ({ en, tr, es, de })
paymentProvider
tip
serviceCharge
priceInTotal
priceOutTotal
grossTotalWithTax
grossTotalWithoutTax
grossTax
netTotalWithTax
netTotalWithoutTax
netTax
discount
discountNote
note
tableId
roomId
courierId
customerId
externalId
createdAt
updatedAt
completedAt
scheduledAt

Order type values

0. PENDING
1. COMPLETED
2. CANCELED
3. SOFT_REMOVED
4. LOSS
5. ON_ACCOUNT

We'll Call You