Guide 1865 min readUpdated 2026-10-19

The YallaBuy Public API

The YallaBuy Public API lets your own applications read your store's data and safely perform operations on it — whether you build the integration yourself or hire a developer. This guide covers everything: authentication, calling operations, and handling errors and limits.

On this page

1.Overview — an interface for YOUR applications

The Public API is the official data gateway to your store: products, orders, inventory, customers, analytics and more. Any tool you choose can use it — an ERP, a custom integration script, your own dashboard, or any external service that lets you connect APIs.

Every operation lives under /api/v1, authenticated with a Bearer key starting with ybapi_.
A key binds only stores you CURRENTLY own; the effective store set is recomputed server-side on every request.
Responses are uniform: data inside `data`, errors inside `error` with a stable code and a request id.

2.Base URL and versioning

The base URL is https://yallabuy.app/api/v1 — every path starts with /api/v1 to pin the first API version. Any future breaking change ships in a new version; the current one stays stable.

3.Authentication with a ybapi_ key

Every request must carry an Authorization header: Bearer followed by your key. You create keys in the dashboard (Settings → API Keys); the full secret is shown EXACTLY ONCE at creation or rotation — afterwards only a verification hash is stored and recovery is impossible.

Authentication failures always answer the ONE stable message: "The API credential is invalid, expired, or revoked" — an unknown key and a revoked key are indistinguishable, so there is nothing to enumerate.
Selling or deactivating a store removes it from your keys' scope on the very next request.
Repeated failed authentication is throttled per source address — once the bucket exhausts, responses become 429.

4.Scopes and the high-risk flag

Each key carries a scope list defining what it may do. Scopes are labelled in Arabic and English in the key-creation screen; this is the full list:

Scope	Grants	High risk?
store:read	Read store profile, plan and settings	No
products:read	Read products and catalog	No
products:write	Create, update and archive products	No
inventory:read	Read stock and movements	No
inventory:write	Receive/adjust stock and run bulk operations	Yes
orders:read	Read orders and returns	No
orders:write	Create and dispatch orders, transition status, cancellation decisions, kitchen and tables, returns and refund evidence	Yes
customers:read	Read customers (requires the CRM module on)	No
customers:write	Create, update and delete customers (phone immutable after creation)	No
analytics:read	Sales analytics and product performance	No
finance:read	Profit & loss, expenses and POS shifts	No
marketing:read	Marketing, coupons and promotions	No
marketing:write	Create, update and delete coupons, promotions and bundles	No
storefront:write	Apply storefront designs (revision-CAS protected)	Yes

Some scopes are published as RESERVED (webhooks:manage, settings:write, staff:read, products:bulk) and are not live — creating a key with them is rejected. This guide documents only what actually works.

5.Creating, rotating and revoking keys

Open Settings → API Keys and press "New key".
Name the key and tick the authorized stores (one or more of your CURRENT stores).
Pick scopes — choosing a high-risk scope requires confirming "Allow high-risk operations".
Optionally set an expiry date, then create — copy the secret immediately into a safe place; it is never shown again.
To rotate, press "Rotate" on the key — you get a new secret and the old one dies instantly. To terminate, press "Revoke" — permanent.

The key list shows each key's name, prefix, status (Active/Revoked/Expired), created date and last-used time. Only the PREFIX is ever displayed — the full secret is not stored by YallaBuy at all.

6.Request and response conventions

Write calls (POST/DELETE) take a JSON body with Content-Type: application/json — capped at 64 KB.
Any authorization field in a body (store_id, tenant_id, confirmation_token, …) is REJECTED with 400 — store identity comes from the key, never from the client.
Every response carries X-Request-Id and Cache-Control: no-store — quote the request id when contacting support.
Success returns { "data": … }; lists additionally return { "pagination": { "next_cursor", "has_more" } }.
Unknown paths and unsupported HTTP methods answer a stable 404 — the API has no hidden surfaces.

7.Pagination and filtering

Lists paginate with an opaque position cursor: the first call without a cursor returns page one; if more rows exist, pagination.next_cursor carries the next position — send it back verbatim. A cursor is NOT a capability — it carries a page position only: a malformed or out-of-range marker answers 400, and even a well-formed one can only ever page through the same authorized list (filters and permissions are re-applied on every request). Page size is controlled with limit (or per_page as an alias), bounded per endpoint.

8.Idempotency for sensitive writes

Four writes REQUIRE an Idempotency-Key header: create order, inventory receive, inventory adjust, and create return. The law: a key binds to the FIRST operation executed with it — any retry with the same key returns the original outcome in full with replayed: true and never executes twice, even if the body differs (the key is not a body fingerprint). So: generate a fresh unique key for every new operation and never reuse a spent key for a different one. Safe retries mean you can replay after any network failure without duplication risk.

9.Rate limits and handling 429

Class	Limit	Applies to
Standard reads	60/min per key	Flat lists and store reads
Heavy reads	20/min per key	Analytics, reporting, universal search, Customer 360
Standard writes	20/min per key	Product archive, kitchen status
High-risk writes	10/min per key	Transitions, receive/adjust, returns, tables, design apply
Bulk writes	5/min per key	Bulk inventory preview/apply
Failed authentication	20/min per source	Anti-stuffing

Counters are shared platform-wide (not per server instance). A 429 response carries a Retry-After header with the suggested wait — respect it instead of hammering.

10.Error codes and troubleshooting

Every error uses the same envelope: { "error": { "code", "message", "request_id" } }. Codes are a closed, stable catalog — they never rename:

Code	HTTP	Meaning
VALIDATION_ERROR	400	Invalid input (query/body/identifier)
UNAUTHENTICATED	401	Missing, malformed, expired or revoked key
SCOPE_INSUFFICIENT	403	The key lacks the required scope
FORBIDDEN	403	High-risk operation from a flag-less key
NO_AUTHORIZED_STORE	403	No owned+active store remains in the key's scope
FEATURE_TURNED_OFF	403	A required feature is off for the store (e.g. CRM)
STORE_SUSPENDED	403	Reserved code: the store is not currently active
PLAN_REQUIRED	403	The current plan does not include the capability
NOT_FOUND	404	Unknown path OR a resource outside the key's stores — identical shape, no existence leak
CONFLICT	409	General state conflict — including an idempotency key replayed with a different payload
IDEMPOTENCY_CONFLICT	409	Reserved code: key conflicts currently surface as CONFLICT
INVALID_STATE_TRANSITION	409	An illegal state move (e.g. returning a completed order)
PREVIEW_STALE / DESIGN_STALE / PROPOSAL_CHANGED	409	The design revision changed — re-propose using the returned details
MULTI_STORE_UNSUPPORTED	400	A multi-store key aimed at a single-store operation — bind the key to one store
RANGE_TOO_LARGE	400	Date window wider than the cap (366 days for reporting)
PAYLOAD_TOO_LARGE	413	Request body over 64 KB on a write
RATE_LIMITED	429	Bucket exhausted — honor Retry-After
API_DISABLED	503	The API is currently disabled platform-wide — the same reply for any request
INTERNAL	500	Unexpected internal error — retry gently and contact support with the request id

11.Endpoint reference with copy-paste examples

The sections that follow are the complete reference for every LIVE surface (the root diagnostic + 48 reads + 31 writes + 5 design reads) — each with its method, path, scope and rate class, a one-click copyable cURL command, an example response, and a table of the error codes that endpoint actually answers. Anything not listed here does not exist in the API.

12.Root diagnostic — GET /api/v1

