Buyers

Buyers linked to your supplier account. List and retrieve them, set your customer number and ERP reference for each, and invite new buyers to Zestt.

Endpoints

GET/supplier/buyers
GET/supplier/buyers/{buyer_id}
PATCH/supplier/buyers/{buyer_id}
POST/supplier/buyer-invitations

The Supplier buyer object

Attributes

idstringRequired

namestringRequired

tax_idstringNullable

statusstringRequired

Possible valuesactiveinactive

customer_numberstringNullable

erp_refstringNullable

branchesarray of object

Show 5 child attributesHide child attributes

idstringRequired

namestringRequired

tax_idstringNullable

addressstring

delivery_daysarray of string

Possible valuessunmontuewedthufrisat

min_orderstring · moneyNullable

Decimal amount as a string, with exactly 2 fraction digits. The currency is set by currency on the parent object.

payment_termsstringNullable

price_list_idstringNullable

created_atstring · date-time

updated_atstring · date-timeRequired

The Supplier buyer object

{
  "id": "71148",
  "name": "שניצי קפה",
  "tax_id": "000000000",
  "status": "active",
  "customer_number": "777077070",
  "erp_ref": "PRI-C-10482",
  "branches": [
    {
      "id": "71148-1",
      "name": "שניצי קפה – ראשי",
      "tax_id": "000000000",
      "address": "הברזל 30, תל אביב",
      "delivery_days": [
        "sun",
        "mon",
        "tue",
        "wed",
        "thu",
        "fri"
      ]
    }
  ],
  "min_order": "250.00",
  "payment_terms": "שוטף + 30",
  "price_list_id": "pl_1",
  "created_at": "2025-06-18T11:20:00+03:00",
  "updated_at": "2026-09-13T10:12:44+03:00"
}

List linked buyers

GET/supplier/buyers

Scopesupplier.buyers:read

Query parameters

cursorstring

Opaque cursor returned as next_cursor in a previous response. Pass it to fetch the next page.

limitinteger

Default 50 · Min 1 · Max 200

updated_sincestring · date-time

Return only items whose updated_at is strictly after this timestamp. Use it for incremental sync.

Responses

200A page of linked buyers.

dataarray of SupplierBuyerRequired

Show 12 child attributesHide child attributes

idstringRequired

namestringRequired

tax_idstringNullable

statusstringRequired

Possible valuesactiveinactive

customer_numberstringNullable

erp_refstringNullable

branchesarray of object

Show 5 child attributesHide child attributes

idstringRequired

namestringRequired

tax_idstringNullable

addressstring

delivery_daysarray of string

Possible valuessunmontuewedthufrisat

min_orderstring · moneyNullable

Decimal amount as a string, with exactly 2 fraction digits. The currency is set by currency on the parent object.

payment_termsstringNullable

price_list_idstringNullable

created_atstring · date-time

updated_atstring · date-timeRequired

next_cursorstringNullable

has_morebooleanRequired

401The API key or token is missing, invalid, expired or revoked. The code is unauthorized, key_expired or key_revoked.

Headers: X-Request-Id

403The credential is valid but is not allowed to make this request. The code is scope_missing, plan_required, ip_not_allowed or client_suspended.

429The rate limit was exceeded. Retry after the number of seconds given in Retry-After.

Headers: Retry-After RateLimit-Limit RateLimit-Remaining RateLimit-Reset

GET /supplier/buyers

curl "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyers?updated_since=2026-09-01T00:00:00%2B03:00&limit=100" \
  -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/supplier/buyers?updated_since=2026-09-01T00:00:00%2B03:00&limit=100", {
  method: "GET",
  headers: {
    Authorization: "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
  },
});
const data = await res.json();

import requests

res = requests.get(
    "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyers?updated_since=2026-09-01T00:00:00%2B03:00&limit=100",
    headers={
        "Authorization": "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
    },
)
data = res.json()

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…");
var res = await http.GetAsync("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyers?updated_since=2026-09-01T00:00:00%2B03:00&limit=100");
var data = await res.Content.ReadAsStringAsync();

Response

