MiniTill Developer

Public API Reference

Connect external systems to MiniTill using the REST API. All endpoints are authenticated via API key.

Download OpenAPI YAML Download Postman Collection Download Postman Environment

Quick Start

Log in to MiniTill Back Office and go to Settings → Developer / API.
Create an API key with the scopes your integration needs.
Copy the key immediately — it is shown only once.
Include the key in the X-Api-Key header of every request.

curl -H "X-Api-Key: YOUR_API_KEY" \
     "https://minitill.co.nz/api/v1/categories"

API access requires a paid MiniTill plan. Free plan accounts cannot issue active API keys.

Base URL

https://minitill.co.nz

All API endpoints are relative to this base URL.

Authentication

Every request must include your API key in the X-Api-Key header.

X-Api-Key: YOUR_API_KEY

API keys are business-scoped. A key can only access data belonging to the business it was created for. Do not share API keys with untrusted parties. Revoke any key that may have been exposed.

API Key Scopes

Each API key is granted a set of scopes. Requests that require a scope not held by the key receive a 403 Forbidden response.

Grant only the scopes each integration needs — follow the principle of least privilege.

Scope	Description
catalogue:read	Read products, categories, and modifier groups
catalogue:write	Create and update products, categories, and modifier groups
stores:read	Read store information
stores:write	Update store settings
orders:read	List and read orders
orders:write	Create orders
payments:read	Read payment records
payments:write	Record payments
customers:read	List and read customer profiles
customers:write	Create and update customer profiles
loyalty:read	Read loyalty point balances
loyalty:write	Adjust loyalty points
gift_cards:read	List and read gift cards
gift_cards:write	Issue and redeem gift cards
vouchers:read	List voucher templates and issued vouchers
vouchers:write	Issue and redeem vouchers
reports:read	Read sales reports and daily summaries

Idempotency

Certain mutation endpoints (such as creating an order or redeeming a gift card) support the Idempotency-Key header. Sending the same key on a retry returns the original response without creating a duplicate.

Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Use a UUID (v4) as the idempotency key. Keys are scoped to your business and expire after 24 hours. Endpoints that support idempotency are marked in the Postman collection and OpenAPI spec.

Rate Limits

API requests are rate-limited per business per day. Your plan determines the daily request limit. When the limit is reached, subsequent requests return 429 Too Many Requests.

The current usage and limit are shown in Back Office under Settings → Billing & Plan.

Error Responses

All error responses use the RFC 7807 Problem Details format.

{
  "type": "https://minitill.app/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key does not have the required scope: orders:write."
}

Status	Meaning
400	Malformed request body or query
401	Missing or invalid API key
403	API key lacks required scope
404	Resource not found
409	Conflict (e.g. duplicate idempotency key with different body)
422	Validation error — check the detail field
429	Daily rate limit exceeded
500	Internal server error — retry with backoff

API Groups

The public API is organised into the following groups. Internal MiniTill routes (POS, KDS, Back Office operations) are not part of the public API contract and are not documented here.

Catalogue

Manage products, categories, and modifier groups.

catalogue:readcatalogue:write

GET/api/v1/categories
GET/api/v1/products
GET/api/v1/modifier-groups

Stores

Read store information.

stores:read

GET/api/v1/stores
GET/api/v1/stores/:id

Orders

Place and retrieve orders.

orders:readorders:write

GET/api/v1/orders
POST/api/v1/orders

Payments

Read payment records.

payments:read

GET/api/v1/payments

Customers

Manage customer profiles.

customers:readcustomers:write

GET/api/v1/customers
GET/api/v1/customers/:id

Loyalty

Adjust loyalty points for customers.

loyalty:readloyalty:write

POST/api/v1/customers/:id/loyalty-adjustments

Gift Cards

Issue, list, and redeem gift cards.

gift_cards:readgift_cards:write

GET/api/v1/gift-cards
POST/api/v1/gift-cards/redeem

Vouchers

Manage voucher templates and issued vouchers.

vouchers:readvouchers:write

GET/api/v1/voucher-templates
POST/api/v1/vouchers/redeem

Sales Reports

Read sales and operational report summaries.

reports:read

GET/api/v1/reports/sales
GET/api/v1/reports/customers
GET/api/v1/reports/sales-by-time
GET/api/v1/reports/menu-profitability
GET/api/v1/reports/labour-productivity
GET/api/v1/reports/order-channels
GET/api/v1/reports/revenue-leakage
GET/api/v1/reports/customer-retention
GET/api/v1/reports/product-affinity
GET/api/v1/reports/till-variance
GET/api/v1/reports/payment-reliability
GET/api/v1/reports/marketplace-reconciliation
GET/api/v1/reports/waste
GET/api/v1/reports/inventory-health
GET/api/v1/reports/sales-forecast

Inventory

Read stock and waste records with catalogue:read. Mutations require catalogue:write and an Idempotency-Key header (8-200 characters); keys are retained for the record lifetime and reuse with a different operation, stock item, or payload returns 409 Conflict.

catalogue:readcatalogue:write

GET/api/v1/inventory/stock-items
POST/api/v1/inventory/stock-items
GET/api/v1/inventory/stock-items/:id
POST/api/v1/inventory/stock-items/:id/ledger
GET/api/v1/inventory/waste-events
POST/api/v1/inventory/waste-events
GET/api/v1/inventory/waste-events/:id
POST/api/v1/inventory/waste-events/:id/reverse

Note on internal routes

MiniTill has internal routes for POS terminals, KDS displays, and Back Office operations. These are not part of the public API contract, are not included in the OpenAPI spec or Postman collection, and may change without notice.

Questions? Contact support.