GET /api/v1 — the diagnostic echo: identifies the key and its effective scopes; the fastest check that a key works. Auth: Bearer. 60/min (failed auth throttles at 20/min per source).

cURL

curl -s "https://yallabuy.app/api/v1" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "api": "yallabuy",
  "version": "v1",
  "phase": "2-writes",
  "authenticated": true,
  "credential_id": "…",
  "scopes": [
    "store:read",
    "orders:read"
  ],
  "store_ids": [
    "…"
  ],
  "effective_store_count": 2,
  "high_risk_enabled": false,
  "origin": "API",
  "causation_id": "req_018f…",
  "request_id": "req_018f…"
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key — one stable description
RATE_LIMITED	repeated auth failures from one source
API_DISABLED	API currently disabled platform-wide

13.Store and its settings (8)

GET /api/v1/store — Core store profile: name, business type, plan and status. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/store" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/store/settings — Current store settings (currency, timezone, ordering, contact). Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/store/settings" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/store/features — State of the store feature keys. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/store/features" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/store/design — Current storefront design context (direction, colors, content). Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/store/design" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/store/setup — Store setup readiness: completed and missing steps. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 20/min per key (API_READ_HEAVY).

cURL

curl -s "https://yallabuy.app/api/v1/store/setup" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/store/builder — AI store-builder context. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 20/min per key (API_READ_HEAVY).

cURL

curl -s "https://yallabuy.app/api/v1/store/builder" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/analytics/overview — Overview dashboard: today/week/month numbers. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 20/min per key (API_READ_HEAVY).

Parameter	Type	Constraints
«period»	enum	today \| yesterday \| last7 \| last30 \| thisMonth \| lastMonth \| custom
«from»	string	—
«to»	string	—

cURL

curl -s "https://yallabuy.app/api/v1/analytics/overview" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/action-center — Action center: items needing attention. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 20/min per key (API_READ_HEAVY).

Parameter	Type	Constraints
«cart_hours»	integer	min 1 · max 720

cURL

curl -s "https://yallabuy.app/api/v1/action-center" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

14.Products and catalog (6)

GET /api/v1/products — Paginated product list with search and filters; updated_since for delta-sync. Auth: Bearer. Required scope products:read — Read products and categories. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«search»	string	len ≥ 1 · len ≤ 100
«category_id»	UUID	—
«is_available»	boolean	—
«updated_since»	string	—
«cursor»	string	position marker from pagination.next_cursor

cURL

curl -s "https://yallabuy.app/api/v1/products?limit=10" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "…": "…"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks products:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/products/:id — One product by id. Auth: Bearer. Required scope products:read — Read products and categories. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«id»	UUID	path segment
«product_id»	UUID	—

cURL

curl -s "https://yallabuy.app/api/v1/products/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks products:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/catalog/config — Catalog configuration (currency, units, display rules). Auth: Bearer. Required scope products:read — Read products and categories. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/catalog/config" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks products:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/gift-boxes — List of gift boxes. Auth: Bearer. Required scope products:read — Read products and categories. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/gift-boxes" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks products:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/digital-assets — Digital assets attached to digital products. Auth: Bearer. Required scope products:read — Read products and categories. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/digital-assets" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks products:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/serials — Issued and available serial numbers. Auth: Bearer. Required scope products:read — Read products and categories. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«status»	enum	IN_STOCK \| SOLD \| RETURNED \| RMA
«limit (per_page)»	integer	min 1 · max 50

cURL

curl -s "https://yallabuy.app/api/v1/serials" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks products:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

15.Orders and returns — reads (5)

GET /api/v1/orders — Paginated order list with filters; updated_since fetches only rows CHANGED (status/fulfillment edits) since an instant. Auth: Bearer. Required scope orders:read — Read orders. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«status»	enum	PENDING \| CONFIRMED \| PROCESSING \| READY \| SHIPPED \| DELIVERED \| COMPLETED \| CANCELLED
«search»	string	len ≥ 1 · len ≤ 100
«date_from»	string	—
«date_to»	string	—
«updated_since»	string	—
«cursor»	string	position marker from pagination.next_cursor

cURL

curl -s "https://yallabuy.app/api/v1/orders?limit=10" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": "…",
      "status": "PENDING",
      "total_amount": 250.5,
      "branch_id": "…",
      "currency": "EGP"
    }
  ],
  "pagination": {
    "next_cursor": "c1_…",
    "has_more": true
  },
  "page": 1,
  "per_page": 10
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/orders/:id — One order: items, amounts, status, delivery — plus cancellations, returns, refund total, and the linked customer profile (requires customers:read). Auth: Bearer. Required scope orders:read — Read orders. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«id»	UUID	path segment
«order_id»	UUID	—

cURL

curl -s "https://yallabuy.app/api/v1/orders/22222222-2222-4222-8222-222222222222" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "order": {
      "id": "…",
      "status": "PROCESSING",
      "total_amount": 250.5,
      "branch_id": "…",
      "currency": "EGP",
      "customer_name": "…",
      "customer_phone": "…"
    },
    "cancellations": [],
    "returns": [],
    "return_requests": [],
    "refund_total": 0,
    "customer": {
      "id": "…",
      "name": "…",
      "phone": "…",
      "segment": "REGULAR",
      "total_orders": 4,
      "total_spent": 820
    }
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/returns — Completed returns, paginated; updated_since for delta-sync (the cursor is trigger-maintained on the table). Auth: Bearer. Required scope orders:read — Read orders. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«updated_since»	string	—
«cursor»	string	position marker from pagination.next_cursor

cURL

curl -s "https://yallabuy.app/api/v1/returns?limit=10" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "…": "…"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/returns/:id — One processed return by id — the same returns gate stack (orders entitlement, then the returns toggle) applies on the row’s store before serving. Auth: Bearer. Required scope orders:read — Read orders. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«id»	UUID	path segment
«return_id»	UUID	—

cURL

curl -s "https://yallabuy.app/api/v1/returns/77777777-7777-4777-8777-777777777778" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "return": {
      "return_id": "77777777-7777-4777-8777-777777777778",
      "tenant_id": "…",
      "order_id": "22222222-2222-4222-8222-222222222222",
      "items": [
        {
          "name": "Consolation gift box",
          "quantity": 1,
          "product_id": "11111111-1111-4111-8111-111111111111"
        }
      ],
      "refund_amount": 340,
      "refund_method": "ORIGINAL_PAYMENT",
      "reason": "DEFECTIVE",
      "notes": "",
      "created_by": "owner",
      "created_at": "2026-10-20T12:04:11Z"
    }
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/return-requests — Return requests, pending and settled. Auth: Bearer. Required scope orders:read — Read orders. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«status»	enum	PENDING \| APPROVED \| REJECTED
«limit (per_page)»	integer	min 1 · max 50
«cursor»	string	position marker from pagination.next_cursor

cURL

curl -s "https://yallabuy.app/api/v1/return-requests" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "…": "…"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

16.Orders and returns — writes (11)

POST /api/v1/orders/:id/transition — Transition an order status — high risk (requires high_risk_enabled on the key). Auth: Bearer. Required scope orders:write — Update order status. Limit: 10/min per key (API_HIGH_RISK). High risk.

Path parameter	Type
«order_id»	UUID

Body field	Type	Constraints
«status»	enum	PENDING \| CONFIRMED \| PROCESSING \| READY \| SHIPPED \| DELIVERED \| COMPLETED \| CANCELLED
«reason»	string	len ≥ 1 · len ≤ 300