{
  "data": [
    {
      "id": "71202",
      "name": "ביסטרו הנמל",
      "tax_id": "000000000",
      "status": "active",
      "customer_number": "777080114",
      "erp_ref": "PRI-C-10517",
      "branches": [
        {
          "id": "71202-1",
          "name": "ביסטרו הנמל – ראשי",
          "tax_id": "000000000",
          "address": "רציף העלייה השנייה 5, חיפה",
          "delivery_days": [
            "mon",
            "wed",
            "fri"
          ]
        }
      ],
      "min_order": "300.00",
      "payment_terms": "שוטף + 60",
      "price_list_id": "pl_1",
      "created_at": "2025-10-05T09:05:00+03:00",
      "updated_at": "2026-09-06T15:31:09+03:00"
    },
    {
      "id": "71148",
      "name": "שניצי קפה",
      "tax_id": "000000000",
      "status": "active",
      "customer_number": "777077070",
      "erp_ref": "PRI-C-10482",
      "branches": [
        {
          "id": "71148-1",
          "name": "שניצי קפה – ראשי",
          "tax_id": "000000000",
          "address": "הברזל 30, תל אביב",
          "delivery_days": [
            "sun",
            "mon",
            "tue",
            "wed",
            "thu",
            "fri"
          ]
        }
      ],
      "min_order": "250.00",
      "payment_terms": "שוטף + 30",
      "price_list_id": "pl_1",
      "created_at": "2025-06-18T11:20:00+03:00",
      "updated_at": "2026-09-13T10:12:44+03:00"
    }
  ],
  "next_cursor": null,
  "has_more": false
}

{
  "type": "https://developers.zester.co.il/errors/key_expired",
  "title": "API key expired",
  "status": 401,
  "code": "key_expired",
  "detail": "The key zk_test_XXXXXXXX expired on 2026-09-10. Create a new key in Settings → Developers.",
  "instance": "/v2/supplier/buyers",
  "request_id": "req_01J9KQAG2K"
}

{
  "type": "https://developers.zester.co.il/errors/scope_missing",
  "title": "Scope missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "Client cl_01J9KQ7X4M does not have the supplier.buyers:read scope.",
  "instance": "/v2/supplier/buyers",
  "request_id": "req_01J9KQAH8M"
}

{
  "type": "https://developers.zester.co.il/errors/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited",
  "detail": "Client cl_01J9KQ7X4M exceeded 1200 requests per minute. Retry after 9 seconds.",
  "instance": "/v2/supplier/buyers",
  "request_id": "req_01J9KQAJ3N"
}

Retrieve a linked buyer

GET/supplier/buyers/{buyer_id}

Scopesupplier.buyers:read

Path parameters

buyer_idstringRequired

Responses

200The linked buyer.

idstringRequired

namestringRequired

tax_idstringNullable

statusstringRequired

Possible valuesactiveinactive

customer_numberstringNullable

erp_refstringNullable

branchesarray of object

Show 5 child attributesHide child attributes

idstringRequired

namestringRequired

tax_idstringNullable

addressstring

delivery_daysarray of string

Possible valuessunmontuewedthufrisat

min_orderstring · moneyNullable

Decimal amount as a string, with exactly 2 fraction digits. The currency is set by currency on the parent object.

payment_termsstringNullable

price_list_idstringNullable

created_atstring · date-time

updated_atstring · date-timeRequired

404The resource does not exist or belongs to another account.

GET /supplier/buyers/{buyer_id}

curl "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyers/71148" \
  -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/supplier/buyers/71148", {
  method: "GET",
  headers: {
    Authorization: "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
  },
});
const data = await res.json();

import requests

res = requests.get(
    "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyers/71148",
    headers={
        "Authorization": "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
    },
)
data = res.json()

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…");
var res = await http.GetAsync("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyers/71148");
var data = await res.Content.ReadAsStringAsync();

Response

{
  "id": "71148",
  "name": "שניצי קפה",
  "tax_id": "000000000",
  "status": "active",
  "customer_number": "777077070",
  "erp_ref": "PRI-C-10482",
  "branches": [
    {
      "id": "71148-1",
      "name": "שניצי קפה – ראשי",
      "tax_id": "000000000",
      "address": "הברזל 30, תל אביב",
      "delivery_days": [
        "sun",
        "mon",
        "tue",
        "wed",
        "thu",
        "fri"
      ]
    }
  ],
  "min_order": "250.00",
  "payment_terms": "שוטף + 30",
  "price_list_id": "pl_1",
  "created_at": "2025-06-18T11:20:00+03:00",
  "updated_at": "2026-09-13T10:12:44+03:00"
}

