Careemnow Careem POS API

Can I push a full menu catalog through the Careem POS API?

Yes. PUT /catalogs accepts the full menu as a single payload and returns a request_id. Poll GET /catalogs/status/{request_id} for the upload result, then use PATCH /catalogs/{catalog_id}/items to flip individual items in or out of stock without re-sending the whole catalog.

How do I close a branch temporarily on the Careem SuperApp?

Call POST /branches/{branch_id}/visibility/status to toggle the branch on or off, or POST /branches/{branch_id}/visibility/status/expiries to set a closed window with a specific duration (for example, 30 minutes during a kitchen rush). Both endpoints affect what customers see in the SuperApp immediately.

What are the rate limits for the Careem POS API?

Careem documents rate limiting under the 'Auth rate limiting' tag of its API reference and applies per-client throttling at the gateway. The OpenAPI specification does not publish numeric limits; if you receive 429 responses, slow polling on /orders and back off on bulk catalog updates. Refer to the official Careem POS docs for the current numbers.

How do I receive new orders - webhook or polling?

The OpenAPI surface itself exposes order retrieval through GET /orders and GET /orders/{order_id}, suitable for polling. The Careem documentation also references catalog and order webhook events under the 'Order API webhook events' and 'Catalog API webhook events' tags; configure those out-of-band with Careem to receive push notifications instead of polling.

How do I accept an order through Jentic?

Run `pip install jentic`, then use Jentic's search to find the order-state operation with the query "update careem order state", load the schema, and execute with `{"order_id": "ORD-9001", "state": "accepted"}`. Jentic calls PUT /orders/{order_id} with a fresh OAuth token from the vault and returns Careem's confirmation.

Can I tag orders with my own POS reference?

Yes. PATCH /orders/{order_id}/tags accepts arbitrary metadata you can use to attach a local POS ticket number, kitchen station ID, or operator initials. This is the recommended way to keep Careem orders linked to your own systems for later reporting.

Can I limit what my agent is allowed to do with the Careem POS API?

Yes. Because you run Jentic One yourself, your own rules decide which Careem POS operations and credentials the agent can use, so you can grant it just GET /orders and PUT /orders/{order_id} while withholding PUT /catalogs and the branch visibility endpoints. Careem places the order, branch, and catalog IDs in the URL path (for example /orders/{order_id} and /branches/{branch_id}/visibility/status), so a rule can also pin the agent to a single branch for order reads and state updates. The OAuth client credentials stay with your instance and are never exposed to the agent, so it can only invoke the operations you have allowed.