API reference · 2.0.0-draft.1
Zestt API
Integrate your ERP, point of sale or BI platform with Zestt. Orders, delivery notes, invoices, catalogs, purchasing and accounting data through a single REST API.
The Zestt API is organized around REST. It has predictable, resource-oriented URLs, accepts and returns JSON, uses standard HTTP methods and status codes, and reports every error with a stable, machine-readable code.
Suppliers integrate through the /supplier endpoints to receive orders and issue delivery notes and invoices. Restaurant chains and buyers use the remaining endpoints to read purchasing, expense and accounting data. The API key you use determines which endpoints are available to you.
Develop against the sandbox first. It contains a demo buyer, "שניצי קפה" (71148), and a demo supplier, "מאפייה אחת עשרה" (72223), already linked to each other. Use the Sandbox / Production switch at the top of the page to change the base URL and API key in every code sample.
Sandbox https://sandbox-api.zester.co.il/v2
Production https://api.zester.co.il/v2Authentication
The Zestt API authenticates requests with API keys. Send your key as a Bearer token in the Authorization header of every request.
Account administrators create keys in Zestt under Settings → Developers: create an integration, select the scopes it needs, and generate a key. The key is displayed only once, so store it securely.
Sandbox keys start with zk_test_ and production keys with zk_live_. Call GET /me to confirm the account, plan and scopes associated with a key.
- Scopes. Each endpoint lists the scope it requires. A new integration is read-only until write scopes are granted.
- IP allowlists. Supplier integrations with write scopes must restrict requests to an IP allowlist.
- Access tokens. To avoid sending the key with every request, exchange it for a 60-minute access token with
POST /oauth/token.
curl "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/me" \
-H "Authorization: Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…"const res = await fetch("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/me", {
headers: { Authorization: `Bearer ${process.env.ZESTT_API_KEY}` },
});
const me = await res.json();import os, requests
res = requests.get(
"https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/me",
headers={"Authorization": f"Bearer {os.environ['ZESTT_API_KEY']}"},
)
me = res.json()using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
"Bearer", Environment.GetEnvironmentVariable("ZESTT_API_KEY"));
var me = await http.GetStringAsync("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/me");{
"account": {
"id": "72223",
"name": "מאפייה אחת עשרה",
"type": "supplier"
},
"client": {
"name": "Priority ERP",
"environment": "sandbox",
"key_prefix": "zk_test_XXXXXXXX"
},
"scopes": [
"supplier.orders:read",
"supplier.orders:write",
"supplier.documents:write"
],
"plan": "supplier",
"features": ["webhooks", "ip_allowlist"],
"api_version": "2"
}Conventions
- Naming
- Fields and parameters use
snake_case. IDs are strings. - Money
- Decimal strings with two decimal places, such as
"496.40". The currency is given bycurrencyon the parent object. - Quantities
- Decimal strings with up to three decimal places, accompanied by a
unit. - Dates
YYYY-MM-DDfor dates, and RFC 3339 with a UTC offset for timestamps.- Enums
- Lowercase
snake_casestrings. New values may be added over time, so handle values you do not recognize. - Pagination
- List endpoints return
data,has_moreandnext_cursor. Passnext_cursorascursorto fetch the next page.limitaccepts up to 200. - Sync
- Filter with
updated_sinceto retrieve only resources that changed after a given timestamp. - Idempotency
- Send an
Idempotency-Keyheader with POST requests. A retry with the same key and body within 24 hours returns the original response instead of repeating the operation. Required when creating documents. - Request IDs
- Every response includes an
X-Request-Idheader. Include it when you contact support. - Rate limits
- Requests over the limit return
429withRetry-After,RateLimit-RemainingandRateLimit-Resetheaders.
curl "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/orders?updated_since=2026-09-10T00:00:00Z&limit=200" \
-H "Authorization: Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…"{
"data": [
{
"id": "2335619",
"status": "pending_approval",
"delivery_date": "2026-09-14",
"currency": "ILS",
"totals": { "before_vat": "496.40", "vat": "89.35", "with_vat": "585.75" },
"lines": [
{ "sku": "300", "quantity": "2.500", "unit": "kg" }
],
"updated_at": "2026-09-11T08:15:00+03:00"
}
],
"has_more": true,
"next_cursor": "eyJpZCI6IjIzMzU2MTkifQ"
}Errors
Zestt uses conventional HTTP status codes: 2xx indicates success, 4xx an error caused by the request, and 5xx an error on Zestt's side.
Error responses follow RFC 9457 (application/problem+json) and include a stable code. Handle errors by code. The title and detail fields are written for people and may change.
code | HTTP | Meaning |
|---|---|---|
unauthorized | 401 | The API key is missing or invalid. |
key_expired | 401 | The API key has passed its expiry date. |
key_revoked | 401 | The API key has been revoked. |
client_suspended | 403 | The integration has been suspended. |
ip_not_allowed | 403 | The request came from an IP address outside the integration's allowlist. |
scope_missing | 403 | The API key lacks the scope this endpoint requires. |
plan_required | 403 | The account's plan does not include this feature. See upgrade_url. |
not_found | 404 | The resource does not exist or belongs to another account. |
idempotency_conflict | 409 | The Idempotency-Key was already used with a different request body. |
conflict | 409 | The request conflicts with the resource's current state. |
precondition_failed | 412 | The resource changed after it was read (If-Match). |
file_too_large | 413 | The file exceeds 25 MB. |
validation_error | 422 | The request body or parameters are invalid. See errors. |
rate_limited | 429 | Too many requests. Retry after the time given in Retry-After. |
internal_error | 5xx | An error occurred on Zestt's side. Retry with exponential backoff. |
{
"type": "https://developers.zester.co.il/errors/validation_error",
"title": "Validation failed",
"status": 422,
"code": "validation_error",
"detail": "2 fields are invalid",
"request_id": "req_01J9KQ7X4M",
"errors": [
{
"field": "lines[1].quantity",
"code": "must_be_positive",
"message": "Quantity must be greater than 0"
},
{ "field": "delivery_date", "code": "in_the_past" }
]
}Endpoints
Each group opens with the object it manages, followed by every endpoint with its parameters, request samples in cURL, Node.js, Python and C#, and example responses. Endpoints marked Soon are defined in the contract but not yet available. To work in your own tools, download the OpenAPI contract or the Postman collection.
Getting started
Supplier API
- BuyersBuyers linked to your supplier account. List and retrieve them, set your customer number and ERP reference for each, and invite new buyers to Zestt.
- OrdersOrders that buyers place with your supplier account. List and retrieve them, then confirm, reject, schedule or acknowledge each one.
- DocumentsDelivery notes, invoices, credit notes and consolidated invoices that you issue to buyers. Create them one at a time or in bulk, and see what each buyer actually received.
- CatalogYour product catalog, product availability and price lists. Create, update and remove products, set availability, and manage prices and the buyers assigned to each price list.
Buyer APISoon
- ReferenceRead-only reference data for a buyer account: branches, purchase types, suppliers, catalog products, expense categories, expense accounts and account mappings.
- PurchasesOrders and purchase documents, such as delivery notes, invoices and credit notes, across all of the account's suppliers. Documents include their lines and export status.
- ExpensesExpense documents, which have no products, and card transactions. List, create and update expenses, and import card transactions.
- AccountingJournal lines from ZesttBox, ready for your ERP. Pull the lines approved for export, then mark them as exported.
- SalesZ-reports and item-level sales from the point of sale (POS). Send them from the POS system and list them.
- InventoryInventory counts taken at the account's branches. List counts, or retrieve a single count with its lines.
- ReportsComputed reports for food cost, purchases, expenses and profit and loss (P&L). To load data into a BI tool, use the list endpoints for the underlying records instead.
Platform
- EventsSoonA change feed of account events that you pull. It uses the same event catalog as webhooks.
- WebhooksSigned notifications that Zestt pushes to your HTTPS endpoints when events occur. Manage endpoints, send test events and redeliver past deliveries.
- FilesUpload attachments, then reference them from other resources by
file_id. Retrieve a file's metadata and a signed download URL. - ExportsSoonAsynchronous bulk exports of account data, available on the Enterprise plan. Create an export job, then poll it until the download links are ready.
- AuditSoonThe account's API request log, available on the Enterprise plan. Filter requests by date, API client and HTTP status code.
curl -O https://docs.zestt.io/openapi.yaml1. Download https://docs.zestt.io/zestt-api.postman_collection.json
2. In Postman, choose Import and select the file.
3. Set the apiKey collection variable to your sandbox key (zk_test_).