{
  "type": "https://developers.zester.co.il/errors/not_found",
  "title": "Buyer not found",
  "status": 404,
  "code": "not_found",
  "detail": "Buyer 71148 does not exist or is not linked to supplier 72223.",
  "instance": "/v2/supplier/buyers/71148",
  "request_id": "req_01J9KQBK5P"
}

Update a linked buyer

PATCH/supplier/buyers/{buyer_id}

Scopesupplier.buyers:write

Path parameters

buyer_idstringRequired

Headers

Request body application/json

customer_numberstring

The buyer's customer number in your ERP.

erp_refstring

A free-form reference of your choice, such as the ERP account key.

Responses

200The updated buyer.

idstringRequired

namestringRequired

tax_idstringNullable

statusstringRequired

Possible valuesactiveinactive

customer_numberstringNullable

erp_refstringNullable

branchesarray of object

Show 5 child attributesHide child attributes

idstringRequired

namestringRequired

tax_idstringNullable

addressstring

delivery_daysarray of string

Possible valuessunmontuewedthufrisat

min_orderstring · moneyNullable

Decimal amount as a string, with exactly 2 fraction digits. The currency is set by currency on the parent object.

payment_termsstringNullable

price_list_idstringNullable

created_atstring · date-time

updated_atstring · date-timeRequired

404The resource does not exist or belongs to another account.

412The If-Match value does not match the resource's current ETag.

422The request body or query parameters failed validation. See errors[] for each invalid field.

PATCH /supplier/buyers/{buyer_id}

curl -X PATCH "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyers/71148" \
  -H "Authorization: Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_number": "777077070",
    "erp_ref": "PRI-C-10482"
  }'

const res = await fetch("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyers/71148", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "customer_number": "777077070",
    "erp_ref": "PRI-C-10482"
  }),
});
const data = await res.json();

import requests

res = requests.patch(
    "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyers/71148",
    headers={
        "Authorization": "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
    },
    json={
        "customer_number": "777077070",
        "erp_ref": "PRI-C-10482"
    },
)
data = res.json()

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…");
var body = new StringContent("""
    {
      "customer_number": "777077070",
      "erp_ref": "PRI-C-10482"
    }
    """, Encoding.UTF8, "application/json");
var res = await http.PatchAsync("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyers/71148", body);
var data = await res.Content.ReadAsStringAsync();

Response

{
  "id": "71148",
  "name": "שניצי קפה",
  "tax_id": "000000000",
  "status": "active",
  "customer_number": "777077070",
  "erp_ref": "PRI-C-10482",
  "branches": [
    {
      "id": "71148-1",
      "name": "שניצי קפה – ראשי",
      "tax_id": "000000000",
      "address": "הברזל 30, תל אביב",
      "delivery_days": [
        "sun",
        "mon",
        "tue",
        "wed",
        "thu",
        "fri"
      ]
    }
  ],
  "min_order": "250.00",
  "payment_terms": "שוטף + 30",
  "price_list_id": "pl_1",
  "created_at": "2025-06-18T11:20:00+03:00",
  "updated_at": "2026-09-13T10:12:44+03:00"
}

{
  "type": "https://developers.zester.co.il/errors/not_found",
  "title": "Buyer not found",
  "status": 404,
  "code": "not_found",
  "detail": "Buyer 71148 does not exist or is not linked to supplier 72223.",
  "instance": "/v2/supplier/buyers/71148",
  "request_id": "req_01J9KQBM7Q"
}

{
  "type": "https://developers.zester.co.il/errors/precondition_failed",
  "title": "ETag mismatch",
  "status": 412,
  "code": "precondition_failed",
  "detail": "Buyer 71148 was changed after ETag \"b71148-v7\" was issued (current \"b71148-v8\"). GET the buyer again and retry.",
  "instance": "/v2/supplier/buyers/71148",
  "request_id": "req_01J9KQBN2R"
}

