Guides

Start here

What Tillstack isQuickstartAuthentication

Getting data in

How data gets inSync API referenceYour payment providerReconciliation

Building on it

Terminal integrationSales, returns, shiftsCatalog and stockInventory ledgerCatalog layout on devicesProduct picturesReportsWebhooksEmail and EngageRunning without our UI

Using the console

Operator portalMerchant guide

Reference

Sandbox, OpenAPI, PostmanErrors and limitsSecurity

Building on it

Product pictures

A merchant gives a product one picture. The terminal asks for it at whatever size it wants to draw, in the same way the Graph API lets you ask for a profile picture by width/height.

For the terminal#

Every catalog item (GET /v1/terminal/catalog, /v1/merchants/{id}/catalog, barcode lookup) carries imageId (null = no picture).

GET /v1/images/{imageId}?w=200&h=200&fit=cover&fmt=webp
Param Meaning
w, h Target size in pixels. Either or both. Rounded up to a multiple of 8 and capped at 1600, so a picture has few distinct sizes.
fit contain (default): fits inside the box, keeps its shape. cover with both w and h: crops to exactly that shape.
fmt webp (default), jpg or png. Pick jpg for very old Android WebViews.
  • No auth header. The imageId is an unguessable token naming one picture, so the URL is safe to hand to an image loader or CDN.
  • Never upscaled. Asking for more than we hold returns the largest size we have (the stored original is at most 2048 px).
  • Cache it forever. Responses carry Cache-Control: public, max-age=31536000, immutable and an ETag. A changed picture gets a new imageId, and the product's variants reappear in the next catalog delta, so a terminal that keys its image cache on imageId never shows a stale picture and never needs to revalidate.
  • A removed picture arrives as imageId: null; the old address then answers 404.

For the console / API#

  • POST /v1/merchants/{id}/products/{productId}/image: multipart field file, JPEG/PNG/WebP, up to 6 MB and 8000 px a side. Replaces any existing picture. Needs catalog:write.
  • DELETE /v1/merchants/{id}/products/{productId}/image.
  • 503 with code unavailable when the server has no storage configured.

How it works#

The upload is decoded, turned upright (EXIF orientation), stripped of all metadata (so phone GPS never leaves the server) and re-encoded as a WebP no larger than 2048 px: that is the only copy kept. Each requested size is rendered from it on first request and stored beside it, so the second request is a file read. At most four renders run at once, so a burst of new sizes queues rather than starving the sales API.

Storage is S3-compatible (MinIO locally, any S3 later). The bucket is never public: pictures leave only through /v1/images, the same rule that keeps owl-express's MinIO internal.

Setting
Storage__Endpoint e.g. minio:9000. Empty = pictures disabled
Storage__AccessKey, Storage__SecretKey
Storage__Bucket default tillstack (created on first use)
Storage__UseSsl true for HTTPS endpoints

Locally: docker compose up -d minio (console on :9003), then set the variables above with endpoint localhost:9002.

Not done#

  • One picture per product (not per variant); no gallery.
  • Orphaned renders are deleted with their picture, but a crash between the database write and the delete leaves a few kilobytes behind; there is no sweeper.
  • No rate limit on /v1/images beyond the render concurrency cap. Put Cloudflare in front in production (the responses are built for it).