cURL

curl -s -X POST "https://yallabuy.app/api/v1/orders/22222222-2222-4222-8222-222222222222/transition" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"status":"CONFIRMED","reason":"Confirmed after stock check"}'

Response

{
  "data": {
    "order": {
      "status": "CONFIRMED"
    },
    "verification": {
      "verified": true,
      "reread_status": "CONFIRMED"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INVALID_STATE_TRANSITION	illegal state transition
INTERNAL	internal error

POST /api/v1/orders — Create an order on the website channel (DELIVERY/TABLE/PICKUP) — prices always come from the catalog; the Idempotency-Key header (UUID) is required and a repeat replays the original order. High risk. Auth: Bearer. Required scope orders:write — Update order status. Limit: 10/min per key (API_HIGH_RISK). High risk.

Body field	Type	Constraints
«order_type»	enum	DELIVERY \| TABLE \| PICKUP
«items»	array	—
«payment_method»	enum	CASH \| COD \| CARD \| ONLINE_CARD \| VODAFONE_CASH \| INSTAPAY \| BANK_TRANSFER
«customer_name»	string	len ≥ 1 · len ≤ 200
«customer_phone»	string	len ≥ 1 · len ≤ 40
«shipping_address»	string	len ≥ 1 · len ≤ 2000
«coupon_code»	string	len ≥ 1 · len ≤ 120

cURL

curl -s -X POST "https://yallabuy.app/api/v1/orders" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b96e3f1-6f2a-4c0f-9f6f-3f8a2f4f1001" \
  -d '{"order_type":"DELIVERY","items":[{"product_id":"11111111-1111-4111-8111-111111111111","quantity":2,"notes":"بدون بصل","extras":[{"id":"11111111-1111-4111-8111-111111111111"}]}],"payment_method":"COD","customer_name":"منى أحمد","customer_phone":"+201001234567","shipping_address":"٥ شارع التحرير، الدقي، الجيزة","coupon_code":"SUMMER25"}'

Response

{
  "data": {
    "order": {
      "id": "…",
      "status": "PENDING",
      "order_type": "DELIVERY",
      "total_amount": 340,
      "receipt_number": "YB-…"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/orders/:id/dispatch — Assign a driver and ship the order to SHIPPED — requires the delivery module. High risk. Auth: Bearer. Required scope orders:write — Update order status. Limit: 10/min per key (API_HIGH_RISK). High risk.

Path parameter	Type
«order_id»	UUID

Body field	Type	Constraints
«driver_name»	string	len ≥ 1 · len ≤ 200
«driver_phone»	string	len ≥ 1 · len ≤ 40
«shipping_carrier»	string	len ≥ 1 · len ≤ 200
«tracking_number»	string	len ≥ 1 · len ≤ 120

cURL

curl -s -X POST "https://yallabuy.app/api/v1/orders/22222222-2222-4222-8222-222222222222/dispatch" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"driver_name":"كريم مصطفى","driver_phone":"+201112223333","shipping_carrier":"أسطول التوصيل الداخلي","tracking_number":"TRK-483920"}'

Response

{
  "data": {
    "order": {
      "id": "…",
      "status": "SHIPPED",
      "driver_name": "كريم مصطفى",
      "shipping_status": "IN_TRANSIT"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INVALID_STATE_TRANSITION	illegal state transition
INTERNAL	internal error

POST /api/v1/cancellation-requests/:id/decide — Approve or reject a customer cancellation request — approval cancels the order and restores stock automatically. High risk. Auth: Bearer. Required scope orders:write — Update order status. Limit: 10/min per key (API_HIGH_RISK). High risk.

Path parameter	Type
«request_id»	UUID

Body field	Type	Constraints
«decision»	enum	APPROVED \| REJECTED
«decision_reason»	string	len ≥ 1 · len ≤ 1000

cURL

curl -s -X POST "https://yallabuy.app/api/v1/cancellation-requests/77777777-7777-4777-8777-777777777777/decide" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"decision":"APPROVED","decision_reason":"العميل ألغى قبل التحضير"}'

Response

{
  "data": {
    "request": {
      "id": "…",
      "status": "APPROVED",
      "decided_at": "…"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INVALID_STATE_TRANSITION	illegal state transition
INTERNAL	internal error

POST /api/v1/orders/:id/kitchen — Advance an order through the kitchen line. Auth: Bearer. Required scope orders:write — Update order status. Limit: 20/min per key (API_MUTATION).

Path parameter	Type
«order_id»	UUID

Body field	Type	Constraints
«next_status»	enum	QUEUED \| IN_PREP \| READY \| SERVED

cURL

curl -s -X POST "https://yallabuy.app/api/v1/orders/22222222-2222-4222-8222-222222222222/kitchen" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"next_status":"READY"}'

Response

{
  "data": {
    "…": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INVALID_STATE_TRANSITION	illegal state transition
INTERNAL	internal error

POST /api/v1/orders/:id/transfer-table — Move an order between tables — high risk. Auth: Bearer. Required scope orders:write — Update order status. Limit: 10/min per key (API_HIGH_RISK). High risk.

Path parameter	Type
«order_id»	UUID

Body field	Type	Constraints
«dest_table_id»	UUID	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/orders/22222222-2222-4222-8222-222222222222/transfer-table" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"dest_table_id":"66666666-6666-4666-8666-666666666666"}'

Response

{
  "data": {
    "…": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/returns — Create a return for an order idempotently — high risk. Auth: Bearer. Required scope orders:write — Update order status. Limit: 10/min per key (API_HIGH_RISK). High risk.

Body field	Type	Constraints
«order_id»	UUID	—
«items»	array	—
«refund_method»	enum	CASH \| ORIGINAL_PAYMENT \| STORE_CREDIT
«reason»	string	len ≥ 1 · len ≤ 80

cURL

curl -s -X POST "https://yallabuy.app/api/v1/returns" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b96e3f1-6f2a-4c0f-9f6f-3f8a2f4f1001" \
  -d '{"order_id":"22222222-2222-4222-8222-222222222222","items":[{"name":"Consolation gift box","quantity":1,"product_id":"11111111-1111-4111-8111-111111111111"}],"refund_method":"ORIGINAL_PAYMENT","reason":"Item arrived damaged"}'

Response

{
  "data": {
    "…": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/return-requests/:id/review — Settle a return request (approve/reject) — high risk. Auth: Bearer. Required scope orders:write — Update order status. Limit: 10/min per key (API_HIGH_RISK). High risk.

Path parameter	Type
«request_id»	UUID

Body field	Type	Constraints
«decision»	enum	APPROVED \| REJECTED
«refund_method»	enum	CASH \| ORIGINAL_PAYMENT \| STORE_CREDIT
«restock»	boolean	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/return-requests/77777777-7777-4777-8777-777777777777/review" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"decision":"APPROVED","refund_method":"CASH","restock":true}'

Response

{
  "data": {
    "…": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INVALID_STATE_TRANSITION	illegal state transition
INTERNAL	internal error

POST /api/v1/tables/:id/release — Release a table once its order is closed — high risk. Auth: Bearer. Required scope orders:write — Update order status. Limit: 10/min per key (API_HIGH_RISK). High risk.

Path parameter	Type
«table_id»	UUID

cURL

curl -s -X POST "https://yallabuy.app/api/v1/tables/66666666-6666-4666-8666-666666666666/release" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Response

{
  "data": {
    "…": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/returns/:id/refund-approval — Record a refund APPROVAL for a return (documentation only, no cash movement) — amount is capped cumulatively and one record per return. High risk. Auth: Bearer. Required scope orders:write — Update order status. Limit: 10/min per key (API_HIGH_RISK). High risk.

Path parameter	Type
«return_id»	UUID

Body field	Type	Constraints
«amount»	number	max 100000000
«method»	enum	CASH \| ORIGINAL_PAYMENT \| STORE_CREDIT
«note»	string	len ≥ 1 · len ≤ 1000

cURL

curl -s -X POST "https://yallabuy.app/api/v1/returns/77777777-7777-4777-8777-777777777778/refund-approval" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"amount":340,"method":"ORIGINAL_PAYMENT","note":"موافقة على استرداد قيمة المرتجع"}'

Response

{
  "data": {
    "refund": {
      "id": "…",
      "status": "RECORDED",
      "method": "ORIGINAL_PAYMENT",
      "approved_amount": 340
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/returns/:id/refund-execution — Record the refund as EXECUTED (mandatory external reference + evidence) — cash refunds deduct from an open shift drawer. High risk. Auth: Bearer. Required scope orders:write — Update order status. Limit: 10/min per key (API_HIGH_RISK). High risk.

Path parameter	Type
«return_id»	UUID

Body field	Type	Constraints
«amount»	number	max 100000000
«external_reference»	string	len ≥ 1 · len ≤ 300
«evidence_note»	string	len ≥ 1 · len ≤ 1000
«shift_id»	UUID	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/returns/77777777-7777-4777-8777-777777777778/refund-execution" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"amount":340,"external_reference":"BANK-TRF-20261020-7731","evidence_note":"تحويل بنكي مرسل","shift_id":"66666666-6666-4666-8666-666666666666"}'

Response

{
  "data": {
    "refund": {
      "id": "…",
      "status": "EXECUTED",
      "amount": 340,
      "external_reference": "BANK-TRF-20261020-7731"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INVALID_STATE_TRANSITION	illegal state transition
INTERNAL	internal error

17.Inventory — reads (5)

GET /api/v1/inventory — Stock levels across products, variants, ingredients. Auth: Bearer. Required scope inventory:read — Read stock levels and inventory movements. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«search»	string	len ≥ 1 · len ≤ 100
«status»	enum	ALL \| OK \| LOW \| OUT \| UNTRACKED
«scope»	enum	ALL \| PRODUCTS \| VARIANTS \| INGREDIENTS
«limit (per_page)»	integer	min 1 · max 50

cURL

curl -s "https://yallabuy.app/api/v1/inventory" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks inventory:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/inventory/overview — Inventory overview: value and low stock. Auth: Bearer. Required scope inventory:read — Read stock levels and inventory movements. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/inventory/overview" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks inventory:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/inventory/movements — Inventory movements (receipt, sale, adjustment), paginated. Auth: Bearer. Required scope inventory:read — Read stock levels and inventory movements. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«item_type»	enum	PRODUCT \| VARIANT \| INGREDIENT
«item_id»	UUID	—
«movement_type»	enum	OPENING_BALANCE \| RECEIPT \| SALE \| RETURN \| ADJUSTMENT_IN \| ADJUSTMENT_OUT \| DAMAGE \| LOSS \| TRANSFER_IN \| TRANSFER_OUT \| RECIPE_CONSUMPTION
«date_from»	string	—
«date_to»	string	—

cURL

curl -s "https://yallabuy.app/api/v1/inventory/movements?limit=10" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks inventory:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/inventory/:id — One inventory record by id. Auth: Bearer. Required scope inventory:read — Read stock levels and inventory movements. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«id»	UUID	path segment
«item_id»	UUID	—

cURL

curl -s "https://yallabuy.app/api/v1/inventory/bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb?item_type=PRODUCT" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks inventory:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/recipes — Manufacturing recipes linked to products. Auth: Bearer. Required scope inventory:read — Read stock levels and inventory movements. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/recipes" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks inventory:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

18.Inventory — writes (4)

POST /api/v1/inventory/receive — Receive stock with a mandatory idempotency key — high risk. Auth: Bearer. Required scope inventory:write — Receive stock and adjust inventory. Limit: 10/min per key (API_HIGH_RISK). High risk.

Body field	Type	Constraints
«item_type»	enum	PRODUCT \| VARIANT \| INGREDIENT
«item_id»	UUID	—
«quantity»	number	min 0.000001 · max 100000000
«unit_code»	string	len ≥ 1 · len ≤ 10
«unit_cost»	number	min 0 · max 1000000000

cURL

curl -s -X POST "https://yallabuy.app/api/v1/inventory/receive" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b96e3f1-6f2a-4c0f-9f6f-3f8a2f4f1001" \
  -d '{"item_type":"PRODUCT","item_id":"11111111-1111-4111-8111-111111111111","quantity":12,"unit_code":"PCS","unit_cost":40}'

Response

{
  "data": {
    "movement_id": "…",
    "quantity": 12
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks inventory:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/inventory/adjust — Adjust inventory (adjustment/damage/loss) idempotently — high risk. Auth: Bearer. Required scope inventory:write — Receive stock and adjust inventory. Limit: 10/min per key (API_HIGH_RISK). High risk.

Body field	Type	Constraints
«item_type»	enum	PRODUCT \| VARIANT \| INGREDIENT
«item_id»	UUID	—
«quantity»	number	min -100000000 · max 100000000
«kind»	enum	ADJUSTMENT \| DAMAGE \| LOSS
«reason»	string	len ≥ 1 · len ≤ 300

cURL

curl -s -X POST "https://yallabuy.app/api/v1/inventory/adjust" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b96e3f1-6f2a-4c0f-9f6f-3f8a2f4f1001" \
  -d '{"item_type":"INGREDIENT","item_id":"55555555-5555-4555-8555-555555555555","quantity":-3,"kind":"DAMAGE","reason":"Spoiled shipment"}'

Response

{
  "data": {
    "…": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks inventory:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/inventory/bulk/preview — Preview a bulk inventory operation (≤25 rows) — POSTs under inventory:read because it changes nothing. Auth: Bearer. Required scope inventory:read — Read stock levels and inventory movements. Limit: 5/min per key (API_WRITE_BULK).

Body field	Type	Constraints
«operation»	string	—
«items»	array	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/inventory/bulk/preview" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"operation":"RECEIVE","items":[{"record_ref":"csv-row-17","item_type":"PRODUCT","item_id":"11111111-1111-4111-8111-111111111111","quantity":6,"unit_code":"PCS","unit_cost":40}]}'

Response

{
  "data": {
    "…": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks inventory:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/inventory/bulk/apply — Apply a previously previewed bulk operation (body must match the preview via preview_hash) — high risk. Auth: Bearer. Required scope inventory:write — Receive stock and adjust inventory. Limit: 5/min per key (API_WRITE_BULK). High risk.

Body field	Type	Constraints
«operation_id»	UUID	—
«preview_hash»	string	—
«operation»	string	—
«items»	array	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/inventory/bulk/apply" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"operation_id":"88888888-8888-4888-8888-888888888888","preview_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","operation":"RECEIVE","items":[{"record_ref":"csv-row-17","item_type":"PRODUCT","item_id":"11111111-1111-4111-8111-111111111111","quantity":6,"unit_code":"PCS","unit_cost":40}]}'

Response

{
  "data": {
    "…": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks inventory:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
PREVIEW_STALE	preview no longer matches the body — re-preview
INTERNAL	internal error

19.Customers (CRM) (2)

GET /api/v1/customers — Customer base with search (requires the CRM feature). Auth: Bearer. Required scope customers:read — Read customers and their profiles. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«search»	string	len ≥ 1 · len ≤ 100

cURL

curl -s "https://yallabuy.app/api/v1/customers?limit=10" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks customers:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
FEATURE_TURNED_OFF	CRM feature is off for the store
INTERNAL	internal error

GET /api/v1/customers/:id/360 — Full customer profile (requires the CRM feature). Auth: Bearer. Required scope customers:read — Read customers and their profiles. Limit: 20/min per key (API_READ_HEAVY).

Parameter	Type	Constraints
«id»	UUID	path segment
«customer_id»	UUID	—

cURL

curl -s "https://yallabuy.app/api/v1/customers/33333333-3333-4333-8333-333333333333/360" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks customers:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
FEATURE_TURNED_OFF	CRM feature is off for the store
INTERNAL	internal error

20.Customers — writes (3)

POST /api/v1/customers — Create a customer in the CRM base (requires the CRM feature) — the phone is unique per store and immutable after creation. Auth: Bearer. Required scope customers:write — Create, update and delete customers (phone immutable after creation). Limit: 20/min per key (API_MUTATION).

Body field	Type	Constraints
«name»	string	len ≥ 1 · len ≤ 200
«phone»	string	len ≥ 3 · len ≤ 32
«email»	any	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/customers" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"Mona Ahmed","phone":"+201001234567","email":"mona@example.com"}'

Response

{
  "data": {
    "customer": {
      "id": "…",
      "name": "Mona Ahmed",
      "phone": "+201001234567",
      "email": "mona@example.com",
      "address": null,
      "whatsapp_number": null,
      "segment": "NEW",
      "total_orders": 0,
      "total_spent": 0,
      "first_order_at": "…",
      "last_order_at": null,
      "notes": null,
      "created_at": "…"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks customers:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/customers/:id — Update an existing customer (phone and segment are immutable; editable: name, WhatsApp, email, address, notes). Auth: Bearer. Required scope customers:write — Create, update and delete customers (phone immutable after creation). Limit: 20/min per key (API_MUTATION).

Path parameter	Type
«customer_id»	UUID

Body field	Type	Constraints
«notes»	any	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/customers/33333333-3333-4333-8333-333333333333" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"notes":"Prefers evening calls"}'

Response

{
  "data": {
    "customer": {
      "id": "…",
      "name": "Mona Ahmed",
      "phone": "+201001234567",
      "email": "mona@example.com",
      "address": null,
      "whatsapp_number": null,
      "segment": "NEW",
      "total_orders": 0,
      "total_spent": 0,
      "first_order_at": "…",
      "last_order_at": null,
      "notes": "Prefers evening calls",
      "created_at": "…"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks customers:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

DELETE /api/v1/customers/:id — Permanently delete a customer from the CRM base — no undo; requires the CRM feature. Auth: Bearer. Required scope customers:write — Create, update and delete customers (phone immutable after creation). Limit: 20/min per key (API_MUTATION).

Path parameter	Type
«customer_id»	UUID

cURL

curl -s -X DELETE "https://yallabuy.app/api/v1/customers/33333333-3333-4333-8333-333333333333" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Response

{
  "data": {
    "deleted": true,
    "customer_id": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks customers:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

21.Marketing (4)

GET /api/v1/marketing — Marketing overview: coupons and promotions. Auth: Bearer. Required scope marketing:read — Read marketing overview and coupons. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«days»	integer	min 1 · max 365

cURL

curl -s "https://yallabuy.app/api/v1/marketing" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/marketing/coupons — Discount coupons; updated_since for delta-sync. Auth: Bearer. Required scope marketing:read — Read marketing overview and coupons. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«active»	boolean	—
«updated_since»	string	—
«limit (per_page)»	integer	min 1 · max 50
«cursor»	string	position marker from pagination.next_cursor

cURL

curl -s "https://yallabuy.app/api/v1/marketing/coupons" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "…": "…"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/marketing/promotions — Promotions; updated_since for delta-sync. Auth: Bearer. Required scope marketing:read — Read marketing overview and coupons. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«status»	enum	ACTIVE \| PAUSED \| ARCHIVED
«updated_since»	string	—
«limit (per_page)»	integer	min 1 · max 50
«cursor»	string	position marker from pagination.next_cursor

cURL

curl -s "https://yallabuy.app/api/v1/marketing/promotions" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "…": "…"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/marketing/promotions/performance — Promotion performance: usage and attributed revenue. Auth: Bearer. Required scope marketing:read — Read marketing overview and coupons. Limit: 20/min per key (API_READ_HEAVY).

Parameter	Type	Constraints
«days»	integer	min 1 · max 365

cURL

curl -s "https://yallabuy.app/api/v1/marketing/promotions/performance" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

22.Marketing — writes (9)

POST /api/v1/coupons — Create a discount coupon (requires the Marketing feature) — the code is unique per store; the plan caps coupon count. Auth: Bearer. Required scope marketing:write — Create, update and delete coupons, promotions and bundles. Limit: 20/min per key (API_MUTATION).

Body field	Type	Constraints
«code»	string	len ≥ 1 · len ≤ 40
«discount_type»	enum	PERCENTAGE \| FIXED_AMOUNT
«discount_value»	number	—
«min_order_amount»	number	min 0
«end_date»	any	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/coupons" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"code":"SUMMER25","discount_type":"PERCENTAGE","discount_value":25,"min_order_amount":200,"end_date":"2026-12-31"}'

Response

{
  "data": {
    "coupon": {
      "id": "…",
      "tenant_id": "…",
      "code": "SUMMER25",
      "discount_type": "PERCENTAGE",
      "discount_value": 25,
      "min_order_amount": 200,
      "usage_limit": null,
      "max_discount_amount": null,
      "per_customer_limit": null,
      "start_date": null,
      "end_date": "2026-12-31T00:00:00Z",
      "is_active": true,
      "archived_at": null,
      "times_used": 0,
      "scope": {
        "kind": "ALL"
      },
      "eligible_customers": {
        "mode": "ALL"
      },
      "stacks_with_automatic": true,
      "created_at": "…",
      "updated_at": "…"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/coupons/:id — Update an existing coupon — usage counters and the redemption ledger are read-only; re-activating clears the soft-archive stamp. Auth: Bearer. Required scope marketing:write — Create, update and delete coupons, promotions and bundles. Limit: 20/min per key (API_MUTATION).

Path parameter	Type
«coupon_id»	UUID

Body field	Type	Constraints
«discount_value»	number	—
«is_active»	boolean	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/coupons/22222222-2222-4222-8222-222222222222" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"discount_value":30,"is_active":true}'

Response

{
  "data": {
    "coupon": {
      "id": "…",
      "code": "SUMMER25",
      "discount_type": "PERCENTAGE",
      "discount_value": 30,
      "is_active": true,
      "archived_at": null,
      "times_used": 4,
      "updated_at": "…"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

DELETE /api/v1/coupons/:id — Delete a coupon — one with redemption history is ARCHIVED instead of destroyed (historical orders must stay interpretable). Auth: Bearer. Required scope marketing:write — Create, update and delete coupons, promotions and bundles. Limit: 20/min per key (API_MUTATION).

Path parameter	Type
«coupon_id»	UUID

cURL

curl -s -X DELETE "https://yallabuy.app/api/v1/coupons/22222222-2222-4222-8222-222222222222" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Response

{
  "data": {
    "deleted": true,
    "coupon_id": "…",
    "archived": false
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/promotions — Create an automatic promotion (requires the Marketing feature) — the type constrains which rule fields apply; the plan caps promotion count. Auth: Bearer. Required scope marketing:write — Create, update and delete coupons, promotions and bundles. Limit: 20/min per key (API_MUTATION).

Body field	Type	Constraints
«name»	string	len ≥ 1 · len ≤ 120
«promotion_type»	enum	CART_PERCENTAGE \| CART_FIXED \| CART_TIERS \| ITEM_PERCENTAGE \| QUANTITY_PERCENTAGE \| FREE_SHIPPING
«discount_value»	number	min 0
«min_order_amount»	number	min 0

cURL

curl -s -X POST "https://yallabuy.app/api/v1/promotions" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"Winter discount","promotion_type":"CART_PERCENTAGE","discount_value":10,"min_order_amount":300}'

Response

{
  "data": {
    "promotion": {
      "id": "…",
      "tenant_id": "…",
      "name": "Winter discount",
      "name_en": null,
      "promotion_type": "CART_PERCENTAGE",
      "status": "ACTIVE",
      "priority": 0,
      "min_order_amount": 300,
      "discount_value": 10,
      "max_uses": null,
      "times_used": 0,
      "min_quantity": null,
      "tiers": null,
      "scope": {
        "kind": "ALL"
      },
      "eligible_customers": {
        "mode": "ALL"
      },
      "created_at": "…",
      "updated_at": "…"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/promotions/:id — Update an existing promotion — the type is immutable after creation (min_quantity/tiers constraints follow the original type). Auth: Bearer. Required scope marketing:write — Create, update and delete coupons, promotions and bundles. Limit: 20/min per key (API_MUTATION).

Path parameter	Type
«promotion_id»	UUID

Body field	Type	Constraints
«discount_value»	number	min 0
«is_active»	boolean	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/promotions/22222222-2222-4222-8222-222222222222" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"discount_value":15,"is_active":true}'

Response

{
  "data": {
    "promotion": {
      "id": "…",
      "name": "Winter discount",
      "promotion_type": "CART_PERCENTAGE",
      "status": "ACTIVE",
      "discount_value": 15,
      "updated_at": "…"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

DELETE /api/v1/promotions/:id — Archive a promotion (soft delete, one-way) — promotions are business records that stay analytically interpretable. Auth: Bearer. Required scope marketing:write — Create, update and delete coupons, promotions and bundles. Limit: 20/min per key (API_MUTATION).

Path parameter	Type
«promotion_id»	UUID

cURL

curl -s -X DELETE "https://yallabuy.app/api/v1/promotions/22222222-2222-4222-8222-222222222222" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Response

{
  "data": {
    "deleted": true,
    "promotion_id": "…",
    "archived": true
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/bundles — Create a product bundle rule (BXGY or COMBO_FIXED) — requires the Marketing feature. Auth: Bearer. Required scope marketing:write — Create, update and delete coupons, promotions and bundles. Limit: 20/min per key (API_MUTATION).

Body field	Type	Constraints
«name_ar»	string	len ≥ 1 · len ≤ 200
«name_en»	any	—
«bundle_type»	enum	BXGY \| COMBO_FIXED
«buy_product_id»	UUID	—
«buy_quantity»	integer	min 1 · max 9007199254740991
«get_product_id»	any	—
«get_quantity»	integer	min 1 · max 9007199254740991
«discount_value»	number	min 0

cURL

curl -s -X POST "https://yallabuy.app/api/v1/bundles" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name_ar":"اشترِ ٢ واحصل على ١","name_en":"Buy 2 get 1","bundle_type":"BXGY","buy_product_id":"11111111-1111-4111-8111-111111111111","buy_quantity":2,"get_product_id":"11111111-1111-4111-8111-111111111111","get_quantity":1,"discount_value":100}'

Response

{
  "data": {
    "bundle": {
      "id": "…",
      "tenant_id": "…",
      "name_ar": "اشترِ ٢ واحصل على ١",
      "name_en": "Buy 2 get 1",
      "bundle_type": "BXGY",
      "buy_product_id": "…",
      "buy_quantity": 2,
      "get_product_id": "…",
      "get_quantity": 1,
      "discount_value": 100,
      "is_active": true,
      "created_at": "…",
      "updated_at": "…"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/bundles/:id — Update an existing bundle rule. Auth: Bearer. Required scope marketing:write — Create, update and delete coupons, promotions and bundles. Limit: 20/min per key (API_MUTATION).

Path parameter	Type
«bundle_id»	UUID

Body field	Type	Constraints
«is_active»	boolean	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/bundles/22222222-2222-4222-8222-222222222222" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"is_active":false}'

Response

{
  "data": {
    "bundle": {
      "id": "…",
      "name_ar": "اشترِ ٢ واحصل على ١",
      "bundle_type": "BXGY",
      "is_active": false,
      "updated_at": "…"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

DELETE /api/v1/bundles/:id — Permanently delete a bundle rule — rules carry no redemption history, so the delete is clean. Auth: Bearer. Required scope marketing:write — Create, update and delete coupons, promotions and bundles. Limit: 20/min per key (API_MUTATION).

Path parameter	Type
«bundle_id»	UUID

cURL

curl -s -X DELETE "https://yallabuy.app/api/v1/bundles/22222222-2222-4222-8222-222222222222" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Response

{
  "data": {
    "deleted": true,
    "bundle_id": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks marketing:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

23.Analytics and finance (7)

GET /api/v1/analytics/sales — Sales analytics over a date window (≤366 days): revenue counts COMPLETED/DELIVERED orders only; net sales subtract refunds; profit subtracts COGS and expenses — per store. Auth: Bearer. Required scope analytics:read — Read sales analytics. Limit: 20/min per key (API_READ_HEAVY).

Parameter	Type	Constraints
«period»	enum	today \| yesterday \| last7 \| last30 \| thisMonth \| lastMonth \| custom
«from»	string	—
«to»	string	—

cURL

curl -s "https://yallabuy.app/api/v1/analytics/sales" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks analytics:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
RANGE_TOO_LARGE	date window exceeds the allowed range
INTERNAL	internal error

GET /api/v1/analytics/product-performance — Product sales performance over a date window (rank by quantity/orders/net revenue): net of product-attributed refunds; no cost or profit fields — reports, not finance. Auth: Bearer. Required scope analytics:read — Read sales analytics. Limit: 20/min per key (API_READ_HEAVY).

Parameter	Type	Constraints
«period»	enum	today \| yesterday \| last7 \| last30 \| thisMonth \| lastMonth \| custom
«from»	string	—
«to»	string	—
«metric»	enum	quantity \| orders \| revenue
«limit»	integer	min 1 · max 50
«offset»	integer	min 0 · max 5000

cURL

curl -s "https://yallabuy.app/api/v1/analytics/product-performance" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks analytics:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
RANGE_TOO_LARGE	date window exceeds the allowed range
INTERNAL	internal error

GET /api/v1/analytics/insights — Engine summary (current vs previous with deltas), stock and pending counts — a field missing from any store totals to null, never a silent partial sum. Auth: Bearer. Required scope analytics:read — Read sales analytics. Limit: 20/min per key (API_READ_HEAVY).

Parameter	Type	Constraints
«period»	enum	today \| yesterday \| last7 \| last30 \| thisMonth \| lastMonth \| custom
«from»	string	—
«to»	string	—

cURL

curl -s "https://yallabuy.app/api/v1/analytics/insights" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks analytics:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
RANGE_TOO_LARGE	date window exceeds the allowed range
INTERNAL	internal error

GET /api/v1/finance/profit-loss — Profit & loss (finance:read): revenue = COMPLETED/DELIVERED minus refunds; COGS from the line’s historical cost or the recorded cost price; expenses come off net profit. Auth: Bearer. Required scope finance:read — Read profit & loss, expenses and POS cash-drawer shifts. Limit: 20/min per key (API_READ_HEAVY).

Parameter	Type	Constraints
«period»	enum	today \| yesterday \| last7 \| last30 \| thisMonth \| lastMonth \| custom
«from»	string	—
«to»	string	—

cURL

curl -s "https://yallabuy.app/api/v1/finance/profit-loss" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks finance:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
RANGE_TOO_LARGE	date window exceeds the allowed range
INTERNAL	internal error

GET /api/v1/expenses — Operating expenses, paginated (window on expense_date) — the exact table the analytics net-profit law subtracts; the window rides the expense date, not created_at. Auth: Bearer. Required scope finance:read — Read profit & loss, expenses and POS cash-drawer shifts. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«date_from»	string	—
«date_to»	string	—
«cursor»	string	position marker from pagination.next_cursor

cURL

curl -s "https://yallabuy.app/api/v1/expenses?limit=10" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "expense_id": "88888888-8888-4888-8888-888888888881",
      "tenant_id": "…",
      "category": "RENT",
      "amount": 5000,
      "description": "إيجار أكتوبر",
      "expense_date": "2026-10-01",
      "receipt_url": null,
      "created_by": "owner",
      "created_at": "2026-10-01T09:00:00Z",
      "branch_id": null
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  },
  "page": 1,
  "per_page": 10
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks finance:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/shifts — POS cashier shift history, paginated — the financial record per drawer (requires finance:read and the POS feature). Auth: Bearer. Required scope finance:read — Read profit & loss, expenses and POS cash-drawer shifts. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«cursor»	string	position marker from pagination.next_cursor

cURL

curl -s "https://yallabuy.app/api/v1/shifts?limit=10&status=CLOSED" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": "77777777-7777-4777-8777-777777777777",
      "tenant_id": "…",
      "branch_id": null,
      "staff_id": null,
      "cashier_name": "منى أحمد",
      "status": "CLOSED",
      "opened_at": "2026-10-20T08:00:00Z",
      "closed_at": "2026-10-20T16:00:00Z",
      "starting_float": 200,
      "closing_cash_counted": 1400.5,
      "cash_sales": 1240.5,
      "card_sales": 830,
      "other_sales": 0,
      "total_refunds": 40,
      "expected_cash": 1400.5,
      "variance": 0,
      "notes": null,
      "created_at": "2026-10-20T08:00:01Z"
    }
  ],
  "pagination": {
    "next_cursor": "c1_…",
    "has_more": true
  },
  "page": 1,
  "per_page": 10
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks finance:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/shifts/:id — One cashier shift by id; an OPEN shift carries the live drawer summary (live_stats), a CLOSED one the stored close snapshot with live_stats:null. Auth: Bearer. Required scope finance:read — Read profit & loss, expenses and POS cash-drawer shifts. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«id»	UUID	path segment
«shift_id»	UUID	—

cURL

curl -s "https://yallabuy.app/api/v1/shifts/77777777-7777-4777-8777-777777777777" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "shift": {
      "id": "77777777-7777-4777-8777-777777777777",
      "tenant_id": "…",
      "branch_id": null,
      "staff_id": null,
      "cashier_name": "منى أحمد",
      "status": "OPEN",
      "opened_at": "2026-10-20T08:00:00Z",
      "closed_at": null,
      "starting_float": 200,
      "closing_cash_counted": null,
      "cash_sales": 0,
      "card_sales": 0,
      "other_sales": 0,
      "total_refunds": 0,
      "expected_cash": 0,
      "variance": 0,
      "notes": null,
      "created_at": "2026-10-20T08:00:01Z"
    },
    "live_stats": {
      "orders_count": 31,
      "returns_count": 2,
      "cash_sales": 1240.5,
      "card_sales": 830,
      "other_sales": 0,
      "total_sales": 2070.5,
      "cash_refunds": 40,
      "total_refunds": 62,
      "cash_in": 100,
      "cash_out": 0,
      "expected_cash": 1500.5
    }
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks finance:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

24.Staff and branches (3)

GET /api/v1/staff — Team members and their roles. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«limit (per_page)»	integer	min 1 · max 50
«cursor»	string	position marker from pagination.next_cursor

cURL

curl -s "https://yallabuy.app/api/v1/staff" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "…": "…"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/staff/:id — One team member. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«id»	UUID	path segment
«staff_id»	UUID	—

cURL

curl -s "https://yallabuy.app/api/v1/staff/aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/branches — Store branches. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«active»	boolean	—
«limit (per_page)»	integer	min 1 · max 50

cURL

curl -s "https://yallabuy.app/api/v1/branches" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

25.Activity and security (4)

GET /api/v1/activity — General store activity log, paginated. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«entity_type»	string	len ≥ 1 · len ≤ 60
«action»	string	len ≥ 1 · len ≤ 80
«date_from»	string	—
«date_to»	string	—
«limit (per_page)»	integer	min 1 · max 100
«cursor»	string	position marker from pagination.next_cursor

cURL

curl -s "https://yallabuy.app/api/v1/activity" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "…": "…"
    }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/security/login-history — Account login history. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«days»	integer	min 1 · max 90

cURL

curl -s "https://yallabuy.app/api/v1/security/login-history?limit=10" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/security/staff-activity — Staff activity in the dashboard. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/security/staff-activity" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/security/activity — Security events (sensitive changes). Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

Parameter	Type	Constraints
«action»	string	len ≥ 1 · len ≤ 80
«actor»	UUID	—
«date_from»	string	—
«date_to»	string	—
«q»	string	len ≥ 1 · len ≤ 60
«limit (per_page)»	integer	min 1 · max 50

cURL

curl -s "https://yallabuy.app/api/v1/security/activity" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

26.Restaurants and cafés (3)

GET /api/v1/restaurant/floor-plan — Current table floor plan. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/restaurant/floor-plan" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/restaurant/kds — Kitchen display: orders in flight. Auth: Bearer. Required scope orders:read — Read orders. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/restaurant/kds" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks orders:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

GET /api/v1/restaurant/config — Kitchen display configuration. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

cURL

curl -s "https://yallabuy.app/api/v1/restaurant/config" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

27.Universal search (1)

GET /api/v1/search — Universal search over products, orders, customers, activity (required query ≤80 chars). Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 20/min per key (API_READ_HEAVY).

Parameter	Type	Constraints
«domain»	enum	products \| orders \| customers \| activity
«limit (per_page)»	integer	min 1 · max 10

cURL

curl -s "https://yallabuy.app/api/v1/search?query=latte" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid query or cursor
NOT_FOUND	unknown path or out-of-scope resource
INTERNAL	internal error

28.Storefront design — intent reads (5)

GET /api/v1/store/design/context — Current storefront design context (direction, colors, content). Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 60/min per key (API_READ_STANDARD).

No parameters — read as-is.

cURL

curl -s "https://yallabuy.app/api/v1/store/design/context" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid or oversized intent
INTERNAL	internal error

GET /api/v1/store/design/proposal — Propose a design via a URL-encoded intent (smart read). Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 20/min per key (API_READ_HEAVY).

Single intent parameter: URL-encoded JSON in the URL (≤16 KB), forbidden-field-checked then schema-validated.

cURL

curl -s "https://yallabuy.app/api/v1/store/design/proposal?intent=%7B%22requested_direction%22%3A%22editorial-noir%22%7D" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid or oversized intent
INTERNAL	internal error

GET /api/v1/store/design/preview — Preview a proposed design without applying. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 20/min per key (API_READ_HEAVY).

Single intent parameter: URL-encoded JSON in the URL (≤16 KB), forbidden-field-checked then schema-validated.

cURL

curl -s "https://yallabuy.app/api/v1/store/design/preview?intent=%7B%22requested_direction%22%3A%22editorial-noir%22%7D" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid or oversized intent
INTERNAL	internal error

GET /api/v1/store/design/diff — Diff between the current and proposed design. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 20/min per key (API_READ_HEAVY).

Single intent parameter: URL-encoded JSON in the URL (≤16 KB), forbidden-field-checked then schema-validated.

cURL

curl -s "https://yallabuy.app/api/v1/store/design/diff?intent=%7B%22requested_direction%22%3A%22editorial-noir%22%7D" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid or oversized intent
INTERNAL	internal error

GET /api/v1/store/design/verify — Contrast and integrity report for a proposed design. Auth: Bearer. Required scope store:read — Read store profile, business type and plan. Limit: 20/min per key (API_READ_HEAVY).

Single intent parameter: URL-encoded JSON in the URL (≤16 KB), forbidden-field-checked then schema-validated.

cURL

curl -s "https://yallabuy.app/api/v1/store/design/verify?intent=%7B%22proposal_id%22%3A%22bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb%22%2C%22base_design_rev%22%3A3%7D" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json"

Response

{
  "data": {
    "…": "…"
  }
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks store:read
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	invalid or oversized intent
INTERNAL	internal error

29.Products — write (3)

POST /api/v1/products — Create a catalog product — the id is server-issued; blind retries can create duplicates. Auth: Bearer. Required scope products:write — Create, update and archive products. Limit: 20/min per key (API_MUTATION).

Body field	Type	Constraints
«name»	string	len ≥ 1 · len ≤ 200
«price»	number	min 0 · max 1000000000
«sku»	string	len ≤ 100
«is_available»	boolean	—
«stock_quantity»	number	min 0 · max 100000000

cURL

curl -s -X POST "https://yallabuy.app/api/v1/products" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"Spanish latte","price":45,"sku":"ESP-LATTE","is_available":true,"stock_quantity":24}'

Response

{
  "data": {
    "product": {
      "id": "…",
      "name": "Spanish latte",
      "price": 45,
      "sku": "ESP-LATTE",
      "is_available": true,
      "stock_quantity": 24,
      "created_at": "…"
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks products:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

POST /api/v1/products/:id — Update an existing product by id (no stock quantity or variant list — stock moves only through the inventory authorities). Auth: Bearer. Required scope products:write — Create, update and archive products. Limit: 20/min per key (API_MUTATION).

Path parameter	Type
«product_id»	UUID

Body field	Type	Constraints
«price»	number	min 0 · max 1000000000
«is_available»	boolean	—

cURL

curl -s -X POST "https://yallabuy.app/api/v1/products/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"price":47,"is_available":true}'

Response

{
  "data": {
    "product": {
      "id": "…",
      "name": "Spanish latte",
      "price": 47,
      "sku": "ESP-LATTE",
      "is_available": true
    }
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks products:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

DELETE /api/v1/products/:id — Permanently delete a product from the catalog despite the operation name (no undo — only the audit trail remains). Auth: Bearer. Required scope products:write — Create, update and archive products. Limit: 20/min per key (API_MUTATION).

Path parameter	Type
«product_id»	UUID

cURL

curl -s -X DELETE "https://yallabuy.app/api/v1/products/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json"

Response

{
  "data": {
    "…": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks products:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
INTERNAL	internal error

30.Storefront design — write (1)

POST /api/v1/store/design/apply — Apply a storefront design — high risk, CAS-guarded (DESIGN_STALE when the revision moved). Auth: Bearer. Required scope storefront:write — Apply storefront designs (compare-and-set protected). Limit: 10/min per key (API_HIGH_RISK). High risk.

Body field	Type	Constraints
«proposal_id»	string	—
«base_design_rev»	integer	min 0 · max 1000000000
«requested_direction»	enum	editorial-noir \| atelier-sculpted \| paper-boutique \| frame-eyewear \| luminous-editorial \| ember-expressive \| kinetic-craft \| greenery-market

cURL

curl -s -X POST "https://yallabuy.app/api/v1/store/design/apply" \
  -H "Authorization: Bearer YOUR_YALLABUY_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"proposal_id":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","base_design_rev":3,"requested_direction":"editorial-noir"}'

Response

{
  "data": {
    "…": "…"
  },
  "replayed": false
}

Code	When
UNAUTHENTICATED	missing/expired/revoked key (one stable description)
SCOPE_INSUFFICIENT	key lacks storefront:write
NO_AUTHORIZED_STORE	no active store behind the key
RATE_LIMITED	throttled — honor Retry-After
API_DISABLED	API currently disabled platform-wide
VALIDATION_ERROR	body fails the strict schema
FORBIDDEN	high-risk without high_risk_enabled on the key
NOT_FOUND	resource missing or out of scope
CONFLICT	current-state conflict (incl. an already-executed return or an already-used external reference)
MULTI_STORE_UNSUPPORTED	multi-store key on a single-store operation
PLAN_REQUIRED	the current plan does not allow this operation
PAYLOAD_TOO_LARGE	body over 64 KB
DESIGN_STALE	design revision moved — re-propose
PROPOSAL_CHANGED	proposal differs from the previewed revision
INTERNAL	internal error

31.Security guidance

Store keys in a secrets manager — never in code, Git, or screenshots.
Grant least privilege: read-only keys for anything that does not write.
Rotate keys periodically and revoke unused ones immediately.
Do not grant high-risk scopes "for later" — that confirmation is a real responsibility.
If you suspect a leak: rotate immediately — the old secret dies that instant.

32.Availability and current limits

The API operates over the key's effective store scope, recomputed every request — but enabling the API itself is an operational platform decision: while disabled, EVERY request answers 503 API_DISABLED identically for any key.

Up nextYallaBuy merchant webhooks — receive store events on your server

Manage API keys

Was this article helpful?

1.Overview — an interface for YOUR applications

2.Base URL and versioning

3.Authentication with a ybapi_ key

4.Scopes and the high-risk flag

5.Creating, rotating and revoking keys

6.Request and response conventions

7.Pagination and filtering

8.Idempotency for sensitive writes

9.Rate limits and handling 429

10.Error codes and troubleshooting

11.Endpoint reference with copy-paste examples

12.Root diagnostic — GET /api/v1

13.Store and its settings (8)

14.Products and catalog (6)

15.Orders and returns — reads (5)

16.Orders and returns — writes (11)

17.Inventory — reads (5)

18.Inventory — writes (4)

19.Customers (CRM) (2)

20.Customers — writes (3)

21.Marketing (4)

22.Marketing — writes (9)

23.Analytics and finance (7)

24.Staff and branches (3)

25.Activity and security (4)

26.Restaurants and cafés (3)

27.Universal search (1)

28.Storefront design — intent reads (5)

29.Products — write (3)

30.Storefront design — write (1)

31.Security guidance

32.Availability and current limits

Related articles