{
  "type": "https://developers.zester.co.il/errors/validation_error",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_error",
  "detail": "1 field is invalid",
  "instance": "/v2/supplier/buyers/71148",
  "request_id": "req_01J9KQBP4S",
  "errors": [
    {
      "field": "customer_number",
      "code": "invalid_format",
      "message": "Customer number may contain digits only, up to 20 characters"
    }
  ]
}

Invite a buyer

POST/supplier/buyer-invitations

Scopesupplier.buyers:write

Invite a new buyer to Zestt. This does not create a user. The response includes an onboarding link.

Headers

Request body application/json

business_namestringRequired

tax_idstring

contact_namestring

contact_emailstring · emailRequired

contact_phonestring

customer_numberstring

price_list_idstring

Responses

201The created invitation.

idstring

statusstring

Possible valuessentacceptedexpired

onboarding_urlstring · uri

expires_atstring · date-time

409The request conflicts with the current state. The code is conflict, or idempotency_conflict when an Idempotency-Key is reused with a different body.

422The request body or query parameters failed validation. See errors[] for each invalid field.

POST /supplier/buyer-invitations

curl -X POST "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyer-invitations" \
  -H "Authorization: Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invite-777081230" \
  -d '{
    "business_name": "קפה הגפן",
    "tax_id": "000000000",
    "contact_name": "מיכל לוי",
    "contact_email": "orders@cafe-hagefen.example",
    "contact_phone": "050-0000000",
    "customer_number": "777081230",
    "price_list_id": "pl_1"
  }'

const res = await fetch("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyer-invitations", {
  method: "POST",
  headers: {
    Authorization: "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
    "Content-Type": "application/json",
    "Idempotency-Key": "invite-777081230",
  },
  body: JSON.stringify({
    "business_name": "קפה הגפן",
    "tax_id": "000000000",
    "contact_name": "מיכל לוי",
    "contact_email": "orders@cafe-hagefen.example",
    "contact_phone": "050-0000000",
    "customer_number": "777081230",
    "price_list_id": "pl_1"
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyer-invitations",
    headers={
        "Authorization": "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
        "Idempotency-Key": "invite-777081230",
    },
    json={
        "business_name": "קפה הגפן",
        "tax_id": "000000000",
        "contact_name": "מיכל לוי",
        "contact_email": "orders@cafe-hagefen.example",
        "contact_phone": "050-0000000",
        "customer_number": "777081230",
        "price_list_id": "pl_1"
    },
)
data = res.json()

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…");
http.DefaultRequestHeaders.Add("Idempotency-Key", "invite-777081230");
var body = new StringContent("""
    {
      "business_name": "קפה הגפן",
      "tax_id": "000000000",
      "contact_name": "מיכל לוי",
      "contact_email": "orders@cafe-hagefen.example",
      "contact_phone": "050-0000000",
      "customer_number": "777081230",
      "price_list_id": "pl_1"
    }
    """, Encoding.UTF8, "application/json");
var res = await http.PostAsync("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/supplier/buyer-invitations", body);
var data = await res.Content.ReadAsStringAsync();

Response

{
  "id": "inv_01J9MZ3F6A",
  "status": "sent",
  "onboarding_url": "https://app.zester.co.il/onboarding/inv_01J9MZ3F6A",
  "expires_at": "2026-09-27T10:30:00+03:00"
}

{
  "type": "https://developers.zester.co.il/errors/conflict",
  "title": "Invitation already open",
  "status": 409,
  "code": "conflict",
  "detail": "An invitation for tax id 000000000 was sent on 2026-09-10 and is open until 2026-09-24. Resend it from the app or wait for it to expire.",
  "instance": "/v2/supplier/buyer-invitations",
  "request_id": "req_01J9KQCQ6T"
}

{
  "type": "https://developers.zester.co.il/errors/validation_error",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_error",
  "detail": "1 field is invalid",
  "instance": "/v2/supplier/buyer-invitations",
  "request_id": "req_01J9KQCR8V",
  "errors": [
    {
      "field": "contact_email",
      "code": "invalid_format",
      "message": "Must be a valid email address"
    }
  ]
}