# Jarir API — search Jarir Bookstore (Saudi Arabia, Kuwait, Qatar, UAE, Bahrain) and read products with price, regular price, discount, online stock, showroom stock, seller, installments, specs and reviews

> Search Jarir's catalogue with Jarir's own search engine: keyword, brand, product type, price range in the storefront's currency and price sort. Give a `query`, or browse a whole `product_type` or `brand` without one. Each row: SKU, name, URL, brand, model, MPN, barcode, price the shopper pays, regular price, discount, currency, in-stock flag, who sells it (Jarir or a named marketplace seller), Tabby/Tamara eligibility, image. Plus Jarir's own total and the brand / product type / price facets of the result set.
> ReefAPI engine `jarir` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/jarir/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/jarir/v1/search — 3 credits
Search Jarir's catalogue with Jarir's own search engine: keyword, brand, product type, price range in the storefront's currency and price sort. Give a `query`, or browse a whole `product_type` or `brand` without one. Each row: SKU, name, URL, brand, model, MPN, barcode, price the shopper pays, regular price, discount, currency, in-stock flag, who sells it (Jarir or a named marketplace seller), Tabby/Tamara eligibility, image. Plus Jarir's own total and the brand / product type / price facets of the result set.

**Parameters:**
- `query` (string, optional) — Search words as typed into Jarir's search box (English or Arabic). Optional when `product_type` or `brand` is given — then the whole product type / brand is listed. One of query, product_type or brand is required.
- `brand` (string, optional) — Brand exactly as Jarir names it (e.g. Apple, Samsung, Lenovo, HP). Several brands: comma-separated ("Lenovo,HP"). The result's `facets.brands` lists the names. An unknown brand returns 0 rows.
- `product_type` (string, optional) — Jarir's product type, e.g. Smartphones, Laptops, Tablets, Books, Smartwatches (see `facets.product_types` of any search). Several: comma-separated.
- `min_price` (number, optional) — Lowest price, in the storefront's currency (SAR for sa).
- `max_price` (number, optional) — Highest price, in the storefront's currency.
- `sort` (enum, optional, default "relevance") — Jarir's own orderings: relevance (default), price low→high, price high→low. [one of: relevance, price_asc, price_desc]
- `page` (integer, optional, default 1) — Result page, from 1.
- `page_size` (integer, optional, default 24) — Rows per page, 1-48 (default 24).
- `country` (enum, optional, default "sa") — Which Jarir storefront: Saudi Arabia (sa, default, prices in SAR), Kuwait (kw, KWD), Qatar (qa, QAR), UAE (ae, AED) or Bahrain (bh, BHD). Each is its own catalogue with its own prices and stock. [one of: sa, kw, qa, ae, bh]
- `lang` (enum, optional, default "en") — Language of names, specs and showroom names: English (en, default) or Arabic (ar). Jarir runs a separate catalogue per language. [one of: en, ar]

**Returns:** results[]{sku, name, url, brand, model, mpn, barcode, item_number, product_type, price, regular_price, discount_amount, discount_pct, source_discount_pct, special_price_from, special_price_to, price_ex_vat, currency, in_stock, sold_by (jarir|marketplace), seller_name, seller_id, installments{tabby,tamara}, promo_tagline, image, matched_by (keyword|semantic), catalogue_read} + total, page, pages, has_more, match_counts{keyword, semantic}, facets{brands[], product_types[], price_range}

**Example request body:**
```json
{
  "query": "iphone 17",
  "country": "sa"
}
```

### POST https://api.reefapi.com/jarir/v1/product — 3 credits
Full Jarir product by SKU: price the shopper pays, regular price, discount and its dates, price ex-VAT, currency, online stock quantity and status, showroom pickup, home delivery, cash on delivery, order cut-off, Tabby/Tamara eligibility, payment methods, seller (Jarir or the named marketplace seller), brand, model, MPN, barcode, the spec table with Jarir's labels, every variant (colour/capacity) with its own price and stock, categories, description, images, star rating and distribution.

