API Documentation

Overview

The Ritapos REST API v1 exposes store, 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.
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. 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.
Order endpoints: { "status": "ok"|"error", "data" | "message" }. Errors use real HTTP status codes (400, 401, 403, 404, 429, 500).

Order 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

Example request

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

Success response

{
  "status": true,
  "data": {
    "_id": "Ey29nwg2WB5cMvh2o",
    "guid": "...",
    "name": "Example Cafe",
    "alias": "example-cafe"
  }
}

Error response

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

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/Ey29nwg2WB5cMvh2o'

Success response

{
  "status": true,
  "data": [
    {
      "_id": "...",
      "storeId": "Ey29nwg2WB5cMvh2o",
      "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/Ey29nwg2WB5cMvh2o/qr-menu?filter=image

Example request

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

Success response

{
  "status": true,
  "data": [
    {
      "_id": "...",
      "storeId": "Ey29nwg2WB5cMvh2o",
      "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