Connect your website to Barrq with one API

The Barrq API lets a merchant's own website talk to Barrq server to server. Report each order and Barrq messages the customer on WhatsApp at every status change, in their language. Optionally, push your catalogue so the AI agent quotes your real prices and stock, and keep customers in step between your site and Barrq.

Base URL

https://app.barrq.co/api/v1

Format

JSON request and response bodies, UTF-8

Transport

HTTPS only, from your server — never from a browser

Version

v1 — additive changes only

1. 1

   Get your API key

   The store owner opens Barrq → Integrations → Website and creates the API key. Barrq shows a Key ID (bq_key_…) and a Secret (bq_secret_…). The Secret is shown once — store it in your server's secret manager.
2. 2

   Test the connection

   A GET /orders changes nothing and returns what the key may do.

   GET /orderscURLNode.jsPHPPython

   Copy

   curl https://app.barrq.co/api/v1/orders \
     -H "X-Barrq-Key: bq_key_YOUR_KEY_ID" \
     -H "X-Barrq-Secret: bq_secret_YOUR_SECRET"

3. 3

   Report your first order

   Send it when the order is placed, then again on every status change.

   POST /orderscURLNode.jsPHPPython

   Copy

   curl -X POST https://app.barrq.co/api/v1/orders \
     -H "X-Barrq-Key: bq_key_YOUR_KEY_ID" \
     -H "X-Barrq-Secret: bq_secret_YOUR_SECRET" \
     -H "Content-Type: application/json" \
     -d '{ "order_id": "10045", "status": "pending", "customer": { "name": "Sara Ahmed", "phone": "+201001234567", "email": "sara@example.com", "language": "ar" }, "currency": "EGP", "total": 1250, "items": [ { "name": "Rose face serum", "sku": "SER-01", "qty": 2, "price": 625 } ], "address": "12 Tahrir St, Cairo", "note": "Call before delivery" }'

Every request carries the Key ID and Secret as two headers. Requests without them, or with a revoked key, return 401.

X-Barrq-Key: bq_key_YOUR_KEY_ID
X-Barrq-Secret: bq_secret_YOUR_SECRET

HTTP Basic authentication also works: Authorization: Basic base64(keyId:secret).

Reporting orders is always allowed. Catalogue and customer access are off until the store owner enables them in Integrations → Website → Catalogue & customers API. Write access includes read access.

Once your site pushes products, Barrq stops reading the catalogue from your web pages: your API becomes the source of truth.

List endpoints take page and limit and return the total. Request the next page while has_more is true. For scheduled syncs, store the time of your last run and send it as updated_since.

{ "ok": true, "products": [ … ], "page": 1, "limit": 100, "total": 342, "has_more": true }

Errors are JSON with a message written for your logs, and a list of every problem when a body is invalid.

{
  "ok": false,
  "error": "Some products could not be read. Nothing was saved.",
  "details": ["products[1] (SOAP-01): \"price\" must be a number ≥ 0."]
}

Each key may make 120 requests per minute. Repeated failed authentication from one address is throttled too. A 429 carries a Retry-After header in seconds.

Every write is idempotent: orders are matched by order_id, products by sku, customers by phone or email. Retry on 429, 5xx and network errors with exponential back-off (for example 1s, 2s, 4s, up to 5 attempts).

The API is versioned in the path. Within v1 we only add — new endpoints, new optional fields, new response fields — so ignore fields you do not recognise. A breaking change would ship as v2, with v1 kept running and notice given well in advance.

• ✓The store owner created the API key and shared the Key ID and Secret privately.
• ✓Both values live in your server’s secrets, not in front-end code.
• ✓GET /orders returns ok: true with the access you expect.
• ✓Catalogue and/or Customers access is enabled, if you sync them.
• ✓Your site calls POST /orders on every new order and every status change.
• ✓Customer phones are sent in international format (+ and country code).
• ✓Bulk syncs use batches of up to 100 with retries on 429 and 5xx.
• ✓A test order to your own WhatsApp number produced a message for each status.