**Parameters:**
- `sku` (string, required) — Jarir SKU exactly as a search row returns it: digits for Jarir's own items (666789), JPP-<digits> for marketplace offers, JPM<digits> for a product family. A jarir.com product URL is accepted too.
- `country` (enum, optional, default "sa") — Which Jarir storefront: Saudi Arabia (sa, default, prices in SAR), Kuwait (kw, KWD), Qatar (qa, QAR), UAE (ae, AED) or Bahrain (bh, BHD). Each is its own catalogue with its own prices and stock. [one of: sa, kw, qa, ae, bh]
- `lang` (enum, optional, default "en") — Language of names, specs and showroom names: English (en, default) or Arabic (ar). Jarir runs a separate catalogue per language. [one of: en, ar]

**Returns:** sku, type, parent_sku, name, url, brand, model, series, mpn, barcode, item_number, product_type, price, regular_price, discount_amount, discount_pct, source_discount_pct, special_price_from/to, price_ex_vat, currency, in_stock, stock{status, in_stock, available_qty, stock_qty_is_capped, preorder_qty, backorder_qty, showroom_pickup, ships_from}, max_order_qty, sold_by, seller_name, seller_id, home_delivery, showroom_pickup, cash_on_delivery, order_cut_off, returnable, installments, payment_methods[], promo_tagline, warranty_code, rating{average, count, distribution}, specs[]{code,label,value}, variants[]{sku,name,options,price,regular_price,in_stock,url}, categories[], short_description, description, weight, box_cm, origin_country, images[], video_url, updated_at

**Example request body:**
```json
{
  "sku": "666789",
  "country": "sa"
}
```

### POST https://api.reefapi.com/jarir/v1/reviews — 1 credit
Customer reviews Jarir publishes for a SKU (rating, title, text, reviewer's display name, date) plus the star distribution. Reviews are per SKU: each colour/capacity variant has its own.

**Parameters:**
- `sku` (string, required) — Jarir SKU exactly as a search row returns it: digits for Jarir's own items (666789), JPP-<digits> for marketplace offers, JPM<digits> for a product family. A jarir.com product URL is accepted too.
- `rating` (integer, optional) — Only reviews with this many stars (1-5).
- `country` (enum, optional, default "sa") — Which Jarir storefront: Saudi Arabia (sa, default, prices in SAR), Kuwait (kw, KWD), Qatar (qa, QAR), UAE (ae, AED) or Bahrain (bh, BHD). Each is its own catalogue with its own prices and stock. [one of: sa, kw, qa, ae, bh]
- `lang` (enum, optional, default "en") — Language of names, specs and showroom names: English (en, default) or Arabic (ar). Jarir runs a separate catalogue per language. [one of: en, ar]

**Returns:** results[]{review_id, rating, title, text, author, created_at, review_type, sku} + rating{average, count, distribution}

**Example request body:**
```json
{
  "sku": "666789",
  "country": "sa"
}
```

### POST https://api.reefapi.com/jarir/v1/store_stock — 2 credits
Showroom-by-showroom availability of a SKU in one country: every Jarir showroom with its availability (AVAILABLE / LIMITED / OUTOFSTOCK), city, address, opening hours, phone and coordinates.

**Parameters:**
- `sku` (string, required) — Jarir SKU exactly as a search row returns it: digits for Jarir's own items (666789), JPP-<digits> for marketplace offers, JPM<digits> for a product family. A jarir.com product URL is accepted too.
- `availability` (enum, optional) — Only showrooms in this state. [one of: available, limited, outofstock]
- `country` (enum, optional, default "sa") — Which Jarir storefront: Saudi Arabia (sa, default, prices in SAR), Kuwait (kw, KWD), Qatar (qa, QAR), UAE (ae, AED) or Bahrain (bh, BHD). Each is its own catalogue with its own prices and stock. [one of: sa, kw, qa, ae, bh]
- `lang` (enum, optional, default "en") — Language of names, specs and showroom names: English (en, default) or Arabic (ar). Jarir runs a separate catalogue per language. [one of: en, ar]

**Returns:** results[]{showroom_code, name, availability, city_code, address, opening_hours, phone, latitude, longitude} + counts{AVAILABLE, LIMITED, OUTOFSTOCK}

**Example request body:**
```json
{
  "sku": "666789",
  "country": "sa"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=jarir
- Human docs page: https://reefapi.com/docs/jarir
- Overview page: https://reefapi.com/jarir-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt