Introduction

The Flavours API is a REST API for the Flavours POS platform. You send JSON over HTTPS, authenticate every request, and get JSON back in a consistent envelope. This section — the Guides — explains the conventions that apply to every endpoint: authentication, errors, pagination, filtering, sorting, relation loading, rate limiting, and versioning. Read it once, and the endpoint reference will read the same way everywhere.

Base URL

Every path in this reference is rooted at /api/v2. Prefix it with the base URL for the environment you are targeting:

So the products list endpoint, written GET /v2/products in the reference, is https://api.flavours.sa/dev/api/v2/products on the test environment.

Your first request

Authenticate with your credentials and call a list endpoint. Here is the products list — the endpoint we use as the running example throughout these guides:

curl "https://api.flavours.sa/dev/api/v2/products?per_page=1" \  -H "API-TOKEN: <your-key>" \  -H "X-API-Version: 2.0.0"

A successful call returns HTTP 200 and the standard envelope — a meta object describing the outcome, and a data object carrying the payload:

{
  "meta": {
    "code": 200,
    "status": "success",
    "message": "Product list retrieved successfully."
  },
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": "45dabf0e-3efa-4c64-8b8b-8f831b23d453",
        "name_en": "Cappuccino",
        "name_ar": "كابتشينو",
        "is_active": true,
        "product_category_id": 12,
        "preparation_time": 15
      }
    ],
    "per_page": 1,
    "total": 42,
    "last_page": 42
  }
}

How to read this reference

• Requests are shown as a full URL plus the headers you need. Replace the placeholder credential with your own — see Authentication.
• Responses are always wrapped in the { meta, data } envelope. meta.code mirrors the HTTP status, meta.status is success or error, and meta.message is a human-readable summary. See Errors for the error shape.
• Timestamps such as created_at and updated_at are Unix epoch milliseconds (integers), not ISO strings.
• IDs are strings (UUIDs) for most resources; a few legacy resources use integer IDs. The reference lists the exact type per field.

Start here