Skip to content
TechTur POS

API quickstart

Base URL: https://pos.techtursolutions.com (sandbox and live share it; the token decides which businesses you reach).

Conventions

  • Versioning — paths start with /api/v1. Breaking changes ship as /api/v2; see Versioning.
  • Responses — { "data": … }; lists add "nextCursor". Pass ?cursor=<nextCursor>&limit=… (max 200) for the next page.
  • Errors — { "error": { "code", "message", "details?", "requestId" } }. See Error handling.
  • Money — decimal strings, ZAR. Prices are shown as the business displays them: VAT-inclusive when the business has pricesIncludeTax: true (the South African norm).
  • Request tracing — every response carries x-request-id; send your own X-Request-Id (8–64 chars) to correlate logs.
  • Idempotency — see each endpoint; the SDK sends an Idempotency-Key on every POST and reuses it on retries.
  • Rate limits — 300 requests/minute per token by default; 429 with a retry-after header when exceeded.

The calls most connectors need

Task Method & path Scope
Who am I GET /api/v1/platform/me any token
Business profile and locations GET /api/v1/businesses/{id} business:read
List products GET /api/v1/businesses/{id}/products?updatedSince=… products:read
Barcode / SKU lookup GET /api/v1/businesses/{id}/barcodes/{code} products:read
Upsert products by external ID PUT /api/v1/businesses/{id}/sync/products products:write
External ID mappings GET /api/v1/businesses/{id}/mappings?entityType=variant products:read
Stock levels GET /api/v1/businesses/{id}/stock?variantId=… inventory:read
Stock adjustment POST /api/v1/businesses/{id}/stock/adjustments inventory:write
Submit an order POST /api/v1/businesses/{id}/orders orders:write
Get order (POS id or ext:<yourRef>) GET /api/v1/businesses/{id}/orders/{orderId} orders:read
Pay / cancel / fulfil an order PATCH /api/v1/businesses/{id}/orders/{orderId} orders:write
List sales GET /api/v1/businesses/{id}/sales orders:read
Refund a sale POST /api/v1/businesses/{id}/sales/{saleId}/refunds orders:write
Customers GET/POST /api/v1/businesses/{id}/customers customers:*
Sales summaries GET /api/v1/businesses/{id}/reports/sales?from&to reports:read

cURL

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://pos.techtursolutions.com/api/v1/businesses/$BIZ/stock?limit=50"

TypeScript

import { TechturPos, TechturPosError } from "@techtur-pos/sdk";

const pos = new TechturPos({ baseUrl: "https://pos.techtursolutions.com", clientId: process.env.CLIENT_ID!, clientSecret: process.env.CLIENT_SECRET! });
try {
  for await (const level of pos.inventory.all(businessId)) console.log(level.variant.sku, level.available);
} catch (e) {
  if (e instanceof TechturPosError) console.error(e.code, e.message, e.requestId);
}

SDK resources: health, businesses, products (list, all, get, byBarcode, sync, syncAll), mappings, inventory (levels, all, adjust), orders (create, get, getByExternalRef, markPaid, cancel, setFulfilment), sales, customers, platform (createLaunchTicket, businesses, resolveBusiness, reportMetrics), plus createPkcePair, buildAuthorizeUrl, exchangeCode, refreshToken, verifyWebhook, signWebhookPayload.

Python

import requests
r = requests.get(f"{BASE}/api/v1/businesses/{biz}/products", headers={"Authorization": f"Bearer {token}"}, timeout=20)
r.raise_for_status()
for p in r.json()["data"]:
    print(p["name"], [v["price"] for v in p["variants"]])

PHP

$ch = curl_init("$base/api/v1/businesses/$biz/orders");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer $token", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["externalRef" => "order-1001", "lines" => [["externalVariantId" => "sku-42", "quantity" => 1]]])]);
$order = json_decode(curl_exec($ch), true)["data"];